Skip to main content

Applications

Unit offers a short, low-friction, non-documentary application process - most applications will be approved in under five seconds. In some cases Unit detects an exception in the application process (e.g. a phone number mismatch), and certain documents are required in order to make a decision.

Unit will let you know exactly what documents to require from the customer, and once they are provided (via an API call), the application will either be approved automatically or manually reviewed by us (under an SLA of two business hours).

For more information on applications including specific details about application statuses and flow, see our End-Customer Applications Guide

Application Statuses

The final statuses for an application are Approved, Denied or Canceled. Once an application is approved, a Customer resource will be created and associated with the application resource. The new created customer resources will be referenced in the relationships object.

In most cases, an application will reach one of these final statuses immediately after creation, without requiring any documents.

In some cases, documents will be required and the application will enter an AwaitingDocuments status. Once you upload all the required documents, Unit will use the information provided to approve or deny the application. The decision may take seconds in some cases and up to two hours in other cases (when a manual review is required). Once the process is complete, you will receive a webhook containing the result.

An application can also be evaluated asynchronously, in which case its status will be Pending as long as the evaluation process is running. Once the process is complete, the status will change to either Approved, Denied or AwaitingDocuments and the relevant webhook event will be fired (see Pending status description below)

There is an option to Cancel Application at any point that is not Approved or Denied. The status of the application will change to Canceled, and the relevant webhook event will be fired.

Below is a diagram describing the lifecycle of an application:

Application workflow

Below are all application statuses and their descriptions:

StatusDescription
AwaitingDocumentsCertain documents are required for the process to continue. You may upload them via Upload Document.
PendingReviewThe application is pending review by Unit (with an SLA of 2 business hours).
PendingThe application is being evaluated asynchronously and a result should be available shortly. Listen for webhooks (application.denied, customer.created) and application.awaitingdocuments) for the final result, or periodically query the application with Get by Id).
ApprovedThe application was approved. A Customer resource was created.
DeniedThe application was denied. A Customer resource will not be created.
CanceledThe application was сanceled. A Customer resource will not be created.

Device Fingerprints

A Device fingerprint is a way to combine certain attributes of a device (operating system, IP address, device language settings etc.) in order to identify unique devices.

Unit partners with select providers to detect and prevent potential fraud. To enjoy improved protection, you must add the device fingerprint to new application.

Providers

NameDescription
IovationThe Iovation (TransUnion TruValidate) device fingerprint string is called a "blackbox", the blackbox can be generated using their Android SDK, iOS SDK, or Web SDK.

Create Individual Application

Create an application for an individual end-customer.

info

The SSN (or passport number, for non US citizens) is used as the unique identifier for an individual on Unit. The same identifier cannot be used to submit multiple applications. If an application for a certain individual has been denied, canceled or archived, they may use their SSN/passport number to reapply. Otherwise, duplicate applications will result in an HTTP error (400).

This functionality can be enabled/disabled on Unit dashboard at: Settings -> Org Settings -> General -> Prevent duplicate individual applications.

VerbPOST
Urlhttps://api.s.unit.sh/applications
Required Scopeapplications-write
Data TypeindividualApplication
Timeout (Seconds)120

Attributes

NameTypeDescription
ssnstringSSN (or ITIN) of the individual (numbers only). Either an ssn or passport is required. It is optional to provide only last 4 SSN digits.
passportstringPassport number of the individual. Valid only for non-US persons. Either an ssn or passport number is required.
nationalityISO31661-Alpha2 stringRequired if a passport is used as the main ID. Two letters representing the individual nationality. (e.g. "US").
fullNameFullNameFull name of the individual.
dateOfBirthRFC3339 Date stringDate only (e.g. "2001-08-15").
addressAddressAddress of the individual. Must be a US address.
phonePhonePhone number of the individual.
emailstringEmail address of the individual.
evaluationParamsEvaluationParamsOptional. Evaluation Params for this entity.
occupationOccupationOccupation of the individual.
annualIncomeAnnualIncomeRequired if nationality is not US. Annual income of the individual.
sourceOfIncomeSourceOfIncomeRequired if nationality is not US. Source of income of the individual.
ipstringOptional. IP address of the end-customer creating the application. Both IPv4 and IPv6 formats are supported. Highly recommended as a fraud prevention measure, if the information is available when submitting the application.
tagsobjectOptional. See Tags. Tags that will be copied to the customer that this application creates (see Tag Inheritance).
idempotencyKeystringOptional. See Idempotency.
deviceFingerprintsArray of Device FingerprintOptional. A list of device fingerprints for fraud and risk prevention (See Device Fingerprints).
jwtSubjectstringOptional. See this section for more information.
Example Request:
curl -X POST 'https://api.s.unit.sh/applications'
-H 'Content-Type: application/vnd.api+json'
-H 'Authorization: Bearer ${TOKEN}'
--data-raw '{
"data": {
"type": "individualApplication",
"attributes": {
"ssn": "721074426",
"fullName": {
"first": "Peter",
"last": "Parker"
},
"dateOfBirth": "2001-08-10",
"address": {
"street": "20 Ingram St",
"city": "Forest Hills",
"state": "NY",
"postalCode": "11375",
"country": "US"
},
"email": "peter@oscorp.com",
"phone": {
"countryCode": "1",
"number": "5555555555"
},
"ip": "127.0.0.2",
"occupation": "ArchitectOrEngineer",
"annualIncome": "Between50kAnd100k",
"sourceOfIncome": "EmploymentOrPayrollIncome",
"tags": {
"userId": "106a75e9-de77-4e25-9561-faffe59d7814"
},
"idempotencyKey": "3a1a33be-4e12-4603-9ed0-820922389fb8"
}
}
}'

