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).

Application Statuses#

The final statuses for an application are Approved or Denied. 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)

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.

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 or iOS SDK.

Create Individual Application#

Create an application for an individual end-customer.

VerbPOST
Urlhttps://api.s.unit.sh/applications
Required Scopeapplications-write
Data TypeindividualApplication

Attributes#

NameTypeDescription
ssnstringSSN (or ITIN) of the individual (numbers only). Either an SSN or a passport number is required.
passportstringPassport number of the individual. Either an SSN or a passport is required.
nationalityISO31661-Alpha2 stringRequired on passport only. 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.
phonePhonePhone number of the individual.
emailstringEmail address 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.
soleProprietorshipbooleanOptional. Default: false. Indicates whether 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.
tagsobjectSee Tags. Tags that will be copied to the customer that this application creates (see Tag Inheritance).
idempotencyKeystringSee 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": "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.1",      "soleProprietorship": true,      "ein": "123456789",      "dba": "Piedpiper Inc",      "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.1",      "soleProprietorship": true,      "ein": "123456789",      "dba": "Piedpiper Inc",      "tags": {        "userId": "106a75e9-de77-4e25-9561-faffe59d7814"      }    },    "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.

VerbPOST
Urlhttps://api.s.unit.sh/applications
Required Scopeapplications-write
Data TypebusinessApplication

Attributes#

NameTypeDescription
namestringName of the business.
dbastringOptional. "Doing business as".
addressAddressAddress of the business.
phonePhonePhone number of the business.
stateOfIncorporationstringTwo letters representing a US state.
einstringRequired. Business EIN (numbers only).
entityTypestringOne of "Corporation", "LLC" or "Partnership".
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.
websitestringBusiness's website. Optional.
contactBusinessContactPrimary contact of the business.
officerOfficerOfficer representing the business (must be the CEO, COO, CFO, President or BenefitsAdministrationOfficer). 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.
tagsobjectSee Tags. Tags that will be copied to the customer that this application creates (see Tag Inheritance).
idempotencyKeystringSee 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.1",      "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"        }      },      "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"          }        }      ],      "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.
includedArray of ApplicationDocument ResourceRequired documents for this application. Each document resource includes the document status.
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",      "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"        },        "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"      },      "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."      }    }  ]}

Get by Id#

Get an application resource by id.

VerbGET
Urlhttps://api.s.unit.sh/applications/{id}
Required Scopeapplications

Response#

Response is a JSON:API document.

200 OK#

FieldTypeDescription
dataIndividualApplication or BusinessApplicationApplication resource. Can be either business or individual, as indicated by the type field.
includedArray of ApplicationDocument ResourceApplication required documents, each document object also include the document status.
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

Query Parameters#

NameTypeDefaultDescription
page[limit]integer100Maximum number of resources that will be returned. Maximum is 1000 resources. See Pagination.
page[offset]integer0Number of resources to skip. See Pagination.
filter[query]string(empty)Optional. Search term according to the Full-Text Search Rules.
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 or BusinessApplicationArray of application resources. Each resource can be either business or individual, as indicated by the type field.
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",        "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"          }        ],        "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"            }          ]        }      }    }  ]}