Response

Response is a JSON:API document.

201 Created

FieldTypeDescription
dataIndividualApplicationThe newly created resource.
includedArray of ApplicationDocument ResourceRequired documents for this application. Each document resource includes the document status.
Example Response:
{
"data": {
"type": "individualApplication",
"id": "53",
"attributes": {
"createdAt": "2020-01-14T14:05:04.718Z",
"fullName": {
"first": "Peter",
"last": "Parker"
},
"ssn": "721074426",
"address": {
"street": "20 Ingram St",
"street2": null,
"city": "Forest Hills",
"state": "NY",
"postalCode": "11375",
"country": "US"
},
"dateOfBirth": "2001-08-10",
"email": "peter@oscorp.com",
"phone": {
"countryCode": "1",
"number": "5555555555"
},
"status": "AwaitingDocuments",
"ip": "127.0.0.2",
"occupation": "ArchitectOrEngineer",
"annualIncome": "Between50kAnd100k",
"sourceOfIncome": "EmploymentOrPayrollIncome",
"soleProprietorship": false,
"tags": {
"userId": "106a75e9-de77-4e25-9561-faffe59d7814"
},
"archived": false
},
"relationships": {
"org": {
"data": {
"type": "org",
"id": "1"
}
},
"documents": {
"data": [
{
"type": "document",
"id": "1"
},
{
"type": "document",
"id": "2"
}
]
}
}
},
"included": [
{
"type": "document",
"id": "1",
"attributes": {
"documentType": "AddressVerification",
"status": "Required",
"name": "Peter Parker",
"description": "Please provide a document to verify your address. Document may be a utility bill, bank statement, lease agreement or current pay stub.",
"address": {
"street": "20 Ingram St",
"street2": null,
"city": "Forest Hills",
"state": "NY",
"postalCode": "11375",
"country": "US"
}
}
},
{
"type": "document",
"id": "2",
"attributes": {
"documentType": "IdDocument",
"status": "Required",
"name": "Peter Parker",
"description": "Please provide a copy of your unexpired government issued photo ID which would include Drivers License or State ID.",
"dateOfBirth": "2001-08-10"
}
}
]
}

Create Sole Proprietor Application

Create an application for a sole proprietor.

info

A sole proprietorship is a type of enterprise owned and run by one person, and in which there is no legal distinction between the owner and the business entity. As such, it is evaluated as an individual, with the soleProprietorship attribute set to true

info

The SSN (or passport number, for non US citizens) is used as the unique identifier for an individual on Unit. The same identifier cannot be used to submit multiple applications. If an application for a certain individual has been denied, canceled or archived, they may use their SSN/passport number to reapply. Otherwise, duplicate applications will result in an HTTP error (400).

This functionality can be enabled/disabled on Unit dashboard at: Settings -> Org Settings -> General -> Prevent duplicate individual applications.

VerbPOST
Urlhttps://api.s.unit.sh/applications
Required Scopeapplications-write
Data TypeindividualApplication
Timeout (Seconds)120

Attributes

NameTypeDescription
ssnstringSSN (or ITIN) of the individual (numbers only). Either an ssn or passport is required.
passportstringPassport number of the individual. Valid only for non-US persons. Either an ssn or passport number is required.
nationalityISO31661-Alpha2 stringRequired if a passport is used as the main ID. Two letters representing the individual nationality. (e.g. "US").
fullNameFullNameFull name of the individual.
dateOfBirthRFC3339 Date stringDate only (e.g. "2001-08-15").
addressAddressAddress of the individual. Must be a US address.
phonePhonePhone number of the individual.
emailstringEmail address of the individual.
soleProprietorshipbooleanSet this to true in order to indicate that the individual is a sole proprietor.
einstringOptional. If the individual is a sole proprietor who has an Employer Identification Number, specify it here. Not all sole proprietors have an EIN, so this attribute is optional, even when soleProprietorship is set to true.
dbastringOptional. If the individual is a sole proprietor who is doing business under a different name, specify it here. This attribute is optional, even when soleProprietorship is set to true.
evaluationParamsEvaluationParamsOptional. Evaluation Params for this entity.
annualRevenueAnnualRevenueRequired if nationality is not US. For sole proprietors, specify the annual revenue here.
numberOfEmployeesNumberOfEmployeesRequired if nationality is not US. For sole proprietors, specify the number of employees here.
businessVerticalBusinessVerticalFor sole proprietors, specify the business vertical here.
websitestringA Valid website Url. Providing a null value is indicative of the business customer attesting that they do not have a website.
ipstringOptional. IP address of the end-customer creating the application. Both IPv4 and IPv6 formats are supported. Highly recommended as a fraud prevention measure, if the information is available when submitting the application.
tagsobjectOptional. See Tags. Tags that will be copied to the customer that this application creates (see Tag Inheritance).
idempotencyKeystringOptional. See Idempotency.
deviceFingerprintsArray of Device FingerprintOptional. A list of device fingerprints for fraud and risk prevention (See Device Fingerprints).
jwtSubjectstringOptional. See this section for more information.
Example Request:
curl -X POST 'https://api.s.unit.sh/applications'
-H 'Content-Type: application/vnd.api+json'
-H 'Authorization: Bearer ${TOKEN}'
--data-raw '{
"data": {
"type": "individualApplication",
"attributes": {
"ssn": "721074426",
"fullName": {
"first": "Peter",
"last": "Parker"
},
"dateOfBirth": "2001-08-10",
"address": {
"street": "20 Ingram St",
"city": "Forest Hills",
"state": "NY",
"postalCode": "11375",
"country": "US"
},
"email": "peter@oscorp.com",
"phone": {
"countryCode": "1",
"number": "5555555555"
},
"ip": "127.0.0.2",
"soleProprietorship": true,
"ein": "123456789",
"dba": "Piedpiper Inc",
"businessVertical": "TechnologyMediaOrTelecom",
"numberOfEmployees": "Between5And10",
"website": "https://www.piedpiper.com",
"tags": {
"userId": "106a75e9-de77-4e25-9561-faffe59d7814"
},
"idempotencyKey": "3a1a33be-4e12-4603-9ed0-820922389fb8"
}
}
}'

Response

Response is a JSON:API document.

201 Created

FieldTypeDescription
dataIndividualApplicationThe newly created resource.
includedArray of ApplicationDocument ResourceRequired documents for this application. Each document resource includes the document status.
Example Response:
{
"data": {
"type": "individualApplication",
"id": "53",
"attributes": {
"createdAt": "2020-01-14T14:05:04.718Z",
"fullName": {
"first": "Peter",
"last": "Parker"
},
"ssn": "721074426",
"address": {
"street": "20 Ingram St",
"street2": null,
"city": "Forest Hills",
"state": "NY",
"postalCode": "11375",
"country": "US"
},
"dateOfBirth": "2001-08-10",
"email": "peter@oscorp.com",
"phone": {
"countryCode": "1",
"number": "5555555555"
},
"status": "AwaitingDocuments",
"ip": "127.0.0.2",
"soleProprietorship": true,
"ein": "123456789",
"dba": "Piedpiper Inc",
"occupation": "ArchitectOrEngineer",
"annualIncome": "Between50kAnd100k",
"sourceOfIncome": "EmploymentOrPayrollIncome",
"annualRevenue": "Between100kAnd200k",
"numberOfEmployees": "Between5And10",
"businessVertical": "TechnologyMediaOrTelecom",
"website": "https://www.piedpiper.com",
"tags": {
"userId": "106a75e9-de77-4e25-9561-faffe59d7814"
},
"archived": false
},
"relationships": {
"org": {
"data": {
"type": "org",
"id": "1"
}
},
"documents": {
"data": [
{
"type": "document",
"id": "1"
},
{
"type": "document",
"id": "2"
}
]
}
}
},
"included": [
{
"type": "document",
"id": "1",
"attributes": {
"documentType": "AddressVerification",
"status": "Required",
"name": "Peter Parker",
"description": "Please provide a document to verify your address. Document may be a utility bill, bank statement, lease agreement or current pay stub.",
"address": {
"street": "20 Ingram St",
"street2": null,
"city": "Forest Hills",
"state": "NY",
"postalCode": "11375",
"country": "US"
}
}
},
{
"type": "document",
"id": "2",
"attributes": {
"documentType": "IdDocument",
"status": "Required",
"name": "Peter Parker",
"description": "Please provide a copy of your unexpired government issued photo ID which would include Drivers License or State ID.",
"dateOfBirth": "2001-08-10"
}
}
]
}

Create Business Application

Create an application for a business end-customer.

info

Companies that are publicly traded in a major US stock exchange are subject to lighter onboarding requirements. If your customer base includes publicly traded companies, please reach out to Unit for additional information.

VerbPOST
Urlhttps://api.s.unit.sh/applications
Required Scopeapplications-write
Data TypebusinessApplication
Timeout (Seconds)120

Attributes

NameTypeDescription
namestringName of the business.
dbastringOptional. "Doing business as".
addressAddressAddress of the business. Must be a US address
phonePhonePhone number of the business.
stateOfIncorporationstringTwo letters representing a US state.
einstringBusiness EIN (numbers only).
entityTypestringOne of LLC, Partnership, PubliclyTradedCorporation, PrivatelyHeldCorporation or NotForProfitOrganization.
websitestringA Valid website Url. Providing a null value is indicative of the business customer attesting that they do not have a website.
contactBusinessContactPrimary contact of the business. This person is the one that will have access to the account.
officerOfficerOfficer representing the business (must be the CEO, COO, CFO, President, BenefitsAdministrationOfficer, CIO, VP, AVP, Treasurer, Secretary, Controller, Manager, Partner or Member). To onboard a business successfully, you must provide the officer's personal details.
beneficialOwnersArray of BeneficialOwnerArray of beneficial owners in the business. Beneficial owners are all people that, directly or indirectly, own 25% or more of the business. To onboard a business successfully, you must provide each beneficial owner's personal details. If the business has no beneficial owners, the array should be empty.
annualRevenueAnnualRevenueRequired if any of the officer / BeneficialOwner of the business have a non US nationality. Annual revenue of the business.
numberOfEmployeesNumberOfEmployeesRequired if any of the officer / BeneficialOwner of the business have a non US nationality. Number of employees of the business.
cashFlowCashFlowRequired if any of the officer / BeneficialOwner of the business have a non US nationality. Cash flow of the business.
yearOfIncorporationYear stringYear of incorporation of the business.
countriesOfOperationArray of ISO31661-Alpha2 stringsRequired if any of the officer / BeneficialOwner of the business have a non US nationality. An array of two letter codes representing the countries of operation of the business.
stockSymbolstringOptional. The stock symbol (ticker) of the business.
businessVerticalBusinessVerticalThe business vertical of the business.
ipstringOptional. IP address of the end-customer creating the application. Both IPv4 and IPv6 formats are supported. Highly recommended as a fraud prevention measure, if the information is available when submitting the application.
tagsobjectOptional. See Tags. Tags that will be copied to the customer that this application creates (see Tag Inheritance).
idempotencyKeystringOptional. See Idempotency.
deviceFingerprintsArray of Device FingerprintOptional. A list of device fingerprints for fraud and risk prevention (See Device Fingerprints).
Example Request:
curl -X POST 'https://api.s.unit.sh/applications'
-H 'Content-Type: application/vnd.api+json'
-H 'Authorization: Bearer ${TOKEN}'
--data-raw '{
"data": {
"type": "businessApplication",
"attributes": {
"name": "Pied Piper",
"address": {
"street": "5230 Newell Rd",
"city": "Palo Alto",
"state": "CA",
"postalCode": "94303",
"country": "US"
},
"phone": {
"countryCode": "1",
"number": "5555555555"
},
"stateOfIncorporation": "DE",
"ein": "123456789",
"entityType": "Corporation",
"ip": "127.0.0.2",
"annualRevenue": "Between500kAnd1m",
"numberOfEmployees": "Between50And100",
"cashFlow": "Predictable",
"yearOfIncorporation": "2014",
"countriesOfOperation": [
"US",
"CA"
],
"stockSymbol": "PPI",
"businessVertical": "TechnologyMediaOrTelecom",
"website": "https://www.piedpiper.com",
"contact": {
"fullName": {
"first": "Richard",
"last": "Hendricks"
},
"email": "richard@piedpiper.com",
"phone": {
"countryCode": "1",
"number": "5555555555"
}
},
"officer": {
"fullName": {
"first": "Richard",
"last": "Hendricks"
},
"dateOfBirth": "2001-08-10",
"title": "CEO",
"ssn": "721074426",
"email": "richard@piedpiper.com",
"phone": {
"countryCode": "1",
"number": "5555555555"
},
"address": {
"street": "5230 Newell Rd",
"city": "Palo Alto",
"state": "CA",
"postalCode": "94303",
"country": "US"
},
"occupation": "ArchitectOrEngineer",
"annualIncome": "Between50kAnd100k",
"sourceOfIncome": "EmploymentOrPayrollIncome"
},
"beneficialOwners": [
{
"fullName": {
"first": "Richard",
"last": "Hendricks"
},
"dateOfBirth": "2001-08-10",
"ssn": "123456789",
"email": "richard@piedpiper.com",
"percentage": 75,
"phone": {
"countryCode": "1",
"number": "5555555555"
},
"address": {
"street": "5230 Newell Rd",
"city": "Palo Alto",
"state": "CA",
"postalCode": "94303",
"country": "US"
},
"occupation": "ArchitectOrEngineer",
"annualIncome": "Between50kAnd100k",
"sourceOfIncome": "EmploymentOrPayrollIncome"
}
],
"tags": {
"userId": "2ab1f266-04b9-41fb-b728-cd1962bca52c"
},
"idempotencyKey": "3a1a33be-4e12-4603-9ed0-820922389fb8"
}
}
}'

Response

Response is a JSON:API document.

201 Created

FieldTypeDescription
dataBusinessApplicationThe newly created resource.
relationshipsJSON:API RelationshipsDescribes relationships between the application resource and other resources (beneficial owners).
includedArray of ApplicationDocument Resource or BeneficialOwner ResourceRequired documents for this application. Each document resource includes the document status. List of the application's beneficial owners.
Example Response:
{
"data": {
"type": "businessApplication",
"id": "50",
"attributes": {
"createdAt": "2020-01-13T16:01:19.346Z",
"name": "Pied Piper",
"dba": null,
"address": {
"street": "5230 Newell Rd",
"street2": null,
"city": "Palo Alto",
"state": "CA",
"postalCode": "94303",
"country": "US"
},
"phone": {
"countryCode": "1",
"number": "5555555555"
},
"stateOfIncorporation": "DE",
"ein": "123456789",
"entityType": "Corporation",
"ip": "127.0.0.2",
"website": "https://www.piedpiper.com",
"annualRevenue": "Between500kAnd1m",
"numberOfEmployees": "Between50And100",
"cashFlow": "Predictable",
"yearOfIncorporation": "2014",
"countriesOfOperation": [
"US",
"CA"
],
"stockSymbol": "PPI",
"businessVertical": "TechnologyMediaOrTelecom",
"contact": {
"fullName": {
"first": "Richard",
"last": "Hendricks"
},
"email": "richard@piedpiper.com",
"phone": {
"countryCode": "1",
"number": "5555555555"
}
},
"officer": {
"fullName": {
"first": "Richard",
"last": "Hendricks"
},
"ssn": "123456789",
"address": {
"street": "5230 Newell Rd",
"street2": null,
"city": "Palo Alto",
"state": "CA",
"postalCode": "94303",
"country": "US"
},
"dateOfBirth": "2001-08-10",
"title": "CEO",
"email": "richard@piedpiper.com",
"phone": {
"countryCode": "1",
"number": "5555555555"
},
"occupation": "ArchitectOrEngineer",
"annualIncome": "Between50kAnd100k",
"sourceOfIncome": "EmploymentOrPayrollIncome",
"status": "Approved"
},
"beneficialOwners": [
{
"fullName": {
"first": "Richard",
"last": "Hendricks"
},
"ssn": "123456789",
"address": {
"street": "5230 Newell Rd",
"street2": null,
"city": "Palo Alto",
"state": "CA",
"postalCode": "94303",
"country": "US"
},
"dateOfBirth": "2001-08-10",
"phone": {
"countryCode": "1",
"number": "5555555555"
},
"email": "richard@piedpiper.com",
"percentage": 75,
"status": "Approved"
}
],
"tags": {
"userId": "2ab1f266-04b9-41fb-b728-cd1962bca52c"
},
"archived": false,
"status": "AwaitingDocuments"
},
"relationships": {
"org": {
"data": {
"type": "org",
"id": "1"
}
},
"documents": {
"data": [
{
"type": "document",
"id": "1"
},
{
"type": "document",
"id": "2"
},
{
"type": "document",
"id": "3"
}
]
}
}
},
"included": [
{
"type": "document",
"id": "1",
"attributes": {
"documentType": "CertificateOfIncorporation",
"status": "Required",
"name": "Pied Piper",
"description": "For Corporation: Please provide a certified copy of the Articles of Incorporation or Certificate of Incorporation..."
}
},
{
"type": "document",
"id": "2",
"attributes": {
"documentType": "AddressVerification",
"status": "Required",
"name": "Richard Hendricks",
"description": "Please provide a document to verify your address. Document may be a utility bill, bank statement, lease agreement or current pay stub.",
"address": {
"street": "5230 Newell Rd",
"street2": null,
"city": "Palo Alto",
"state": "CA",
"postalCode": "94303",
"country": "US"
}
}
},
{
"type": "document",
"id": "3",
"attributes": {
"documentType": "IdDocument",
"status": "Required",
"name": "Richard Hendricks",
"description": "Please provide a copy of your unexpired government issued photo ID which would include Drivers License or State ID."
}
}
]
}

Create Trust Application

note

Trust applications are not enabled by default. To enable them, please contact Unit support.

Create an application for a trust end-customer.

VerbPOST
Urlhttps://api.s.unit.sh/applications
Required Scopeapplications-write
Data TypetrustApplication
Timeout (Seconds)120

Attributes

NameTypeDescription
namestringName of the business.
stateOfIncorporationstringTwo letters representing a US state.
revocabilityEither Revocable or IrrevocableWhether the trust can be changed or canceled after the trust document has been signed.
sourceOfFundsOne of Inheritance, Salary, Savings, InvestmentReturns, GiftsOrigin of the funds used to fund the account.
taxIdstringThe grantor's SSN.
grantorGrantorThe individual that creates the trust.
trusteesArray of TrusteeList of individual who take legal ownership of the assets held by the trust.
beneficiariesArray of BeneficiaryList of individuals for whom the trust is created.
contactTrustContactPrimary contact of the trust. This person is the one that will have access to the account.
ipstringOptional. IP address of the end-customer creating the application. Both IPv4 and IPv6 formats are supported. Highly recommended as a fraud prevention measure, if the information is available when submitting the application.
tagsobjectOptional. See Tags. Tags that will be copied to the customer that this application creates (see Tag Inheritance).
idempotencyKeystringOptional. See Idempotency.
deviceFingerprintsArray of Device FingerprintOptional. A list of device fingerprints for fraud and risk prevention (See Device Fingerprints).
Example Request:
curl -X POST 'https://api.s.unit.sh/applications'
-H 'Content-Type: application/vnd.api+json'
-H 'Authorization: Bearer ${TOKEN}'
--data-raw '{
"data": {
"type": "trustApplication",
"attributes": {
"name": "Trust me Inc.",
"stateOfIncorporation": "CA",
"revocability": "Revocable",
"sourceOfFunds": "Salary",
"taxId": "123456789",
"trustees": [
{
"fullName": {
"first": "Richard",
"last": "Hendricks"
},
"dateOfBirth": "2000-01-01",
"ssn": "000000002",
"email": "richard@piedpiper.com",
"phone": {
"countryCode": "1",
"number": "2025550108"
},
"address": {
"street": "5230 Newell Rd",
"city": "Palo Alto",
"state": "CA",
"postalCode": "94303",
"country": "US"
}
}
],
"contact": {
"fullName": {
"first": "Jared",
"last": "Dunn"
},
"email": "jared@piedpiper.com",
"phone": {
"countryCode": "1",
"number": "2025550108"
},
"address": {
"street": "5230 Newell Rd",
"city": "Palo Alto",
"state": "CA",
"postalCode": "94303",
"country": "US"
}
},
"grantor": {
"fullName": {
"first": "Laurie",
"last": "Bream"
},
"dateOfBirth": "2000-01-01",
"ssn": "000000003",
"email": "laurie@raviga.com",
"phone": {
"countryCode": "1",
"number": "2025550108"
},
"address": {
"street": "950 Allerton Street",
"city": "Redwood City",
"state": "CA",
"postalCode": "94063",
"country": "US"
}
},
"tags": {
"test": "test1"
},
"beneficiaries": [
{
"fullName": {
"first": "Dinesh",
"last": "Chugtai"
},
"dateOfBirth": "2000-01-01"
},
{
"fullName": {
"first": "Gilfoyle",
"last": "Unknown"
},
"dateOfBirth": "2000-01-01"
}
]
}
}
}'

Response

Response is a JSON:API document.

201 Created

FieldTypeDescription
dataTrustApplicationThe newly created resource.
includedArray of ApplicationDocument ResourceRequired documents for this application. Each document resource includes the document status.
Example Response:
{
"data": {
"type": "trustApplication",
"id": "100",
"attributes": {
"createdAt": "2022-03-31T14:28:08.235Z",
"name": "Trust me Inc.",
"contact": {
"fullName": {
"first": "Jared",
"last": "Dunn"
},
"email": "jared@piedpiper.com",
"phone": {
"countryCode": "1",
"number": "2025550108"
},
"address": {
"street": "5230 Newell Rd",
"city": "Palo Alto",
"state": "CA",
"postalCode": "94303",
"country": "US"
}
},
"status": "AwaitingDocuments",
"stateOfIncorporation": "CA",
"revocability": "Revocable",
"sourceOfFunds": "Salary",
"grantor": {
"status": "PendingReview",
"fullName": {
"first": "Laurie",
"last": "Bream"
},
"ssn": "000000003",
"address": {
"street": "950 Allerton Street",
"city": "Redwood City",
"state": "CA",
"postalCode": "94063",
"country": "US"
},
"dateOfBirth": "2000-01-01",
"email": "laurie@raviga.com",
"phone": {
"countryCode": "1",
"number": "2025550108"
}
},
"tags": {
"test": "test1"
},
"archived": false
},
"relationships": {
"org": {
"data": {
"type": "org",
"id": "1"
}
},
"trustees": {
"data": [
{
"type": "trustee",
"id": "13"
}
]
},
"beneficiaries": {
"data": [
{
"type": "beneficiary",
"id": "21"
},
{
"type": "beneficiary",
"id": "22"
}
]
},
"documents": {
"data": [
{
"type": "document",
"id": "179"
},
{
"type": "document",
"id": "180"
},
{
"type": "document",
"id": "181"
}
]
}
}
},
"included": [
{
"id": "179",
"type": "document",
"attributes": {
"documentType": "AddressVerification",
"status": "Required",
"description": "Please provide a document to verify your address. Document may be a utility bill, bank statement, lease agreement or current pay stub.",
"name": "Richard Hendricks",
"address": {
"street": "5230 Newell Rd",
"city": "Palo Alto",
"state": "CA",
"postalCode": "94303",
"country": "US"
}
}
},
{
"id": "180",
"type": "document",
"attributes": {
"documentType": "IdDocument",
"status": "Required",
"description": "Please provide a copy of your unexpired government issued photo ID which would include Drivers License or State ID.",
"ssn": "000000003",
"name": "Laurie Bream",
"dateOfBirth": "2000-01-01"
}
},
{
"id": "181",
"type": "document",
"attributes": {
"documentType": "TrustDocument",
"status": "Required",
"description": "Please provide a document verifying your Trust",
"name": "Trust me Inc."
}
}
]
}

Cancel Application

Cancel an Application under PendingReview Pending or AwaitingDocuments status. The application.canceled webhook event will be fired.

VerbPOST
Urlhttps://api.s.unit.sh/applications/{id}/cancel
Data TypeapplicationCancel
Timeout (Seconds)5

Response

Response is a JSON:API document.

201 Created

FieldTypeDescription
dataIndividualApplication, BusinessApplication or TrustApplicationApplication resource. Can be business, individual or trust, as indicated by the type field.
includedArray of ApplicationDocument ResourceApplication required documents, each document object also includes the document status.
Example Request:
curl -X POST 'https://api.s.unit.sh/applications/10001/cancel'
-H 'Content-Type: application/vnd.api+json'
-H 'Authorization: Bearer ${TOKEN}'
--data-raw '{
"data": {
"type": "applicationCancel",
"attributes": {
"reason": "By Org"
}
}
}'

Get by Id

Get an application resource by id.

VerbGET
Urlhttps://api.s.unit.sh/applications/{id}
Required Scopeapplications
Timeout (Seconds)5

Response

Response is a JSON:API document.

200 OK

FieldTypeDescription
dataIndividualApplication, BusinessApplication or TrustApplicationApplication resource. Can be business, individual or trust, as indicated by the type field.
includedArray of ApplicationDocument Resource or BeneficialOwner ResourceRequired documents for this application. Each document resource includes the document status. List of the application's beneficial owners.
curl -X GET 'https://api.s.unit.sh/applications/43' \
-H "Authorization: Bearer ${TOKEN}"

List

List application resources. Paging can be applied.

VerbGET
Urlhttps://api.s.unit.sh/applications
Required Scopeapplications
Timeout (Seconds)5

Query Parameters

NameTypeDefaultDescription
page[limit]integer100Optional. Maximum number of resources that will be returned. Maximum is 1000 resources. See Pagination.
page[offset]integer0Optional. Number of resources to skip. See Pagination.
filter[query]string(empty)Optional. Search term according to the Full-Text Search Rules.
filter[status][]string(empty)Optional. Filter applications by Application Status. Usage example: filter[status][0]=Pending&filter[status][1]=Approved
filter[email]string(empty)Optional. Filter applications by email address (case sensitive).
filter[tags]Tags (JSON)(empty)Optional. Filter Applications by Tags.
sortstringsort=-createdAtOptional. sort=createdAt for ascending order or sort=-createdAt (leading minus sign) for descending order.
curl -X GET 'https://api.s.unit.sh/applications?page[limit]=20&page[offset]=10' \
-H "Authorization: Bearer ${TOKEN}"

Response

Response is a JSON:API document.

200 OK

FieldTypeDescription
dataArray of IndividualApplication, BusinessApplication or TrustApplicationArray of application resources. Each resource can be business, individual or trust, as indicated by the type field.
metaJSON object that contains pagination dataPagination data includes offset, limit and total (total items).
Example Response:
{
"data": [
{
"type": "individualApplication",
"id": "1",
"attributes": {
"createdAt": "2020-01-15T13:47:36.098Z",
"fullName": {
"first": "Peter",
"last": "Parker"
},
"ssn": "721074426",
"address": {
"street": "20 Ingram St",
"street2": null,
"city": "Forest Hills",
"state": "NY",
"postalCode": "11375",
"country": "US"
},
"dateOfBirth": "2001-08-10",
"email": "peter@oscorp.com",
"phone": {
"countryCode": "1",
"number": "5555555555"
},
"status": "AwaitingDocuments",
"archived": false,
"message": "Waiting for you to upload the required documents."
},
"relationships": {
"org": {
"data": {
"type": "org",
"id": "1"
}
},
"documents": {
"data": [
{
"type": "document",
"id": "1"
},
{
"type": "document",
"id": "2"
}
]
}
}
},
{
"type": "businessApplication",
"id": "2",
"attributes": {
"createdAt": "2020-01-15T13:48:38.527Z",
"name": "Pied Piper",
"dba": null,
"address": {
"street": "5230 Newell Rd",
"street2": null,
"city": "Palo Alto",
"state": "CA",
"postalCode": "94303",
"country": "US"
},
"phone": {
"countryCode": "1",
"number": "5555555555"
},
"stateOfIncorporation": "DE",
"ein": "123456789",
"entityType": "Corporation",
"contact": {
"fullName": {
"first": "Richard",
"last": "Hendricks"
},
"email": "richard@piedpiper.com",
"phone": {
"countryCode": "1",
"number": "5555555555"
}
},
"officer": {
"fullName": {
"first": "Richard",
"last": "Hendricks"
},
"ssn": "123456789",
"address": {
"street": "5230 Newell Rd",
"street2": null,
"city": "Palo Alto",
"state": "CA",
"postalCode": "94303",
"country": "US"
},
"dateOfBirth": "2001-08-10",
"email": "richard@piedpiper.com",
"phone": {
"countryCode": "1",
"number": "5555555555"
},
"status": "Approved"
},
"beneficialOwners": [
{
"fullName": {
"first": "Richard",
"last": "Hendricks"
},
"ssn": "123456789",
"address": {
"street": "5230 Newell Rd",
"street2": null,
"city": "Palo Alto",
"state": "CA",
"postalCode": "94303",
"country": "US"
},
"dateOfBirth": "2001-08-10",
"phone": {
"countryCode": "1",
"number": "5555555555"
},
"email": "richard@piedpiper.com",
"status": "Approved"
}
],
"archived": false,
"status": "AwaitingDocuments",
"message": "Waiting for you to upload the required documents."
},
"relationships": {
"org": {
"data": {
"type": "org",
"id": "1"
}
},
"documents": {
"data": [
{
"type": "document",
"id": "1"
},
{
"type": "document",
"id": "2"
},
{
"type": "document",
"id": "3"
}
]
}
}
}
],
"meta": {
"pagination": {
"total": 2,
"limit": 100,
"offset": 0
}
}
}

Update Business

Update a business application.

note

Tags that are updated after the application has been approved will not be inherited by the corresponded customer resource.

VerbPATCH
Urlhttps://api.s.unit.sh/applications/:id
Required Scopeapplications-write
Timeout (Seconds)5

Attributes

NameTypeDescription
tagsobjectSee Updating Tags.
annualRevenueAnnualRevenueOptional. Annual revenue of the business.
numberOfEmployeesNumberOfEmployeesOptional. Number of employees of the business.
cashFlowCashFlowOptional. Cash flow of the business.
yearOfIncorporationYear stringOptional. Year of incorporation of the business.
countriesOfOperationArray of ISO31661-Alpha2 stringsOptional. An array of two letter codes representing the countries of operation of the business.
stockSymbolstringOptional. The stock symbol (ticker) of the business.
websitestringOptional. A Valid website Url.
businessVerticalBusinessVerticalOptional. The business vertical of the business.

Response

Response is a JSON:API document.

200 OK

FieldTypeDescription
dataBusinessApplicationThe updated BusinessApplication resource.
relationshipsJSON:API RelationshipsDescribes relationships between the application resource and other resources (beneficial owners).
includedArray of ApplicationDocument Resource or BeneficialOwner ResourceRequired documents for this application. Each document resource includes the document status. List of the application's beneficial owners.
Update business application:
curl -X PATCH 'https://api.s.unit.sh/application/:id'
-H 'Content-Type: application/vnd.api+json'
-H 'Authorization: Bearer ${TOKEN}'
--data-raw '{
"data": {
"type": "businessApplication",
"attributes": {
"tags": {
"by": "Richard Hendricks",
"id": "23033b64-38f8-4dbc-91a1-313ff0156d02"
},
"annualRevenue": "Between500kAnd1m",
"numberOfEmployees": "Between50And100",
"cashFlow": "Predictable",
"yearOfIncorporation": "2014",
"countriesOfOperation": [
"US",
"CA"
],
"stockSymbol": "PPI",
"businessVertical": "TechnologyMediaOrTelecom"
}
}
}'

Update Business Officer

Update a business application's officer.

VerbPATCH
Urlhttps://api.s.unit.sh/applications/:id
Required Scopeapplications-write
Timeout (Seconds)5

Attributes

NameTypeDescription
officer.occupationOccupationOptional. Occupation of the officer.
officer.annualIncomeAnnualIncomeOptional. Annual income of the officer.
officer.sourceOfIncomeSourceOfIncomeOptional. Source of income of the officer.

Response

Response is a JSON:API document.

200 OK

FieldTypeDescription
dataBusinessApplicationThe updated BusinessApplication resource.
relationshipsJSON:API RelationshipsDescribes relationships between the application resource and other resources (beneficial owners).
includedArray of ApplicationDocument Resource or BeneficialOwner ResourceRequired documents for this application. Each document resource includes the document status. List of the application's beneficial owners.
Update business application officer:
curl -X PATCH 'https://api.s.unit.sh/application/:id'
-H 'Content-Type: application/vnd.api+json'
-H 'Authorization: Bearer ${TOKEN}'
--data-raw '{
"data": {
"type": "businessApplication",
"attributes": {
"officer": {
"occupation": "ArchitectOrEngineer",
"annualIncome": "Between10kAnd25k",
"sourceOfIncome": "EmploymentOrPayrollIncome"
}
}
}
}'

Update Business Beneficial Owner

Update a business application's beneficial owner. The application id associated with the beneficial owner must be passed as a relationship in the request body.

VerbPATCH
Urlhttps://api.s.unit.sh/beneficial-owner/:id
Required Scopeapplications-write
Timeout (Seconds)5

Attributes

NameTypeDescription
occupationOccupationOptional. Occupation of the beneficial owner.
annualIncomeAnnualIncomeOptional. Annual income of the beneficial owner.
sourceOfIncomeSourceOfIncomeOptional. Source of income of the beneficial owner.

Response

Response is a JSON:API document.

200 OK

FieldTypeDescription
dataBeneficialOwnerThe updated BeneficialOwner resource.
Update business application beneficial owner:
curl -X PATCH 'https://api.s.unit.sh/beneficial-owner/:id'
-H 'Content-Type: application/vnd.api+json'
-H 'Authorization: Bearer ${TOKEN}'
--data-raw '{
"data": {
"type": "beneficialOwner",
"attributes": {
"occupation": "ArchitectOrEngineer",
"annualIncome": "Between10kAnd25k",
"sourceOfIncome": "EmploymentOrPayrollIncome"
},
"relationships": {
"application": {
"data": {
"type": "businessApplication",
"id": "10001"
}
}
}
}
}'

Update Individual

Update an individual application.

note

Tags that are updated after the application has been approved will not be inherited by the corresponded customer resource.

VerbPATCH
Urlhttps://api.s.unit.sh/applications/:id
Required Scopeapplications-write
Timeout (Seconds)5

Attributes

NameTypeDescription
tagsobjectSee Updating Tags.
occupationOccupationOptional. Occupation of the individual.
annualIncomeAnnualIncomeOptional. Annual income of the individual.
sourceOfIncomeSourceOfIncomeOptional. Source of income of the individual.

Response

Response is a JSON:API document.

200 OK

FieldTypeDescription
dataIndividualApplicationThe updated IndividualApplication resource.
Update individual application:
curl -X PATCH 'https://api.s.unit.sh/application/:id'
-H 'Content-Type: application/vnd.api+json'
-H 'Authorization: Bearer ${TOKEN}'
--data-raw '{
"data": {
"type": "individualApplication",
"attributes": {
"tags": {
"by": "Richard Hendricks",
"id": "23033b64-38f8-4dbc-91a1-313ff0156d02"
},
"occupation": "ArchitectOrEngineer",
"annualIncome": "Between10kAnd25k",
"sourceOfIncome": "EmploymentOrPayrollIncome"
}
}
}'

Update Sole Proprietor

Update a sole-proprietorship application.

note

Tags that are updated after the application has been approved will not be inherited by the corresponded customer resource.

VerbPATCH
Urlhttps://api.s.unit.sh/applications/:id
Required Scopeapplications-write
Timeout (Seconds)5

Attributes

NameTypeDescription
tagsobjectSee Updating Tags.
annualRevenueAnnualRevenueOptional. Specify the annual revenue here.
numberOfEmployeesNumberOfEmployeesOptional. Specify the number of employees here.
businessVerticalBusinessVerticalOptional. Specify the business vertical here.
websitestringOptional. Specify the business website here.

Response

Response is a JSON:API document.

200 OK

FieldTypeDescription
dataIndividualApplicationThe updated IndividualApplication resource.
Update sole-proprietor application:
curl -X PATCH 'https://api.s.unit.sh/application/:id'
-H 'Content-Type: application/vnd.api+json'
-H 'Authorization: Bearer ${TOKEN}'
--data-raw '{
"data": {
"type": "individualApplication",
"attributes": {
"tags": {
"by": "Richard Hendricks",
"id": "23033b64-38f8-4dbc-91a1-313ff0156d02"
},
"annualRevenue": "UpTo50k",
"numberOfEmployees": "Between2And5",
"businessVertical": "BusinessSupportOrBuildingServices",
"website": "https://unit.co"
}
}
}'

Update Trust

Update a trust application.

note

Tags that are updated after the application has been approved will not be inherited by the corresponded customer resource.

VerbPATCH
Urlhttps://api.s.unit.sh/applications/:id
Required Scopeapplications-write
Timeout (Seconds)5

Attributes

NameTypeDescription
tagsobjectSee Updating Tags.

Response

Response is a JSON:API document.

200 OK

FieldTypeDescription
dataTrustApplicationThe updated TrustApplication resource.
Update trust application:
curl -X PATCH 'https://api.s.unit.sh/application/:id'
-H 'Content-Type: application/vnd.api+json'
-H 'Authorization: Bearer ${TOKEN}'
--data-raw '{
"data": {
"type": "trustApplication",
"attributes": {
"tags": {
"by": "Richard Hendricks",
"id": "23033b64-38f8-4dbc-91a1-313ff0156d02"
}
}
}
}'

Testing Applications

By default, applications in Sandbox are approved immediately. In order to test the various flows (decline, manual review, required documents), Unit provides simulations that allow you to control the application results.

You may trigger a decline, or a flow that requires documents, by providing specific SSNs that trigger each scenario.

In order to test flows that involve manual intervention, you may use dedicated endpoints that simulate the manual review results.