NAV
shell Ruby Python PHP
v2
v2
v1

Introduction

The Onfido API is used to submit check requests. The API is built using RESTful endpoints and standard HTTP verbs.

Getting Started

Follow this simple step-by-step guide to get started using the Onfido API.

Find your sandbox token

We are going to run an initial check in the sandbox environment. You can find your sandbox token under the Settings > API section of your Onfido Dashboard. Make sure that it is a sandbox token by checking that the token name starts with the prefix test_ and that it is of type Test, and not Live. If you have not been issued with one, please contact sales.

Create an applicant

$ curl https://api.onfido.com/v2/applicants \
  -H 'Authorization: Token token=your_api_token' \
  -d 'title=Mr' \
  -d 'first_name=John' \
  -d 'last_name=Smith' \
  -d 'gender=male' \
  -d 'dob=1980-01-22' \
  -d 'country=GBR' \
  -d 'addresses[][building_number]=100' \
  -d 'addresses[][street]=Main Street' \
  -d 'addresses[][town]=London' \
  -d 'addresses[][postcode]=SW4 6EH' \
  -d 'addresses[][country]=GBR'

EXAMPLE RESPONSE

{
  "id": "1030303-123123-123123",
  "created_at": "2014-05-23T13:50:33Z",
  "sandbox": true,
  "href": "/v2/applicants/1030303-123123-123123",
  "title": "Mr"
  ...
}

Copy the curl command on the right, replace your_api_token with your given sandbox token, and run it in your console to create an applicant.

You should see the created applicant object in the response.

Note down the id attribute of the applicant, you will need it in the next step.

Create an identity check

$ curl https://api.onfido.com/v2/applicants/applicant_id/checks \
  -H 'Authorization: Token token=your_api_token' \
  -d 'type=express' \
  -d 'reports[][name]=identity'

EXAMPLE RESPONSE

{
  "id": "8546921-123123-123123",
  "created_at": "2014-05-23T13:50:33Z",
  "sandbox": true,
  "href": "/v2/applicants/1030303-123123-123123/checks/8546921-123123-123123",
  "type": "express",
  "status": "complete",
  "result": "clear",
  "results_uri": "https://onfido.com/dashboard/information_requests/1234",
  "redirect_uri": null,
  "reports": [
    {
      "id": "6951786-123123-422221",
      "name": "identity",
      "created_at": "2014-05-23T13:50:33Z",
      "status": "complete",
      "result": "clear",
      "href": "/v2/checks/8546921-123123-123123/reports/6951786-123123-422221"
      ...
    }
  ]
}

Having created an applicant, you are now ready to run a check containing an identity report against this applicant.

Copy the curl command on the right, replace applicant_id with the id from the previous step (as well as your_api_token), and run it in your console to create and start a check for the applicant.

You should see the created check object in the response. In this case, the check has completed and the result is a clear, i.e., the applicant’s identity has been verified. (Note that this is only a check result based on a simulated run, as checks are not actually run against real-life databases in the sandbox environment.)

Congratulations! you have run your first Onfido check.

Next steps

Now that you have run your first check, you can learn more about the rest of the API.

Learn about Express vs Standard Checks

Onfido offers two check types. Learn about the difference between the two and pick the right one for your system/workflow.

Set up a webhook

Sometimes, reports take time to process, and their results do not return instantly. In this case, the check will return with an in_progress status, and you can be notified of status changes, e.g. when a report has completed, by configuring a webhook.

Create check with multiple reports

Often you would want to run multiple reports against an applicant at the same time, e.g. an identity report alongside a watchlist report. You can do this easily by providing multiple report names or specifying a report type group when you create a check.

Create further checks for the same applicant

After the first check, you are allowed to create further checks for the same applicant, as long as the previous check is not still ongoing (i.e. check has been completed, withdrawn or cancelled).

Learn about document upload

Some reports, such as document report require documents to be uploaded.

Learn about Conditional Checks

You may want to only run certain reports based on certain conditions. You can do so without having to implement your own logic. Check out the Conditional Checks feature.

Going live

When you have finished testing your integration, you are ready to go live!

Add billing information

Live checks cannot be requested without valid billing information, so please add billing information to your account via the Onfido Dashboard.

Request live token

Please contact sales to request a live token, and update your production system to use the live token.

Update webhook endpoints

Optionally, if you intend to use a different set of webhook endpoints to handle live check/report status update events, don’t forget to update them!

Congratulations! You are now ready to start you first live check!

Check Types

The Onfido API offers two different check types: standard and express. A standard check requires an applicant to enter their information via our applicant form. An express check bypasses this step and requires all of the applicant’s information to be provided up-front by the client application.

You have to specify the check type when you create a check.

Typically, after check creation, an express check will start processing straightaway, and a standard check will only start processing when the applicant has submitted the applicant form.

Which type do I need?

Deciding which type of check to perform essentially depends upon whether your system already has the applicant’s necessary information to perform the check or whether you need their input to be collected by us.

Depending on the type of check you wish to perform, different information will be required when you are creating an applicant. This is detailed under the create applicant endpoint.

Some types of reports are only available within standard checks, due to the comprehensive data required from an applicant. Report availability is indicated in the Report Types section.

Client Libraries

We’re working on client libraries to make integrating with our API even easier!

If you write your own library and would like us to link to it, just let us know.

Ruby

An open-source library, developed by the team at Hassle, is available for Ruby.

Either add it to your gem file:

gem 'onfido'

Or install it yourself:

gem install onfido

Click the ruby tab in the upper right to see code examples, or see the source on GitHub.

Python

The Onfido Python library is available on GitHub.

Note: the previous version of the client library is no longer being supported.

PHP

The Onfido PHP library is available on GitHub.

Note: the previous version of the client library is no longer being supported.

Backwards Compatibility

The following changes are considered backwards compatible:

Changelog

2017-12-04 Added new events to the webhooks section
2017-08-25 Updated documentation on Facial similarity checks
Added support for Facial similarity reports under sandbox responses
2017-07-14 Added a new token authentication scheme for the web SDK
2017-03-03 Added report options for Watchlist full report
2017-02-21 Added support for additional reports under sandbox responses
2017-02-01 Added new client libraries
2017-01-18 Added social_insurance as a id number type
2016-12-08 Added support for basic Criminal history report as an express check
2016-10-31 Added support of testing multiple-report scenarios inside sandbox
2016-10-24 Added support of additional Criminal history report details in create check
2016-09-29 Added documentation around tag support for checks
Added more detailed description of applicant address requirements
2016-09-15 Added endpoint to download document for a particular applicant
2016-09-07 Added charge_applicant_for_check support for standard check
Added Drug Test support
Updated Right to Work report document requirements
Added SSN format specification
2016-09-01 Added two new sections:
2016-08-25 Added the referrer argument to the JSON web token endpoint
2016-08-25 Added endpoint:
Added new check:
2016-08-25 Added two new endpoints:
2016-08-15 Added Right to Work support
Added documentation on Criminal History supported options
Added documentation on supported Applicant title values
Added documentation on UK Address street attribute character limit restriction
Added documentation on Create check suppress_form_email attribute
2016-08-08 Added Resume Report endpoint and Conditional Checks documentation
2016-07-14 Added Report Type Groups (Packages) support
2016-04-25 Released API version v2:
  • Restructures document report results for greater clarity and detail
  • Changes the report type name for SSN trace from identity to to ssn_trace
Documentation for our previous version (v1) is available here

Authentication

# With curl, you can just pass the correct header with each request
curl -H "Authorization: Token token=your_api_token"
https://api.onfido.com/v2/applicants
require 'onfido'

Onfido.configure do |config|
  config.api_key = 'TOKEN'
end
from onfido import Api
api = Api("TOKEN")
\Onfido\Config::init()->set_token("TOKEN");

The API uses token-based authentication. You will be provided with a token which must be included in the header of all requests made to the API.

All API requests must be made over HTTPS. Any requests made over HTTP will fail.

You will be provided with both live and sandbox tokens. Requests made with the sandbox token can be used to trial and test our API before going live. Requests made in sandbox-mode will return dummy responses and no credit will be deducted from your account.

Errors

Standard HTTP error codes are returned in the case of a failure. 2xx codes indicate a successful message; 4xx codes indicate an error caused by information provided by the client; and 5xx codes indicate an error on Onfido’s servers.

Error codes

The following error codes are used:

Error Code Name Meaning
400 Bad Request Malformed request
401 Unauthorized Invalid authorization credentials
422 Unprocessable Entity Validation error
404 Not Found Resource not found
50x Internal Server Error An unexpected error occurred in our API

Error object

{
  "error": {
    "id": "544f95539648607d03001542",
    "type": "validation_error",
    "message": "",
    "fields": {
      "email": {
        "messages": [
          "invalid format"
        ]
      },
      "name": {
        "messages": [
          "can't be blank"
        ]
      }
    }
  }
}
Attributes Description
id string
A unique identifier for the error. This can be used as a reference for our technical support team
type string
The type of error returned
message string
A human-readable message giving more details about the error
fields hash
The list of fields which have errors associated with them. Only applies to validation errors

Pagination

$ curl https://api.onfido.com/v2/applicants?page=2&per_page=50
  -H "Authorization: Token token=your_api_token"
api.applicant.all(page: 2, per_page: 10)
top10_applicants = api.Applicants.all(1, 10):
\Onfido\Config::init()->set_token('TOKEN')->paginate(2, 5);
$applicants = (new \Onfido\Applicant())->get();

Requests that return multiple items, e.g. GET v1/applicants, will be paginated to 20 items by default. You can specify further pages using the ?page parameter and specify page size using the ?per_page parameter.

Link:   <https://api.onfido.com/v2/applicants?page=1&per_page=50>; rel="first",
        <https://api.onfido.com/v2/applicants?page=4&per_page=50>; rel="last",
        <https://api.onfido.com/v2/applicants?page=3&per_page=50>; rel="next"

X-Total-Count: 178

Pagination info is included in the link header. It is recommended that you follow these rather than constructing your own URLs. The possible rel values are next, last, first and prev.

The total count of the resource is included in a custom header X-Total-Count.

Expanding

$ curl https://api.onfido.com/v2/applicants/1030303-123123-123123/checks?expand=reports
  -H "Authorization: Token token=your_api_token"

Many objects contain the id of another object in their response properties. Those objects can be expanded inline with the expand request parameter. Objects that can be expanded are noted in this documentation.

Operations that create child objects, e.g. creating a check will return an expanded resource representation by default.

Testing

Onfido offers a sandbox environment for simulating API requests to help you test your integration. To use the sandbox environment, you would need a sandbox API token when making calls to the API endpoints. Sandbox token starts with the test_ prefix, while live token starts with the live_ prefix. Therefore, please make sure you are using the right token, if you want to make sandbox rather than live requests.

Why use a sandbox environment?

You are allowed to make all the same API requests in the sandbox environment as you are in the live environment. You will also be notified of check/report statuses changes via your registered webhooks. The key differences are, for sandbox requests:

The main reasons for using the sandbox environment are therefore to:

As check results are pre-determined, the sandbox environment is NOT for:

Rate limiting

For sandbox requests, there is currently a rate limit of 30 requests per minute. When you hit the limit, you will see an HTTP 429 too many requests error. You will be prevented from making further sandbox requests within the one-minute time period.

Sandbox responses

$ curl https://api.onfido.com/v2/applicants \
  -H 'Authorization: Token token=your_api_token' \
  -d 'title=Mr' \
  -d 'first_name=John' \
  -d 'last_name=unidentified' \
  -d 'gender=male' \
  -d 'dob=1980-01-22' \
  -d 'country=GBR' \
  -d 'addresses[][building_number]=100' \
  -d 'addresses[][street]=Main Street' \
  -d 'addresses[][town]=London' \
  -d 'addresses[][postcode]=SW4 6EH' \
  -d 'addresses[][country]=GBR'

$ curl https://api.onfido.com/v2/applicants/applicant_id/checks \
  -H 'Authorization: Token token=your_api_token' \
  -d 'type=express' \
  -d 'reports[][name]=identity'

EXAMPLE RESPONSE

{
  "id": "8546921-123123-123123",
  "created_at": "2014-05-23T13:50:33Z",
  "sandbox": true,
  "href": "/v2/applicants/1030303-123123-123123/checks/8546921-123123-123123",
  "type": "express",
  "status": "complete",
  "result": "consider",
  "results_uri": "https://onfido.com/dashboard/information_requests/1234",
  "redirect_uri": null,
  "reports": [
    {
      "id": "6951786-123123-422221",
      "name": "identity",
      "created_at": "2014-05-23T13:50:33Z",
      "status": "complete",
      "result": "unidentified",
      "href": "/v2/checks/8546921-123123-123123/reports/6951786-123123-422221"
      ...
    }
  ]
}

To help you test your integration, we currently provide a number of test data for triggering specific pre-determined responses.

ReportVariantApplicant last name*Report result
Identitystandardunidentifiedunidentified
Identitykycconsiderconsider
Documentn/aconsiderconsider
Watchlistfullconsiderconsider
Credit**n/aconsiderconsider
SSN Tracen/aconsiderconsider
National Criminaln/aconsiderconsider
Facial Similarityn/aconsiderconsider

*For all the reports listed above, “clear” will be returned if any other applicant last name value is specified.

**Credit report requires that an identity report is included in the check for the test data to work.

Note that all the usual applicant attribute requirements apply, when you create a check inside the sandbox, even if they are just dummy values. As an example, title, first_name, last_name, gender, dob, addresses, country must all be specified to trigger an identity report sandbox response.

$ curl https://api.onfido.com/v2/applicants \
  -H 'Authorization: Token token=your_api_token' \
  -d 'title=Mr' \
  -d 'first_name=John' \
  -d 'last_name=Smith' \
  -d 'gender=male' \
  -d 'dob=1980-01-22' \
  -d 'country=GBR' \
  -d 'addresses[][building_number]=100' \
  -d 'addresses[][street]=Main Street' \
  -d 'addresses[][town]=London' \
  -d 'addresses[][postcode]=SW4 6EH' \
  -d 'addresses[][country]=GBR'

$ curl https://api.onfido.com/v2/applicants/applicant_id/checks \
  -H 'Authorization: Token token=your_api_token' \
  -d 'type=express' \
  -d 'reports[][name]=identity' \
  -d 'reports[][name]=watchlist' \
  -d 'reports[][variant]=full' \
  -d 'consider[]=watchlist'

EXAMPLE RESPONSE

{
  "id": "8546921-123123-123123",
  "created_at": "2014-05-23T13:50:33Z",
  "sandbox": true,
  "href": "/v2/applicants/1030303-123123-123123/checks/8546921-123123-123123",
  "type": "express",
  "status": "complete",
  "result": "consider",
  "results_uri": "https://onfido.com/dashboard/information_requests/1234",
  "redirect_uri": null,
  "reports": [
    {
      "id": "6951786-123123-422221",
      "name": "identity",
      "created_at": "2014-05-23T13:50:33Z",
      "status": "complete",
      "result": "clear",
      "href": "/v2/checks/8546921-123123-123123/reports/6951786-123123-422221"
      ...
    },
    {
      "id": "6951786-123123-423321",
      "name": "watchlist",
      "created_at": "2014-05-23T13:50:33Z",
      "status": "complete",
      "result": "consider",
      "href": "/v2/checks/8546921-123123-123123/reports/6951786-123123-423321"
      ...
    }
  ]
}

Testing multiple-report scenarios

Apart from test data, we also provide a second mechanism to help with the testing of multiple-report scenarios. When creating a check with multiple reports, you can include an additional parameter consider to control exactly which reports should return “consider” (and which shouldn’t). This will allow you to test any scenarios that you want.

Applicants

Applicant object

{
  "id": "1030303-123123-123123",
  "created_at": "2014-05-23T13:50:33Z",
  "href": "/v2/applicants/1030303-123123-123123",
  "title": "Mr",
  "first_name": "John",
  "middle_name": null,
  "last_name": "Smith",
  "gender": "male",
  "dob": "2013-02-17",
  "telephone": "02088909293",
  "mobile": null,
  "country": "GBR",
  "mothers_maiden_name": "Johnson",
  "previous_last_name": null,
  "nationality": "USA",
  "country_of_birth": "USA",
  "town_of_birth": "New York City",
  "id_numbers": [
    {
      "type": "ssn",
      "value": "433-54-3937"
    },
    {
      "type": "driving_licence",
      "value": "I1234562",
      "state_code": "CA"
    }
  ],
  "addresses": [
    {
      "flat_number": null,
      "building_name": null,
      "building_number": "100",
      "street": "Main Street",
      "sub_street": null,
      "state": null,
      "town": "London",
      "postcode": "SW4 6EH",
      "country": "GBR",
      "start_date": "2013-01-01",
      "end_date": null
    },
    {
      "flat_number": "Apt 2A",
      "building_name": null,
      "building_number": "1017",
      "street": "Oakland Ave",
      "sub_street": null,
      "town": "Piedmont",
      "state": "CA",
      "postcode": "94611",
      "country": "USA",
      "start_date": "2006-03-07",
      "end_date": "2012-12-31"
    }
  ]
}

An applicant represents the individual the check is being performed on. To initiate a check an applicant must first be created. Applicants can be retrieved and listed.

Attribute Description
id string
The unique identifier for the applicant
created_at datetime
The date and time when this applicant was created
href string
The uri of this resource
title string
The applicant’s title. Valid values are Mr, Mrs, Miss and Ms
first_name string
The applicant’s first name
middle_name string
The applicant’s middle name(s) or initial
last_name string
The applicant’s surname
email string
The applicant’s email address
gender string
The applicant’s gender. Valid values are male and female
dob date
The applicant’s date of birth in yyyy-mm-dd format
telephone string
The applicant’s landline phone number
mobile string
The applicant’s mobile phone number
country string
The country where this applicant will be checked. This must be a three-letter ISO code e.g. GBR or USA
mothers_maiden_name string
The applicant’s mother’s maiden name
previous_last_name string
The applicant’s previous surname
nationality string
The applicant’s current nationality. This must be a three-letter ISO code e.g. GBR or USA
country_of_birth string
The applicant’s country of birth. This must be a three-letter ISO code e.g. GBR or USA
town_of_birth string
The applicant’s town of birth
id_numbers list id number
A collection of identification numbers belonging to this applicant
addresses list address
The address history of the applicant

ID Number

Attribute Description
type string
Type of ID number. Valid values are ssn, social_insurance (e.g. UK National Insurance), tax_id, identity_card and driving_license
value string
Value of ID number
Note that ssn value has to be supplied with dashes in the following format: xxx-xx-xxxx
state_code string
Two letter code of issuing state (state-issued driving licenses only)

Address

Attribute Description
flat_number string
The flat number of this address
building_number string
The building number of this address
building_name string
The building name of this address
street string
The street of the applicant’s address. There is a 32-character limit on this field for UK addresses
sub_street string
The sub-street of the applicant’s address
town string
The town of the applicant’s address
state string
The address state. US states must use the USPS abbreviation (see also ISO 3166-2:US), for example AK, CA, or TX.
postcode string
The postcode or ZIP of the applicant’s address. For UK postcode, specify the value in the following format: SW4 6EH
country string
The 3 character ISO country code of this address. For example, GBR is the country code for the United Kingdom
start_date date
The date the applicant started living at this address in yyyy-mm-dd format
end_date date
The date the applicant left this address in yyyy-mm-dd format. If current residence, leave null

street, town, postcode and country are the basic required fields. Most addresses will contain other information such as flat_number, etc. Please make sure they are supplied as separate fields, and do not try and fit them all into the street field.

For US addresses, the state field is also required.

Create applicant

$ curl https://api.onfido.com/v2/applicants \
  -H "Authorization: Token token=your_api_token" \
  -d 'title=Mr' \
  -d 'first_name=John' \
  -d 'last_name=Smith' \
  -d 'gender=male' \
  -d 'dob=2013-02-17' \
  -d 'telephone=02088909293' \
  -d 'country=GBR' \
  -d 'addresses[][building_number]=100' \
  -d 'addresses[][street]=Main Street' \
  -d 'addresses[][town]=London' \
  -d 'addresses[][postcode]=SW4 6EH' \
  -d 'addresses[][country]=GBR' \
  -d 'addresses[][start_date]=2013-08-10'
applicant_hash = {
  title: "Mr",
  first_name: "John",
  last_name: "Smith",
  gender: "male",
  dob: Date.new(2013, 2, 17),
  telephone: "02088909293",
  country: "GBR",
  addresses: [{
    building_number: 100,
    street: "Main Street",
    town: "London",
    postcode: "SW4 6EH",
    country: "GBR",
    start_date: Date.new(2013, 8, 10)
  }]
}

api.applicant.create(applicant_hash)
applicant_details = {
  title: "Mr",
  first_name: "John",
  last_name: "Smith",
  gender: "male",

  # ...
}

api.Applicants.create(applicant_details)
$applicant = new \Onfido\Applicant();
$applicant->first_name = 'John';
$applicant->last_name = 'Smith';
$applicant->email = 'email@server.com';

$address1 = new \Onfido\Address();
$address1->postcode = 'abc';
$address1->town = 'London';
$address1->country = 'GBR';

$applicant->addresses = Array($address1);

$applicant->create();

EXAMPLE RESPONSE

{
  "id": "1030303-123123-123123",
  "created_at": "2014-05-23T13:50:33Z",
  "href": "/v2/applicants/1030303-123123-123123",
  "title": "Mr",
  "first_name": "John",
  "middle_name": null,
  "last_name": "Smith",
  "gender": "male",
  "dob": "2013-02-17",
  "telephone": "02088909293",
  "mobile": null,
  "country": "GBR",
  "mothers_maiden_name": null,
  "previous_last_name": null,
  "nationality": null,
  "country_of_birth": null,
  "town_of_birth": null,
  "id_numbers": [],
  "addresses": [
    {
      "flat_number": null,
      "building_number": "100",
      "building_name": null,
      "street": "Main Street",
      "sub_street": null,
      "town": "London",
      "state": null,
      "postcode": "SW4 6EH",
      "country": "GBR",
      "start_date": "2013-08-10",
      "end_date": null
    }
  ]
}

Before you create any checks, you need to create an applicant.

The parameters required depend on whether you are planning to perform standard or express checks on this applicant. Standard checks require the applicant to provide their information using Onfido’s applicant form, whereas express checks are performed using data provided through the API.

The table below highlights which arguments are required for each check type.

Endpoint

POST https://api.onfido.com/v2/applicants

Arguments

title optional
The applicant’s title. Valid values are Mr, Mrs, Miss and Ms.
first_name required
The applicant’s forename.
last_name required
The applicant’s surname.
middle_name optional
The applicant’s middle name(s) or initials.
email required if doing a US check or a standard UK check
The applicant’s email address.
gender optional The applicant’s gender. Valid values are male and female.
dob optional
The applicant’s date of birth in yyyy-mm-dd format.
telephone optional
The applicant’s landline phone number.
mobile optional
The applicant’s mobile phone number.
country optional
The applicant’s country. This must be a three-letter ISO code e.g. GBR or USA. If not provided the default is GBR.
mothers_maiden_name optional
The applicant’s mother’s maiden name.
previous_last_name optional
The applicant’s previous surname.
nationality optional
The applicant’s current nationality. This must be a three-letter ISO code e.g. GBR or USA.
country_of_birth optional
The applicant’s country of birth. This must be a three-letter ISO code e.g. GBR or USA.
town_of_birth optional
The applicant’s town of birth.
id_numbers required if:
- doing a county_criminal or a ssn_trace check for a US applicant you must provide an SSN
- doing a driving record check you must provide a driving license
- doing a aadhaar_card check for an IND applicant you must provide an Aadhaar number. The Aadhaar number type is identity_card.
- doing a pan_card check for an IND applicant you must provide a Permanent Account Number (PAN). The PAN type is tax_id.
A collection of identification numbers belonging to this applicant
addresses optional
The address history of the applicant

Retrieve applicant

$ curl https://api.onfido.com/v2/applicants/1030303-123123-123123 \
  -H "Authorization: Token token=your_api_token"
api.applicant.find('1030303-123123-123123')
api.Applicants.find('1030303-123123-123123')
$applicant = (new \Onfido\Applicant())->get('1030303-123123-123123');

A single applicant can be retrieved by calling this endpoint along with the applicant’s unique identifier.

Endpoint

GET https://api.onfido.com/v2/applicants/{applicant_id}

Update applicant

$ curl https://api.onfido.com/v2/applicants/1030303-123123-123123 \
  -H "Authorization: Token token=your_api_token" \
  -X PUT
  -d 'last_name=Daniels' \
  -d 'dob=1990-02-17' \
  -d 'addresses[][building_number]=40' \
  -d 'addresses[][street]=Springfield Rd' \
  -d 'addresses[][town]=Teddington' \
  -d 'addresses[][postcode]=TW11 9AP' \
  -d 'addresses[][country]=GBR'
  -d 'addresses[][start_date]=2016-09-10' \

EXAMPLE RESPONSE

{
  "id": "1030303-123123-123123",
  "created_at": "2014-05-23T13:50:33Z",
  "href": "/v2/applicants/1030303-123123-123123",
  "title": "Mr",
  "first_name": "John",
  "middle_name": null,
  "last_name": "Daniels",
  "gender": "male",
  "dob": "1990-02-17",
  "telephone": "02088909293",
  "mobile": null,
  "country": "GBR",
  "mothers_maiden_name": null,
  "previous_last_name": null,
  "nationality": null,
  "country_of_birth": null,
  "town_of_birth": null,
  "id_numbers": [],
  "addresses": [
    {
      "flat_number": null,
      "building_number": "40",
      "building_name": null,
      "street": "Springfield Rd",
      "sub_street": null,
      "town": "Teddington",
      "state": null,
      "postcode": "TW11 9AP",
      "country": "GBR",
      "start_date": "2016-09-10",
      "end_date": null
    }
  ]
}

Allows updating of an applicant’s information before any checks are created.

Endpoint

PUT https://api.onfido.com/v2/applicants/{applicant_id}

Arguments

title The applicant’s title. Valid values are Mr, Mrs, Miss and Ms.
first_name The applicant’s forename.
last_name The applicant’s surname.
middle_name The applicant’s middle name(s) or initials.
email The applicant’s email address.
gender The applicant’s gender. Valid values are male and female.
dob The applicant’s date of birth in yyyy-mm-dd format.
telephone The applicant’s landline phone number.
mobile The applicant’s mobile phone number.
country The applicant’s country. This must be a three-letter ISO code e.g. GBR or USA.
mothers_maiden_name The applicant’s mother’s maiden name.
previous_last_name The applicant’s previous surname.
nationality The applicant’s current nationality. This must be a three-letter ISO code e.g. GBR or USA.
country_of_birth The applicant’s country of birth. This must be a three-letter ISO code e.g. GBR or USA.
town_of_birth The applicant’s town of birth.
id_numbers A collection of identification numbers belonging to this applicant.
addresses The address history of the applicant.

Delete applicant

$ curl https://api.onfido.com/v2/applicants/1030303-123123-123123 \
  -H "Authorization: Token token=your_api_token"
  -X DELETE

A single applicant can be deleted by calling this endpoint along with the applicant’s unique identifier.

NOTE: only applicants that don’t have any checks associated can be deleted. Trying to delete an applicant that has checks associated will result in a validation error.

Endpoint

DELETE https://api.onfido.com/v2/applicants/{applicant_id}

List applicants

$ curl https://api.onfido.com/v2/applicants \
  -H "Authorization: Token token=your_api_token"
api.applicant.all
api.Applicants.all()
$applicants = (new \Onfido\Applicant())->get();

EXAMPLE RESPONSE

{
  "applicants": [
    {
      "id": "1030303-123123-123123",
      "first_name": "John"
      ...
    },
    {
      "id": "1030303-123123-123145",
      "first_name": "Jane"
      ...
    }
  ]
}

All the applicants you have created can be retrieved from this endpoint

Endpoint

GET https://api.onfido.com/v2/applicants/

Documents

If documents are required for your check, they can be uploaded via the upload documents endpoint. Some reports require documents (passport, visas, etc) in order to be processed. Documents belong to a single applicant, so they must be uploaded after an applicant has been created.

Document object

{
  "id": "1030303-123123-123123",
  "created_at": "2014-05-23 13:50:33Z",
  "href": "/v2/applicants/1030303-123123-123123/documents/7568415-123123-123123",
  "download_href": "/v2/applicants/1030303-123123-123123/documents/7568415-123123-123123/download",
  "file_name": "localfile.png",
  "file_type": "png",
  "file_size": 282870,
  "type": "passport",
  "side": "front"
}
Attribute Description
id string
The unique identifier of the document
created_at datetime
The date and time at which the document was uploaded
href string
The uri of this resource
download_href string
The uri that can be used to download the document
file_name string
The name of the uploaded file
file_type string
The file type of the uploaded file
file_size integer
The size of the file in bytes
type string
The type of document. The possible values are detailed below.
side string
The side of the document, if applicable. The possible values are front and back

Document types

Identity documents

The below is a non-exhaustive list of the identity documents that we accept. If you can’t find what you’re looking for, please contact api@onfido.com.

Country Name Type Both sides required?
All Passport passport No
EU and EFTA states National Identity Card national_identity_card Yes
CAN Driving Licence driving_licence Yes
CHN Hong Kong Identity Card national_identity_card No
GBR Driving Licence driving_licence No
GBR Biometric Residence Permit uk_biometric_residence_permit Yes
IND Aadhaar national_identity_card No
IND PAN tax_id No
MEX INE voter_id Yes
USA Driving License driving_licence No; back optional

If you’re unaware of the type of identity document you want to verify, it can also be submitted with type unknown and we will attempt to classify and recognize the document type when processing a document report.

Other documents

In addition, we also accept uploads of the following non-identity documents specific to certain reports such as Right to Work report:

Type
work_permit
national_insurance
birth_certificate
bank_statement

Upload document

$ curl https://api.onfido.com/v2/applicants/1030303-123123-123123/documents \
  -H 'Authorization: Token token=your_api_token' \
  -F 'type=passport' \
  -F 'file=@localfile.png;type=image/png'
applicant_id = '1030303-123123-123123'
file = File.new('localfile.png')

api.document.create(applicant_id, file: file, type: 'passport')
applicant_id = '1030303-123123-123123'
document_file = open("passport.png", "rb")

document = api.Documents.create(applicant_id, document_file, "passport.png", DocumentType.Passport)
$document = new \Onfido\Document();

$document->file_name = 'file.jpg';
$document->file_path = '/path/to/file.jpg';
$document->file_type = 'image/jpg';
$document->type = 'passport';
$document->side = 'front';

$response = $document->upload_for(APPLICANT_ID);

EXAMPLE RESPONSE

{
  "id": "7568415-123123-123123",
  "created_at": "2014-05-23 13:50:33Z",
  "href": "/v2/applicants/1030303-123123-123123/documents/7568415-123123-123123",
  "download_href": "/v2/applicants/1030303-123123-123123/documents/7568415-123123-123123/download",
  "file_name": "localfile.png",
  "file_type": "png",
  "file_size": 282870,
  "type": "passport",
  "side": null
}

Documents are uploaded using this endpoint. Along with the file upload the relevant document type must be specified. Documents must be uploaded as a multipart form.

The valid file types are: jpg, png and pdf. The file size must be between 32KB and 10MB.

Endpoint

POST https://api.onfido.com/v2/applicants/{applicant_id}/documents

Arguments

file required
The file to be uploaded
type required
The type of document
side optional
Either the front or back of the document.

Retrieve document

$ curl https://api.onfido.com/v2/applicants/1030303-123123-123123/documents/8546921-123123-123123 \
  -H "Authorization: Token token=your_api_token"

A single document can be retrieved by calling this endpoint with the document’s unique identifier.

ENDPOINT

GET https://api.onfido.com/v2/applicants/{applicant_id}/documents/{document_id}

List documents

$ curl https://api.onfido.com/v2/applicants/1030303-123123-123123/documents \
  -H "Authorization: Token token=your_api_token"

All documents belonging to an applicant can be listed from this endpoint.

GET https://api.onfido.com/v2/applicants/{applicant_id}/documents

Download document

$ curl https://api.onfido.com/v2/applicants/1030303-123123-123123/documents/7568415-123123-123123/download \
  -H 'Authorization: Token token=your_api_token'

Documents are downloaded using this endpoint. Please note that in order to download the file, the token authentication is mandatory.

The response will be the binary data representing the image.

Endpoint

GET https://api.onfido.com/v2/applicants/{applicant_id}/documents/{document_id}/download

Checks

Checks are performed on an applicant. Checks can be created and retrieved.

A check consists of many reports. See reports and report types to learn more.

Check object

{
  "id": "8546921-123123-123123",
  "created_at": "2014-05-23T13:50:33Z",
  "href": "/v2/applicants/1030303-123123-123123/checks/8546921-123123-123123",
  "type": "express",
  "status": "complete",
  "result": "clear",
  "redirect_uri": "https://somewhere.else",
  "results_uri": "https://onfido.com/dashboard/information_requests/1234",
  "download_uri": "https://onfido.com/dashboard/pdf/1234",
  "reports": [
    "1030303-123123-375629",
    "1030303-123123-456789"
  ],
  "tags": [
    "My tag",
    "Another tag"
  ]
}

The check object is used to track the type and status of a check, and contains the nested resource reports.

Attribute Description
id string
The unique identifier for the check.
created_at timestamp
The date and time at which the check was initiated.
href string
The API endpoint to retrieve the check.
type string
The type of check: standard or express.
status string
The current state of the check in the checking process.
tags list [string]
A list of tags associated with this check.
result string
The overall result of the check, based on the results of the constituent reports.
download_uri string
A link to a PDF output of the check results
form_uri string
A link to the applicant form, if the check is of type standard
redirect_uri string
For standard checks, redirect to this URI when the applicant has submitted their data.
results_uri string
A link to the corresponding results page on the Onfido dashboard
reports list reports expandable
The list of report objects associated with the check.

Check status

Status Description
in_progress We are currently processing the check.
awaiting_applicant Applicant has not yet submitted the Applicant Form, either because they have not started filling the form out or because they have started but have not finished.
complete All reports for the applicant have been completed or withdrawn.
withdrawn Check has been withdrawn.
paused Check is paused until you, i.e. the client, switch it on manually. Special case used by clients who wants to collect data and run the checks when they want and not immediately.
reopened Insufficient/inconsistent information is provided by the applicant, and the report has been bounced back for further information.

Create check

$ curl https://api.onfido.com/v2/applicants/1030303-123123-123123/checks \
  -H "Authorization: Token token=your_api_token" \
  -d 'type=standard' \
  -d 'reports[][name]=identity' \
  -d 'reports[][name]=criminal_history' \
  -d 'reports[][variant]=enhanced' \
  -d 'reports[][options][][name]=adults_barred_list' \
  -d 'criminal_history_report_details[job_role]=carer' \
  -d 'criminal_history_report_details[place_of_work]=care home' \
  -d 'tags[]=My tag' \
  -d 'tags[]=Another tag'

$ curl https://api.onfido.com/v2/applicants/1030303-123123-123123/checks \
  -H "Authorization: Token token=your_api_token" \
  -d 'type=standard' \
  -d 'report_type_groups[]=8546921-123123-422221' \
  -d 'criminal_history_report_details[job_role]=carer' \
  -d 'criminal_history_report_details[place_of_work]=care home' \
  -d 'tags[]=My tag' \
  -d 'tags[]=Another tag'
# creating a check containing an identity report
api.check.create('1030303-123123-123123', {
  type: 'standard',
  reports: [{ name: 'identity' }]
})

# creating a check containing an enhanced UK criminal history report
api.check.create('1030303-123123-123123', {
  type: 'standard',
  redirect_uri: 'https://www.onfido.com',
  reports: [
    {
      name: 'criminal_history',
      variant: 'enhanced',
      options: [
        {
          name: 'children_barred_list',
          options: [
            { name: 'speedy' }
          ]
        }
      ]
    }
  ]
})
check = api.Checks.create("1030303-123123-123123", {
    "type": "standard",
    "reports": [{ "name": "identity" }]
})
$check = new \Onfido\Check();
$check->type = 'standard';

$report1 = new \Onfido\CheckReport();
$report1->name = 'identity';

$check->reports = Array(
    $report1
);
$response = $check->create_for(APPLICANT_ID);

EXAMPLE RESPONSE

{
  "id": "8546921-123123-123123",
  "created_at": "2014-05-23T13:50:33Z",
  "href": "/v2/applicants/1030303-123123-123123/checks/8546921-123123-123123",
  "type": "standard",
  "status": "awaiting_applicant",
  "result": null,
  "results_uri": "https://onfido.com/dashboard/information_requests/1234",
  "redirect_uri": null,
  "reports": [
    {
      "id": "6951786-123123-422221",
      "name": "identity",
      "created_at": "2014-05-23T13:50:33Z",
      "status": "awaiting_data",
      "result": null,
      "href": "/v2/checks/8546921-123123-123123/reports/6951786-123123-422221",
      "breakdown": {},
      "properties": {}
    },
    {
      "id": "6951786-123123-316712",
      "name": "document",
      "created_at": "2014-05-23T13:50:33Z",
      "status": "awaiting_data",
      "result": null,
      "href": "/v2/checks/8546921-123123-123123/reports/6951786-123123-316712",
      "breakdown": {},
      "properties": {}
    }
  ],
  "tags": [
    "My tag",
    "Another tag"
  ]
}

Checks are initiated using this endpoint.

Certain reports are generated instantly and their results are returned in the response, while other reports take longer to be processed. You will need to set up a webhook to listen for the results of non-instant reports.

Having created the first check, you are allowed to create further checks for the same applicant, as long as the previous check is not still ongoing (i.e. check has been completed, withdrawn or cancelled). You will receive an error message if you try to create a check for an applicant with an ongoing check. Applicant details can be updated between check creations.

ENDPOINT

POST https://api.onfido.com/v2/applicants/{applicant_id}/checks

ARGUMENTS

type required
standard or express. See Check Types.
redirect_uri optional
For standard checks, redirect to this URI when the applicant has submitted their data.
reports optional
Array of Reports being requested for this check.
report_type_groups optional
Array containing ids of the Report type groups being requested for
criminal_history_report_details optional
Hash containing properties required for standard or enhanced UK criminal history reports. Only required for checks containing these specific reports. See Criminal history report details arguments.
tags optional
Array of tags being assigned to this check.
suppress_form_emails optional
For standard checks, applicant form will not be automatically sent if this is set to true. You can manually send the form at any time after the check has been created, using the link found in the form_uri attribute of the check object.
Defaults to false (i.e., form will be sent automatically by default)
async optional
If this is set to true, checks will be queued for processing and no reports will be returned immediately. Defaults to false
charge_applicant_for_check optional
For standard checks, applicants will be presented with a mandatory payment screen before they can submit the applicant form, if this is set to true. In this case, your account will not be charged.
Defaults to false
consider optional
Array of names of the reports to return consider as their results. This is a sandbox testing specific argument for testing multiple-report scenarios.

Note that either reports or report_type_groups must be specified when creating a check.

REPORT ARGUMENTS

name required
The name of the report type. The possible report types are detailed here. For more information please see our product description.
variant optional
The name of the report type variant, if required.
options optional
Array of Report Options hashes

REPORT OPTIONS ARGUMENTS

name required
The name of the option to be enabled.
options optional
Any Report Options hashes that apply to this option. (Can only be nested to 1 level)

CRIMINAL HISTORY REPORT DETAILS ARGUMENTS

job_role optional
The applicant’s job role for which you would like to request a standard or enhanced UK criminal history reports.
place_of_work optional
The place of work where the applicant will be carrying out their role.

Retrieve check

$ curl https://api.onfido.com/v2/applicants/1030303-123123-123123/checks/8546921-123123-123123 \
  -H "Authorization: Token token=your_api_token"
api.check.find('1030303-123123-123123', '8546921-123123-123123')
applicant_id = "1030303-123123-123123"
check_id = "8546921-123123-123123"

check = api.Checks.find(applicant_id, check_id)
$check = (new \Onfido\Check())->get(APPLICANT_ID, CHECK_ID);

A single check can be retrieved by calling this endpoint with the check’s unique identifier.

ENDPOINT

GET https://api.onfido.com/v2/applicants/{applicant_id}/checks/{check_id}

List checks

$ curl https://api.onfido.com/v2/applicants/1030303-123123-123123/checks \
  -H "Authorization: Token token=your_api_token"
api.check.all('1030303-123123-123123')
applicant_id = "1030303-123123-123123"

checks = api.Checks.all(applicant_id)
$checks = (new \Onfido\Check())->get(APPLICANT_ID);

All checks belonging to an applicant can be listed from this endpoint.

GET https://api.onfido.com/v2/applicants/{applicant_id}/checks

Resume check

$ curl https://api.onfido.com/v2/checks/1030303-123123-123123/resume \
  -H "Authorization: Token token=your_api_token"

This endpoint is for resuming paused checks. A check is paused if all the reports that it contains are in the paused state.

When a standard check gets resumed, all its reports are going to start processing immediately if the applicant has already submitted the form. The check status will automatically change to in_progress. Otherwise, the check will remain as awaiting_applicant and the reports are only going to start processing after the applicant submits the form.

ENDPOINT

POST https://api.onfido.com/v2/checks/{check_id}/resume

Reports

Report object

{
  "id": "6951786-123123-316712",
  "name": "identity",
  "created_at": "2014-05-23T13:50:33Z",
  "status": "awaiting_data",
  "result": null,
  "sub_result": null,
  "variant": null,
  "options": {},
  "href": "/v2/checks/8546921-123123-123123/reports/6951786-123123-316712",
  "breakdown": {},
  "properties": {}
}

The report object contains the state and relevant details of the particular report. The structure of the object is listed below.

The breakdown hash contains the details of the particular report and differs for each report type. The format of the breakdown and properties for each report type is listed below.

Attribute Description
id string
The unique identifier for the report
created_at timestamp
The date and time at which the report was first initiated
name string
Report type string identifier. See Report Types
href string
The API endpoint to retrieve the report
status string
The current state of the report in the checking process
result string
The result of the report
sub_result string
The sub_result of the report. It gives a more detailed result for document reports only, and will be null otherwise
variant string
Report variant string identifier. Some reports e.g. criminal_history have sub-types, which are identified by this field. These are detailed in Report Types
options string
Report options. Some reports e.g. criminal_history expose additional options. These are detailed in Report Types
breakdown hash
The details of the report. This is specific to each type of report
properties hash
The properties associated with the report, if any

Report status

Status Description
awaiting_data Onfido has made a request to one of its data providers and we are waiting on their reply.
awaiting_approval Report is going through manual review.
complete Report is done.
withdrawn Report has been cancelled.
paused Report is paused until you, i.e. the client, switch it on manually. Special case used by clients who wants to collect data and run the reports when they want and not immediately.
cancelled Special status for conditional checks: When you, i.e. the client, request two reports and one of them is conditional on the other, then the status will be complete if the condition is met or cancelled if not.

Results

The result field indicates the overall result of a report. The possible values of this field are detailed below:

Report result
clear If all underlying verifications pass, the overall result will be clear
consider If the report has returned information that needs to be evaluated, the overall result will be consider.
unidentified Identity report (standard variant) only - this is returned if the applicant fails an identity check. This indicates there is no identity match for this applicant on any of the databases searched.

For convenience, the check object also has a result field. Its value is derived from the results of the individual reports that it contains:

Check result
clear If all the reports contained in the check have clear as their results.
consider If some of the reports contained in the check have either consider or unidentified as their results.

Sub Results

The sub_result field indicates a more detailed result for document reports

Report sub_result
clear If all underlying verifications pass, the overall sub result will be clear
rejected If the report has returned information where the check cannot be processed further (poor quality image or an unsupported document).
suspected If the document that is analysed is suspected to be fraudulent.
caution If any other underlying verifications fail but they don’t necessarily point to a fraudulent document (such as the name provided by the applicant doesn’t match the one on the document)

Retrieve report

$ curl https://api.onfido.com/v2/checks/8546921-123123-123123/reports/1256879-123123-456789 \
  -H "Authorization: Token token=your_api_token"
api.report.find('8546921-123123-123123', '1256879-123123-456789')
check_id = "8546921-123123-123123"
report_id = "1256879-123123-456789"

report = api.Reports.find(check_id, report_id)
$report = (new \Onfido\Report())->get(CHECK_ID, REPORT_ID);

A single report can be retrieved using this endpoint with the corresponding unique identifier.

Endpoint

GET https://api.onfido.com/v2/checks/{check_id}/reports/{report_id}

List reports

$ curl https://api.onfido.com/v2/checks/8546921-123123-123123/reports \
  -H "Authorization: Token token=your_api_token"
api.report.all('8546921-123123-123123')
check_id = "8546921-123123-123123"

reports = api.Reports.all(check_id)
$reports = (new \Onfido\Report())->get(CHECK_ID);

All the reports belonging to a particular check can be listed from this endpoint.

Endpoint

GET https://api.onfido.com/v2/checks/{check_id}/reports

Resume report

$ curl https://api.onfido.com/v2/checks/1234567-123123-123123/reports/1030303-123123-123123/resume \
  -H "Authorization: Token token=your_api_token"

This endpoint is for resuming individual paused reports.

When an individual report gets resumed in a standard check, it will start processing immediately if the applicant has already submitted the form. The report status will automatically change from paused to awaiting_data. Otherwise, the status change will happen but the report processing will only start after the applicant submits the form.

Note that you can resume all reports within a check by resuming the check itself.

ENDPOINT

POST https://api.onfido.com/v2/checks/{check_id}/reports/{report_id}/resume

Cancel report

$ curl https://api.onfido.com/v2/checks/1234567-123123-123123/reports/1030303-123123-123123/cancel \
  -H "Authorization: Token token=your_api_token"

This endpoint is for cancelling individual paused reports.

When an individual report gets cancelled in a standard check, its status will change from paused to cancelled and the report will never get processed.

ENDPOINT

POST https://api.onfido.com/v2/checks/{check_id}/reports/{report_id}/cancel

Report Type Groups

Report type groups provide a convenient way to group and organize different types of reports, so that you can easily request different sets of reports for different buckets of applicants. For example, you may want to only run an identity report, a right_to_work report and a criminal_history report on a junior-level role, but you may want additional reports on a more senior-level role.

To set up or update your report type groups, please contact client-support@onfido.com.

Report type group object

{
  "id": "8546921-123123-123123",
  "name": "Senior level",
  "group_only": false,
  "report_types": [
    {
      "id": "4566764-567657-234445",
      "name": "identity"
    },
    {
      "id": "2344556-236767-786868",
      "name": "right_to_work"
    },
    {
      "id": "4523434-345133-234424",
      "name": "directorship"
    },
    {
      "id": "7857345-234234-565345",
      "name": "criminal_history",
      "variant": "basic",
      "options": []
    }
  ]
}

The report type group object defines the set of reports to be requested in a check. The structure of the object is listed below.

Note that more than one report type group can be requested in a single check.

Attribute Description
id string
The unique identifier for the group.
name string
The group’s name, as specified under your account.
group_only boolean
If false, individual reports in that group can be requested; if true, all reports must be requested together.
report_types list [object]
A list of objects containing information regarding the different report types included in this group.

Retrieve report type group

$ curl https://api.onfido.com/v2/report_type_groups/8546921-123123-123123 \
  -H "Authorization: Token token=your_api_token"

A single report type group can be retrieved by calling this endpoint with the group’s unique identifier.

ENDPOINT

GET https://api.onfido.com/v2/report_type_groups/{report_type_group_id}

List report type groups

$ curl https://api.onfido.com/v2/report_type_groups \
  -H "Authorization: Token token=your_api_token"

All report type groups belonging to your account can be listed from this endpoint.

GET https://api.onfido.com/v2/report_type_groups

Live Photos

Live photos are images of the applicant’s face, typically taken at the same time as documents are provided. These photos are used to perform facial similarity checks on the applicant.

Live photo object


{
  "id": "7410A943-8F00-43D8-98DE-36A774196D86",
  "created_at": "2016-05-11T11:45:26Z",
  "href": "/v2/live_photos/7410A943-8F00-43D8-98DE-36A774196D86",
  "download_href": "/v2/live_photos/7410A943-8F00-43D8-98DE-36A774196D86/download",
  "file_name": "localfile.png",
  "file_type": "png",
  "file_size": 282123
}
Attribute Description
id string
The unique identifier of the live photo
created_at datetime
The date and time at which the live photo was uploaded
applicant_id integer
The id of the applicant the live photo belongs to
href string
The uri of this resource
download_href string
The uri that can be used to download the live photo
file_name string
The name of the uploaded file
file_type string
The file type of the uploaded file
file_size integer
The size of the file in bytes

Upload live photo

$ curl https://api.onfido.com/v2/live_photos \
  -H 'Authorization: Token token=your_api_token' \
  -F 'applicant_id=293CD57E-47A4-40A9-A7F9-C8AD47FE0CE8' \
  -F 'file=@localfile.jpg;type=image/jpeg'

EXAMPLE RESPONSE

{
  "id": "7410A943-8F00-43D8-98DE-36A774196D86",
  "created_at": "2016-05-11T11:45:26Z",
  "href": "/v2/live_photos/7410A943-8F00-43D8-98DE-36A774196D86",
  "download_href": "/v2/live_photos/7410A943-8F00-43D8-98DE-36A774196D86/download",
  "file_name": "localfile.png",
  "file_type": "png",
  "file_size": 282123
}

You can upload live photos to this endpoint. Like document upload, files must be uploaded as a multipart form.

Valid file types are jpg, png and pdf. The file size must be between 32KB and 10MB. Live photos are validated at the point of upload to check that they contain exactly one face. This validation can be disabled by setting the advanced_validation argument to false.

Endpoint

POST https://api.onfido.com/v2/live_photos

Arguments

file required
The file to be uploaded
applicant_id required
The applicant_id to associate the live photo to
advanced_validation optional
A boolean which defaults to true
Validates that the live photo contains exactly one face

Retrieve live photo

$ curl https://api.onfido.com/v2/live_photos/7410A943-8F00-43D8-98DE-36A774196D86 \
  -H 'Authorization: Token token=your_api_token'

You can retrieve a single live photo by calling this endpoint with the live photo’s unique identifier.

ENDPOINT

GET https://api.onfido.com/v2/live_photos/{live_photo_id}

List live photos

$ curl https://api.onfido.com/v2/live_photos?applicant_id=293CD57E-47A4-40A9-A7F9-C8AD47FE0CE8 \
  -H 'Authorization: Token token=your_api_token'

This endpoint lists all the live photos that belong to an applicant. You must pass the applicant ID as a query string parameter.

GET https://api.onfido.com/v2/live_photos

Arguments

applicant_id required
The ID of the applicant whose live photos you want to list

Download live photo

$ curl https://api.onfido.com/v2/live_photos/7410A943-8F00-43D8-98DE-36A774196D86/download \
  -H 'Authorization: Token token=your_api_token'

Live photos are downloaded using this endpoint. Please note that in order to download the file, token authentication is mandatory.

The response is the binary data representing the image.

Endpoint

GET https://api.onfido.com/v2/live_photos/{live_photo_id}/download

Webhooks

Onfido provides webhooks to alert you of changes in the status of your resources (i.e., checks and reports). These are POST requests to your server that are sent as soon as an event occurs. The body of the request contains details of the event.

All check/report status changes trigger webhook notifications, even for those that complete instantly.

Sandbox checks and reports also trigger webhook notifications. Your can create and configure webhooks to receive status changes from sandbox, live or both environments.

Webhook endpoints can be registered through the Onfido dashboard or API. To help you diagnose or to understand webhook issues, a log of your wehbook requests is also available under your dashboard’s Webhook Logs.

Upon receiving a webhook notification, you should acknowledge success by responding with an HTTP 20x response. Otherwise, we will attempt to resend the notification up to 10 times over the next 72 hours in increasing time intervals, based on an exponential backoff algorithm.

Quick tip: for initial testing, you can create a temporary endpoint URL using a service such as http://requestb.in/ to quickly inspect webhook requests.

IP addresses

All webhook requests will be coming from the following IPs:

52.51.171.25

52.51.228.228

52.51.234.203

Please make sure that you’ve whitelisted these IPs in order to receive webhook notifications.

Events

The following events will trigger a message to registered webhooks:

Resource Events Description
check check.started A check has been started; when check.type = standard, this indicates the applicant has submitted all required information.
check check.reopened A check has been reopened. This indicates the applicant needs to re-submit required information.
check check.withdrawn A check has been withdrawn.
check check.completed A check has been completed.
check check.form_opened An applicant has opened the applicant form. It fires every time the applicant opens the form.
check check.form_completed An applicant has submitted his information by the applicant form.
report report.withdrawn A report has been withdrawn.
report report.resumed A paused report has been resumed.
report report.cancelled A paused report has been cancelled.
report report.awaiting_approval A report has transitioned to the “Awaiting Approval” status.
report report.completed A report has been completed and results are available.

Event object

{
  "payload": {
    "resource_type": "report",
    "action": "report.completed",
    "object": {
      "id": "12345-23122-32123",
      "status": "completed",
      "completed_at": "2014-05-23 13:50:33 UTC",
      "href": "https://api.onfido.com/v2/checks/12343-11122-09290/reports/12345-23122-32123"
    }
  }
}

The payload below will be sent to all registered webhooks when an supported event occurs on the Onfido application.

Attributes

Attribute Description
payload hash
The top level element
resource_type string
Indicates the resource affected by this event
action string
The event that triggered this webhook, e.g. report.completed
object hash
The object affected by this event. This will contain an id and an href to retrieve that resource

Webhook security

X-Signature: f1b9e6cd8eef30c333da48370e646839c9bb9e21b11ea161b4d5cf93a12345df
# Validating the X-Signature in Sinatra
signature = OpenSSL::HMAC.hexdigest(OpenSSL::Digest.new('sha1'), your_token, data_to_sign)
return halt 500, "Signatures did not match!" unless Rack::Utils.secure_compare(signature, request.env['X_SIGNATURE'])

Each webhook URL is associated with a secret token. This is visible in the response.token field when registering a webhook.

Events sent to your application will be signed using this token: verifying the request signature on your server prevents attackers from imitating valid webhooks. The HMAC digest signature, generated using SHA-1, will be stored in a X-Signature header.

When you receive an event, you should compute a hash based on the complete event payload using the secret token, and ensure that the X-Signature sent by Onfido matches that hash.

Register webhook

$ curl https://api.onfido.com/v2/webhooks \
  -H "Authorization: Token token=your_api_token" \
  -d 'url=https://webhookendpoint.url' \
  -d 'enabled=true' \
  -d 'environments[]=live' \
  -d 'environments[]=sandbox' \
  -d 'events[]=report.completed' \
  -d 'events[]=report.withdrawn' \
  -d 'events[]=check.started' \
  -d 'events[]=check.completed' \
  -d 'events[]=check.form_opened' \
  -d 'events[]=check.form_completed' \

EXAMPLE RESPONSE

{
  "id": "fcb73186-0733-4f6f-9c57-d9d5ef979443",
  "url": "https://webhookendpoint.url",
  "token": "yV85IsmuYwmjQGlZ",
  "enabled": true,
  "href": "/v2/webhooks/fcb73186-0733-4f6f-9c57-d9d5ef979443",
  "environments": [
    "live",
    "sandbox"
  ],
  "events": [
    "report.completed",
    "report.withdrawn",
    "check.completed",
    "check.started",
    "check.form_opened",
    "check.form_completed"
  ]
}

Webhook URLs can be registered using this endpoint. By default, webhooks are subscribed to all events, but can be subscribed to a subset using the events array.

Endpoint

POST https://api.onfido.com/v2/webhooks

Arguments

url required
The url that will listen to notifications (must be https).
enabled optional
Determine if the webhook should be active.
If the enabled parameter is omitted it will be set as true.
environments optional
The environments from which the webhook will receive events.
Allowed values are “sandbox” and “live”.
If the environments parameter is omitted the webhook will receive events from both environments.
events optional
The events that should be published to the webhook.
The supported events are:
“report.completed”, “report.withdrawn”, “check.completed”, “check.started”, “check.form_opened”, “check.form_completed”
If the events parameter is omitted all the events will be subscribed.

Retrieve webhook

$ curl https://api.onfido.com/v2/webhooks/1030303-123123-123123 \
  -H "Authorization: Token token=your_api_token"

A single webhook can be retrieved by calling this endpoint along with the webhook’s unique identifier.

Endpoint

GET https://api.onfido.com/v2/webhooks/{webhook_id}

List webhooks

$ curl https://api.onfido.com/v2/webhooks \
  -H "Authorization: Token token=your_api_token"

EXAMPLE RESPONSE

{
  "webhooks": [
    {
      "id": "dd0a89e4-d44e-417a-aec4-01137d01ae59",
      "url": "https://demo.com","enabled":false,
      "href": "/v2/webhooks/dd0a89e4-d44e-417a-aec4-01137d01ae59",
      "token": "yV85IsmuYwmjQGlZ",
      "environments": [
        "sandbox"
      ],
      "events": [
        "check.started"
      ]
    },
    {
      "id": "bfc727a8-f7bf-4073-b123-ed70a70f58e5",
      "url": "https://demo2.com",
      "enabled": true,
      "href": "/v2/webhooks/bfc727a8-f7bf-4073-b123-ed70a70f58e5",
      "token": "yV85IsmuYwmjQGlZ",
      "environments": [
        "live"
      ],
      "events": [
        "report.completed",
        "report.withdrawn",
        "check.completed",
        "check.started",
        "check.form_opened",
        "check.form_completed"
      ]
    }
  ]
}

All the webhooks you have created can be retrieved from this endpoint

Endpoint

GET https://api.onfido.com/v2/webhooks/

Address Picker

$ curl -X GET https://api.onfido.com/v2/addresses/pick?postcode=SW4%206EH \
  -H "Authorization: Token token=your_api_token"
api.address.all('SW4 6EH')
addresses = api.AddressPicker.all('SW4 6EH')
$address = new \Onfido\AddressPicker();
$address->postcode = 'SW4 6EH';
$addresses = $address->pick();

Example Response

{
  "addresses": [
    {
      "flat_number": "",
      "building_number": "100",
      "building_name": "",
      "street": "Main Street",
      "sub_street": "",
      "town": "London",
      "postcode": "SW4 6EH",
      "country": "GBR"
    },
    {
      "flat_number": "",
      "building_number": "101",
      "building_name": "",
      "street": "Main Street",
      "sub_street": "",
      "town": "London",
      "postcode": "SW4 6EH",
      "country": "GBR"
    }
  ]
}

The address picker endpoint performs a search for addresses by postcode.

This resource can be used to aid in ensuring addresses passed to /applicants are valid.

Endpoint

GET https://api.onfido.com/v2/addresses/pick

Arguments

postcode string
The applicant’s postcode

SDK Tokens

$ curl https://api.onfido.com/v2/sdk_token
  -H 'Authorization: Token token=your_api_token' \
  -F 'applicant_id=293CD57E-47A4-40A9-A7F9-C8AD47FE0CE8' \
  -F 'referrer=https://*.onfido.com/documentation/*' \

EXAMPLE RESPONSE

{
  "token": "header.payload.signature"
}

JSON Web Tokens (JWTs) are used to authenticate Onfido’s JavaScript SDK. The tokens documented here support SDK versions 0.16.0 and above. The tokens used in earlier versions will be deprecated soon, but we continue to support them for now. We recommend upgrading to the latest version of the SDK.

A new SDK token is required for every new instance of the JS SDK. Tokens are obtained from the API and expire after 90 minutes.

Endpoint

POST https://api.onfido.com/v2/sdk_token

Arguments

applicant_id required
Specifies the applicant for the SDK instance
referrer required
The referrer URL pattern

Each authenticated instance of the SDK will correspond to a single Onfido applicant. You must specify the applicant when generating the SDK token.

The referrer argument specifies the URL of the web page where the JavaScript SDK will be used. The referrer must match the web page for the SDK to authenticate. The referrer is based on the Chrome match pattern URLs. URLs can contain wild card characters.

Permitted patterns:

Section Format Example
Referrer scheme://host/path https://*.onfido.com/documentation/*
Scheme * or http or https https
Host * or *. then any char except / and * *.onfido.com
Path Any char or none documentation/*

Identity Verification

The following section details report types that can be used to verify an individual’s identity. These are available in multiple countries.

ReportNameVariantsStandard checkExpress check
Identity Report identity standard kyc yes yes
Document Report document yes yes
Street Level Report street_level yes yes
Facial Similarity Report facial_similarity standard video yes yes

Identity Report

Example UK Response

{
  "id": "6951786-123123-316712",
  "name": "identity",
  "created_at": "2014-05-23T13:50:33Z",
  "status": "complete",
  "result": "clear",
  "href": "/v2/checks/8546921-123123-123123/reports/6951786-123123-316712",
  "breakdown": {
    "address": {
      "result": "clear",
      "breakdown": {
        "credit_agencies": {
          "result": "clear",
          "properties": {
            "number_of_agencies": "5"
          }
        },
        "voting_register": {
          "result": "none",
          "properties": {}
        },
        "telephone_database": {
          "result": "clear",
          "properties": {}
        }
       }
    },
    "date_of_birth": {
      "result": "clear",
      "breakdown": {
        "credit_agencies": {
          "result": "clear",
          "properties": {}
        },
        "voting_register": {
          "result": "none",
          "properties": {}
        }
      }
    }
  },
  "properties": {}
}

Example non-UK Response

{
  "id": "6951786-234234-316712",
  "name": "identity",
  "created_at": "2014-05-23T13:50:33Z",
  "status": "complete",
  "result": "clear",
  "href": "/v2/checks/8546922-234234-234234/reports/6951786-234234-316712",
  "breakdown": {
    "date_of_birth": {
      "result": "clear",
      "breakdown": {
        "date_of_birth_matched": {
          "result": "clear",
          "properties": {
            "sources": "Credit Agencies"
          }
        }
      }
    },
    "address": {
      "result": "clear",
      "breakdown": {
        "address_matched": {
          "result": "clear",
          "properties": {
            "sources": "Credit Agencies, Telephone Database"
          }
        }
      }
    }
  },
  "properties": {}
}

An identity report validates an applicant’s address, date of birth, name, and mortality (where applicable) by cross-referencing their details against a range of verified databases.

Report result breakdowns indicate which of these elements was positively matched, and the underlying source or sources of that database match.

The example to the right details:

When we can’t find a match for date of birth or address (i.e. result is not clear) the corresponding properties bucket will be empty as such "properties":{}.

Sources names and definitions

Onfido source name Onfido definition
Credit Agencies Data comprised of consumer credit applications
Voting Register Data comprised of voter registration within a country
Telephone Database Data provided by both landline and mobile providers
Government Any standard publicly accessible data collected by government entities. These include driver’s license data, motor vehicle registration, court filings, property ownership registers, permanent place of residence registration and other similar data sets
Business Registration Data comprised of business registrations, corporate directors filings and business hierarchy data
Consumer Database Opt-in consumer data leveraging database marketing and other similar opt-in data sources
Utility Registration Data comprised of utility registrations such as electricity, gas, water accounts
Postal Authorities Data provided by postal authorities
Commercial Database These are corporate/private databases where users have opted-in and allowed for their information to be used for the purpose of verification of their identities
Proprietary This is when a data provider chooses not to divulge the source of the data to us for varied reasons, and also includes social media based data
Register of Deaths Negative source for known deaths (UK only)

There are two different variants of identity report: standard and kyc.

Standard

This check should be used for employment/recruitment purposes. It may leave an employment footprint on the individual’s credit record in some countries, such as the UK.

Report result breakdowns indicate which of these elements was positively matched, and the underlying source or sources of that database match.

Overall result logic:

Number of addresses: This check will attempt to find an address match for the current applicant address. If no match is found it will attempt to match the previous address (if provided), up to a total of 3 applicant addresses.

Mortality: Not checked.

KYC

This check should be used for “know your customer” (KYC) purposes, for instance, if you are providing a financial service.

Report result breakdowns indicate which of these elements was positively matched, and the underlying source or sources of that database match.

Overall result logic:

If the applicant address is in the UK:

This follows the definition of 2+2 as per the JMLSG Guidelines 2014 Section 5.3.69.

If the applicant address is outside of the UK:

Number of addresses: As per JMLSG definitions, this check will only attempt to find a match using the applicant’s current address.

Mortality: Only checked in the UK.

Document Report

{
  "created_at": "2016-03-31T13:24:17Z",
  "href": "/v2/checks/7c1dfeef-938b-4198-8e83-ef3b12282d39/reports/d79747be-9aab-420a-b16f-f0a2160ac13e",
  "id": "d79747be-9aab-420a-b16f-f0a2160ac13e",
  "name": "document",
  "properties": {
    "document_type": "passport",
    "issuing_country": "GBR",
    "first_name": "JOHN",
    "last_name": "OLIVER",
    "document_numbers": [{ "type": "document_number", "value" : "AA000000" }],
    "date_of_birth": "2004-03-16",
    "date_of_expiry": "2025-07-05",
    "nationality": "GBR",
    "gender": "Male",
    "mrz_line1": "P<GBRJOHN<OLIVER<<<<<<<<<<<<<<<<<<<<<<<<<<",
    "mrz_line2": "AA000000<0GBR0403162M2507053<<<<<<<<<<<<<<04"
  },
  "result": "clear",
  "sub_result": "clear",
  "status": "complete",
  "variant": "standard",
  "breakdown": {
    "police_record": {
      "result": "clear"
    },
    "data_comparison": {
      "result": "clear",
      "breakdown": {
        "date_of_expiry": {
          "result": null,
          "properties": {}
        },
        "issuing_country": {
          "result": null,
          "properties": {}
        },
        "document_type": {
          "result": null,
          "properties": {}
        },
        "document_numbers": {
          "result": null,
          "properties": {}
        },
        "gender": {
          "result": "clear",
          "properties": {}
        },
        "date_of_birth": {
          "result": "clear",
          "properties": {}
        },
        "last_name": {
          "result": "clear",
          "properties": {}
        },
        "first_name": {
          "result": "clear",
          "properties": {}
        }
      }
    },
    "data_consistency": {
      "result": "clear",
      "breakdown": {
        "date_of_expiry": {
          "result": "clear",
          "properties": {}
        },
        "document_type": {
          "result": "clear",
          "properties": {}
        },
        "gender": {
          "result": "clear",
          "properties": {}
        },
        "date_of_birth": {
          "result": "clear",
          "properties": {}
        },
        "nationality": {
          "result": "clear",
          "properties": {}
        },
        "issuing_country": {
          "result": "clear",
          "properties": {}
        },
        "document_numbers": {
          "result": "clear",
          "properties": [
            { "type": "passport", "result": "clear" }
          ]
        },
        "last_name": {
          "result": "clear",
          "properties": {}
        },
        "first_name": {
          "result": "clear",
          "properties": {}
        }
      }
    },
    "data_validation": {
      "result": "clear",
      "breakdown": {
        "gender": {
          "result": "clear",
          "properties": {}
        },
        "expiry_date": {
          "result": "clear",
          "properties": {}
        },
        "date_of_birth": {
          "result": "clear",
          "properties": {}
        },
        "document_numbers": {
          "result": "clear",
          "properties": [
            { "type": "passport", "result": "clear" }
          ]
        },
        "mrz": {
          "result": "clear",
          "properties": {}
        }
      }
    },
    "visual_authenticity": {
      "result": "clear",
      "breakdown": {
        "face_detection": {
          "result": "clear",
          "properties": {}
        }
      }
    },
    "image_integrity": {
      "result": "clear",
      "breakdown": {
        "supported_document": {
          "result": "clear",
          "properties": {}
        },
        "image_quality": {
          "result": "clear",
          "properties": {}
        },
        "colour_picture": {
          "result": "clear",
          "properties": {}
        },
        "conclusive_document_quality": {
          "result": "clear",
          "properties": {}
        }
      }
    },
    "compromised_document": {
        "result": "clear"
    }    
  }
}

The document report is composed of data integrity, visual authenticity and police record checks. It checks the internal and external consistency of the most recent identity document provided by the applicant to identify potential discrepancies.

In addition, any data extracted from the document through OCR is returned in the properties attribute.

The document report combines software and an expert team to maximise fraud detection. The majority of documents will be processed instantly. However, when document analysis falls back to expert review, the report status will be delivered asynchronously via webhook notifications.

Expert review is required when we encounter images that use sophisticated counterfeiting techniques, or the image is of poor quality (blurred, low resolution, obscured, cropped, or held at an unreadable angle).

Breakdown

visual_authenticity hash
Asserts whether visual, non-textual, elements are correct given the type of document
image_integrity hash
Asserts whether the document was of sufficient quality to verify
data_validation hash
Asserts whether algorithmically-validatable elements are correct e.g. MRZ lines and document numbers
data_consistency hash
Asserts whether data represented in multiple places on the document is consistent e.g. between MRZ lines and OCR extracted text on passports
data_comparison hash
Asserts whether data on the document is consistent with data provided by an applicant (either through Onfido’s applicant form or when creating an applicant through the API)
police_record hash
Asserts whether the document has been identified as lost, stolen or otherwise compromised
compromised_document hash
Asserts whether the image of the document has been found in our internal database of compromised documents

Sub breakdowns that are part of visual_authenticity may point to a fraudulent document if their result is consider:

fonts Fonts in the document don’t match the expected ones
security_features Security features expected on the document are missing or wrong
picture_face_integrity The pictures of the person identified on the document show signs of tampering or alteration. In most cases this will focus on the primary picture yet it may also apply to the secondary and tertiary pictures when documents contain them
digital_tampering Indication of digital tampering in the image (for example, name altered)
original_document_present The document is a genuine document and not, for example, a photo of a photo of a document
template The document doesn’t match the expected template for the document type and country it is from

A result of clear in the conclusive_document_quality breakdown of image_integrity will assert if the document was of enough quality to be able to perform a fraud inspection. A result of consider will mean that even if sub breakdowns of visual_authenticity fail, we cannot positively say the document is fraudulent or not (in cases such as parts of the document are not visible).

Street Level Report

{
  "id": "6951786-123123-154788",
  "name": "street_level",
  "created_at": "2014-05-23T13:50:33Z",
  "status": "complete",
  "result": "clear",
  "href": "/v2/checks/8546921-123123-123123/reports/6951786-123123-154788",
  "breakdown": {
    "slv_address": {
      "result": "clear"
    }
  },
  "properties": {}
}

A street level check confirms a person’s address by sending a letter to their home with a unique verification code. The applicant enters this code online to confirm their address.

Breakdown

address hash
Contains the result and details of an address match

Facial Similarity

Example Standard Response

{
  "id": "7c1dfeef-938b-4198-8e83-ef3b12282d39",
  "name": "facial_similarity",
  "created_at": "2016-05-10T13:50:33Z",
  "result": "clear",
  "status": "complete",
  "variant": "standard",
  "href": "/v2/checks/d79747be-9aab-420a-b16f-f0a2160ac13e/reports/7c1dfeef-938b-4198-8e83-ef3b12282d39",
  "breakdown": {
    "visual_authenticity": {
      "result": "clear"
    },
    "face_comparison": {
      "result": "clear"
    },
    "image_integrity": {
      "result": "clear"
    }
  },
  "properties": {
    "score": 0.7809
  }
}

Example Video Response

{
    "created_at": "2016-05-13T11:19:37Z",
    "href": "/v2/checks/7c688607-7a10-42f4-962b-452e34ab8964/reports/d32ea881-5f0c-48f3-ac59-515ab332cfe8",
    "id": "d32ea881-5f0c-48f3-ac59-515ab332cfe8",
    "name": "facial_similarity",
    "properties": {},
    "result": "clear",
    "status": "complete",
    "variant": "video",
    "breakdown": {
        "visual_authenticity": {
            "result": "clear",
            "breakdown": {
                "spoofing_detection": {
                    "result": "clear",
                    "properties": {}
                },
                "liveness_detected": {
                    "result": "clear",
                    "properties": {}
                }
            }
        },
        "face_comparison": {
            "result": "consider"
        },
        "image_integrity": {
            "result": "clear"
        }
    }
}

The facial similarity check will compare the most recent live photo or live video provided by the applicant to the photo in the most recent identity document provided. Depending on your configuration, the process may involve an expert review when the results are inconclusive.

There are two different variants of facial similarity report: standard which uses live photos and video which uses live videos.

breakdown

face_comparison hash
Asserts whether the face in the document matches the face in the live photo or live video
image_integrity hash
Asserts whether the quality of the uploaded files and the content contained within them were sufficient to perform a face comparison
visual_authenticity hash
Asserts whether the live photo or live video is not a spoof (such as photos of printed photos or photos of digital screens)

properties

The report will include a score property if the check did not involve a manual review procedure. The score property is a number between 0 and 1 that expresses how similar the two faces are, where 1 is a perfect match. If the report is completed manually or image integrity fails then the score property will not be present. The score only measures how similar the faces are, and does not make an assessment of the nature of the photo or video. If tampering (such as photos of printed photos or photos of digital screens) is detected the applicant will be rejected independently of the similarity score.

Standard

The standard variant uses live photos. The photo needs to be a live photo taken at the time of check submission, so that it can assess whether the holder of the identity document is the same person as the one on the document.

Video

Live videos are collected and uploaded by the Onfido iOS or Android SDKs. In addition to confirming the two faces match, the video variant assesses liveness by asking users to repeat randomly generated numbers and perform a random head movement. Thus preventing user impersonation via photos of photos, photos of screens, etc.

liveness_detected is an additional sub breakdown under visual_authenticity and asserts whether the numbers and head movements were correctly executed.

spoofing_detection asserts whether the live video is not a spoof (such as videos of digital screens).

Global Database

The following section outlines report types that are available globally to supplement identity verification and/or enrich pre-employment screening.

ReportNameVariantsStandard checkExpress check
Watchlist Report watchlist standard* full yes yes

*for watchlist, standard is going to be deprecated in favour of the full variant

Watchlist Report - Standard

{
  "created_at": "2015-01-11T16:54:56Z",
  "href": "/v2/checks/a49955d5-1e2c-417c-93e8-85ec45461c22/reports/6321a9de-f2b1-4037-bcb0-6d26947b0f4b",
  "id": "6321a9de-f2b1-4037-bcb0-6d26947b0f4b",
  "name": "watchlist",
  "result": "clear",
  "status": "complete",
  "breakdown": {
    "sanctions_and_politically_exposed_persons": {
      "result": "clear",
      "breakdown": {
        "politically_exposed_person": {
          "result": "clear",
          "properties": {}
        },
        "asset_sanctions": {
          "result": "clear",
          "properties": {}
        },
        "treasury_sanctions": {
          "result": "clear",
          "properties": {}
        }
      }
    }
  }
}

An international watchlist check will identify whether the applicant is listed on any global watchlists including: Government Sanctions Lists, Politically Exposed Persons Lists, Anti-Terrorism Watchlists, Anti-Money Laundering (AML) Watchlists, CIA Watchlists, Global and Disqualified Directors

A watchlist standard check provides an alert, and which will notify you if an applicant is listed on any global watchlists including: Government Sanctions Lists, Politically Exposed Persons Lists, Anti-Terrorism Watchlists, Anti-Money Laundering (AML) Watchlists, CIA Watchlists, Global and Disqualified Directors.

Breakdown

sanctions_and_politically_exposed_persons hash
Verifies the applicant against watchlists

Watchlist Report - Full

{
  "created_at": "2015-01-11T16:54:56Z",
  "href": "/v2/checks/a49955d5-1e2c-417c-93e8-85ec45461c22/reports/6321a9de-f2b1-4037-bcb0-6d26947b0f4b",
  "id": "6321a9de-f2b1-4037-bcb0-6d26947b0f4b",
  "name": "watchlist",
  "result": "consider",
  "status": "complete",
  "variant": "full",
  "properties": {
    "records": [
      {
        "associates": "",
        "keywords": "consul, director",
        "last_updated_utc": "2015-12-10T12:57:04Z",
        "entity_type": "person",
        "sources": "PEPs list",
        "types": "warning",
        "name": "Jim John Smith",
        "external_id": "M06IUM4DIQNZZ44",
        "match_types": "name_phonetic",
        "entity_fields_countries": "Canada",
        "report_id": 40863
      }
    ]
  },
  "breakdown": {
    "legal_and_regulatory_warnings": {
        "result": "consider"
    },
    "politically_exposed_person": {
        "result": "consider"
    },
    "sanction": {
        "result": "consider"
    }
  }
}

A watchlist full check goes beyond an alert by providing a granular breakdown of any records found when searching the global watchlists. The watchlists include: Government Sanctions Lists, Politically Exposed Persons Lists, Anti-Terrorism Watchlists, Anti-Money Laundering (AML) Watchlists, CIA Watchlists, Global and Disqualified Directors.

Two non-mandatory report options can be specified when you create a check for watchlist full reports. They are as follows:

Options
peps
sanctions

Specifying peps means only Politically Exposed Persons Lists will be searched. On the other hand, specifying sanctions means only Sanctions Lists and other watchlists will be searched. And if no options are specified, all watchlists will be researched.

This breakdown returned includes, but is not limited to: name of match, associates, date of birth, related keywords, type of list, name of list, and when the entry was last updated. This allows you to quickly assess the relevancy of the match and eliminate false positives.

Breakdown

legal_and_regulatory_warnings hash
politically_exposed_person hash
sanction hash

United Kingdom

The following section outlines report types that are specific to the United Kingdom.

ReportNameVariantsStandard checkExpress check
Credit Report credit yes yes
Criminal History Report criminal_history basic standard enhanced yes basic only
Right to Work Report right_to_work yes yes

Credit Report

{
  "created_at": "2015-06-19T08:52:08Z",
  "href": "/v2/checks/863fbc7f-c839-482c-bc04-c843b64802c8/reports/0eb0ef9d-60da-49ba-88c9-d2cf7080f6f8",
  "id": "0eb0ef9d-60da-49ba-88c9-d2cf7080f6f8",
  "name": "credit",
  "properties": {
    "number_of_ccjs": "0",
    "sum_of_ccj_value": "0",
    "number_of_bankruptcies": "0",
    "number_of_ivas": "0"
  },
  "result": "consider",
  "status": "complete",
  "breakdown": {
    "insolvency": {
      "result": "clear",
      "breakdown": {
        "bankruptcy_cases": {
          "result": "clear",
          "properties": {}
        },
        "iva_cases": {
          "result": "clear",
          "properties": {}
        }
      }
    },
    "county_court_judgments": {
      "result": "consider"
    }
  }
}

A UK credit report highlights any adverse financial history an applicant may have.

If an adverse financial history case is found, the report will list any bankruptcies, insolvencies, individual voluntary arrangements (IVA), or CCJs.

Criminal History Report

{
  "id": "6951786-123123-316712",
  "name": "criminal_history",
  "created_at": "2014-05-23T13:50:33Z",
  "status": "complete",
  "result": "clear",
  "variant": "enhanced"
  "href": "/v2/checks/8546921-123123-123123/reports/6951786-123123-316712",
  "breakdown": {},
  "properties": {}
}

A criminal history report identifies whether an applicant has a criminal record within the United Kingdom.

There are three different variants of criminal history report: basic, standard, and enhanced. Different roles require different levels of check; if you’re unsure which type you need try using the DBS Eligibility Tool, or our team at client-support@onfido.com can advise you on which choice is right for your company and roles.

A number of report options can be specified when you create a check for standard and enhanced reports. They are as follows:

VariantOptions
standardvolunteer working_at_home_address
enhancedchildren_barred_list adults_barred_list volunteer working_at_home_address

standard and enhanced criminal history reports also require additional details to be specified for us to be able to request data from the record agency. They should be specified when the check is created.

Document requirements

Document requirements for a basic criminal history report are

*under certain circumstances, if a check contains an identity report, a proof of address may not be required. Our team at client-support@onfido.com can advise you on the applicability.

When requesting a basic criminal history report as an express check, make sure these are uploaded before the check is created.

Applicant detail requirements

When requesting a basic criminal history report as an express check, make sure the following applicant attributes are specified

Right to Work Report

{
  "id": "6951786-123123-316712",
  "name": "right_to_work",
  "created_at": "2014-05-23T13:50:33Z",
  "status": "complete",
  "result": "clear",
  "href": "/v2/checks/8546921-123123-123123/reports/6951786-123123-316712",
  "breakdown": {},
  "properties": {}
}

A right to work report identifies whether an applicant has the right to work within the United Kingdom.

Document requirements

Document requirements for a right to work report are

for UK/EU/EEA (European Economic Area)/Swiss citizens

for citizens of other nationalities

When requesting a right to work report as an express check, make sure these are uploaded before the check is created.

USA

The following section outlines report types that are specific to the USA.

ReportNameVariantsStandard checkExpress check
SSN Trace Report ssn_trace yes yes
Sex Offender Report sex_offender yes yes
National Criminal Report national_criminal standard non_employment yes yes
County Criminal Report county_criminal yes yes
Driving Record Report driving_record yes yes
Eviction Report eviction yes yes
Watchlist Report watchlist yes yes
Drug Test Report drug_test five_panel seven_panel ten_panel yes yes

SSN Trace

{
  "created_at": "2015-01-11T16:11:19Z",
  "href": "/v2/checks/3810324d-5fbe-4849-b6da-5169a126a233/reports/6e506031-3968-457b-b1c5-de532bbc39e0",
  "id": "6e506031-3968-457b-b1c5-de532bbc39e0",
  "name": "ssn_trace",
  "properties": {
    "addresses": [
      {
        "street_number": "9570",
        "street": "VANGUARD DR",
        "flat_number": "APT 53",
        "town": "ANCHORAGE",
        "county": "ANCHORAGE",
        "state": "AK",
        "postcode": "99507",
        "from_date": "2005-08-01",
        "to_date": "2014-10-01"
      },
      {
        "street_number": "5565",
        "street": "S 152ND ST",
        "flat_number": "APT 39",
        "town": "TUKWILA",
        "county": "KING",
        "state": "WA",
        "postcode": "98188",
        "from_date": "2005-08-01",
        "to_date": "2014-10-01"
      }
    ],
    "phone_numbers": [
      {
        "number": "(661) 388-4044",
        "listed": true,
        "company_name": null
      }
    ]
  },
  "result": "clear",
  "status": "complete",
  "breakdown": {
    "date_of_birth": {
      "result": "clear"
    },
    "mortality": {
      "result": "clear"
    },
    "ssn": {
      "result": "clear"
    }
  }
}

An SSN Trace is comprised of a SSN match, a mortality check, a date of birth match and an optional address match.

The report will also return any addresses and phone numbers recorded by credit agencies in the last seven years against the given applicant’s SSN.

Running an SSN trace is a prerequisite of running county criminal checks to aid in the discovery of jurisdictions that should be searched for criminal records.

Breakdown

ssn hash
Contains the result and details of a SSN match
date_of_birth hash
Contains the result and details of a date of birth match
mortality hash
Asserts whether the applicant was found on the mortality register

Properties

addresses list
List of addresses associated with this applicant
phone_numbers list
List of phone numbers associated with this applicant

National Criminal Report

{
  "created_at": "2015-02-02T17:21:06Z",
  "href": "/v2/checks/713b6223-9369-47eb-8cce-d7f3b3391361/reports/99d4cd0f-6665-4425-bd8b-f2d19e890262",
  "id": "99d4cd0f-6665-4425-bd8b-f2d19e890262",
  "name": "national_criminal",
  "properties": {
      "records": [
          {
              "category": "CRIMINAL",
              "data_source": "IL COUNTY CIRCUIT CLERK OF COURTS",
              "state": "IL",
              "full_name": "JONH DOE",
              "first_name": "JOHN",
              "last_name": "DOE",
              "dob": "1975-10-15",
              "year_of_birth": 1975,
              "gender": "MALE",
              "eye_color": "BROWN",
              "weight": "160 POUNDS",
              "height": "5'10\"",
              "case_number": "2000XYZ000",
              "county": "JACKSON",
              "offenses": [
                  {
                      "description": "DRVG UNDER INFLU/BAC 0.08",
                      "case_type": "CLASS A MISDEMEANOR",
                      "disposition": "BOND FORFEITURE/30 DAY NOTICE",
                      "disposition_date": "04/03/2009",
                      "court": "CIRCUIT CLERK",
                      "plea": "GUILTY"
                  },
                  {
                      "description": "DRVG UNDER INFLU/BAC 0.08",
                      "case_type": "CLASS A MISDEMEANOR",
                      "disposition": "GUILTY",
                      "disposition_date": "04/14/2010",
                      "conviction_date": "04/14/2010",
                      "court": "CIRCUIT CLERK",
                      "plea": "GUILTY"
                  },
                  {
                      "description": "DRVG UNDER INFLU/BAC 0.08",
                      "case_type": "CLASS A MISDEMEANOR",
                      "disposition": "GUILTY",
                      "disposition_date": "04/14/2010",
                      "conviction_date": "04/14/2010",
                      "court": "CIRCUIT CLERK",
                      "plea": "GUILTY",
                      "comments": "SENTENCE LENGTH: 12 MONTHS"
                  }
              ]
          }
      ]
  },
  "result": "consider",
  "status": "complete",
  "breakdown": {
      "national_criminal": {
          "result": "consider"
      }
  }
}

A national criminal report performs a multi-jurisditional search on a database compiled from multiple sources: court records, incarceration records, probation/parole/release information and other proprietary sources.

If an applicant’s details match, the properties element will contain a breakdown of associated record(s).

Please note that a match for a single characteristic, e.g. full_name, is not sufficient, and the service will only report positive matches where 2 or more properties match (e.g. full_name and date of birth)

There are two different variants of national criminal report: standard and non_employment.

Standard

Adhering to the standards set out in the The Fair Credit Reporting Act (FCRA), the Employment version of the National Criminal Report double checks any records at the county-level to ensure that it is accurate and up to date when reported to employers making hiring decisions.

Please note that while the majority of the reports maintain a fast turnaround time, a small proportion require more in-depth investigation and this could take longer to complete.

Non-Employment

A National Criminal Report performs a multi-jurisdictional search on a database compiled from multiple sources: court records, incarceration records, probation/parole/release information and other proprietary sources.

If an applicant’s details match, the properties element will contain a breakdown of associated record(s).

Please note that a match for a single characteristic, e.g. full_name, is not sufficient, and the service will only report positive matches where 2 or more properties match (e.g. full_name and date of birth).

Breakdown

national_criminal hash
Asserts whether the applicant’s details match one or more known US criminal records.

Properties

records list
A list of criminal records matching the details of the given applicant

County Criminal Report

{
  "created_at": "2015-02-03T09:17:55Z",
  "href": "/v2/checks/09510cd9-31b1-4338-9011-631f59212d0f/reports/f6565fc2-51b1-487a-8cb6-8933f4c0e73a",
  "id": "f6565fc2-51b1-487a-8cb6-8933f4c0e73a",
  "name": "county_criminal",
  "properties": {
    "records": [
      {
        "full_name": "JOHN, DOE",
        "dob": "1970-01-01",
        "year_of_birth": 1970,
        "gender": "MALE",
        "weight": "150 POUNDS",
        "height": "5'10\" FT. IN.",
        "case_number": "2000CM123",
        "addresses": [
          {
            "address1": "SOME STREET, IL 123450000"
          }
        ],
        "offenses": [
          {
            "description": "RESIST/PEACE OFFICER/CORR EMP",
            "case_type": "CLASS A MISDEMEANOR",
            "disposition": "101 - GUILTY",
            "disposition_date": "11/20/2000",
            "offense_date": "10/22/2000",
            "court": "JACKSON COUNTY COURT",
            "comments": "SENTENCE 1 204 - PROBATION 12 MONTHS  IN FORCE 11/20/2000"
          }
        ]
      },
      {
        "full_name": "JOHN, DOE",
        "dob": "1970-01-01",
        "year_of_birth": 1970,
        "gender": "MALE",
        "weight": "178 POUNDS",
        "height": "5'10\" FT. IN.",
        "case_number": "2009Ov223",
        "addresses": [
          {
            "address1": "SOME STREET, IL 123450000"
          }
        ],
        "offenses": [
          {
            "description": "DISORDERLY CONDUCT",
            "case_type": "CLASS  OTHER",
            "disposition": "208 - DISMISS",
            "disposition_date": "07/24/2009",
            "offense_date": "04/26/2009",
            "court": "JACKSON COUNTY COURT"
          }
        ]
      }
    ]
  },
  "result": "consider",
  "status": "complete",
  "breakdown": {
    "county_criminal": {
      "result": "consider"
    }
  }
}

A county criminal report performs a search for criminal records on one/several jurisdictions. The results are not instant and the report will be ready to be returned once all of the individual county searches are completed.

If an applicant’s details match, the properties element will contain a breakdown of associated record(s).

Please note that a match for a single characteristic, e.g. full_name, is not sufficient, and the service will only report positive matches where 2 or more properties match (e.g. full_name and date of birth)

Breakdown

county_criminal hash
Asserts whether the applicant’s details match one or more known US county criminal records.

Properties

records list
A list of criminal records matching the details of the given applicant

Sex Offender Report

{
  "created_at": "2015-01-11T16:54:56Z",
  "href": "/v2/checks/a49955d5-1e2c-417c-93e8-85ec45461c22/reports/6321a9de-f2b1-4037-bcb0-6d26947b0f4b",
  "id": "6321a9de-f2b1-4037-bcb0-6d26947b0f4b",
  "name": "sex_offender",
  "properties": {
    "records": [
      {
        "registry": "WI SEX OFFENDER REGISTRY",
        "full_name": "JAKOB F DANE",
        "first_name": "JAKOB",
        "middle_name": "F",
        "last_name": "DANE",
        "age": 26,
        "dob": null,
        "year_of_birth": null,
        "gender": "MALE",
        "hair_color": "BLONDE",
        "eye_color": "GREEN",
        "weight": "200 LBS",
        "height": "6'0\"",
        "scarsmarks": "SCAR:EYEBROW, RIGHT/RIGHT EYE AREA; SCAR:FOREHEAD; SCAR:SCAR EYE, RIGHT OR RIGHT;",
        "photo_uri": "http://placehold.it/150x150",
        "aliases": [
          { "full_name": "BOB FRANCIS DANE" }
        ],
        "addresses": [
          {
            "address1": "12202 DUCK LA",
            "city": "COLUMBUS",
            "state": "WI",
            "zip": "53925"
          }
        ],
        "offenses": [
          {
            "description": "UNLAWFUL SEXUAL CONTACT SECOND DEGREE HAVE SEXUAL CONTACT",
            "statute": "DE-11-0768-0000-F-G",
            "disposition_date": "2003-15-07",
            "comments": ""
          }
        ]
      }
    ]
  },
  "result": "consider",
  "status": "complete",
  "breakdown": {
    "full_name": {
      "result": "consider"
    },
    "known_alias": {
      "result": "clear"
    },
    "address": {
      "result": "consider"
    },
    "date_of_birth": {
      "result": "clear"
    },
    "year_of_birth": {
      "result": "clear"
    },
    "age": {
      "result": "consider"
    }
  }
}

A sex offender report performs a search across all US state sex offender registries to verify whether or not an applicant’s details match the details of a registered sex offender.

If an applicant’s details match, the properties element will contain a breakdown of associated registration record(s), including physical characteristics for further verification.

Please note that a match for a single characteristic, e.g. full_name, is not sufficient, and the service will only report positive matches where 2 or more properties match (e.g. full_name and date of birth, full_name and age and address)

Breakdown

full_name hash
Whether the applicant’s name matches a record in a US sex offender database
known_alias hash
Whether the applicant’s name matches a known alias in a US sex offender database
address hash
Whether any of the addresses linked to the applicant’s SSN or provided through the API match the offender database
date_of_birth hash
Whether the applicant’s date of birth matches the offender database
year_of_birth hash
Whether the applicant’s year of birth matches the offender database
age hash
Whether the applicant’s age matches the offender database

Properties

records list
A list of sex offender registration records matching the details of the given applicant

Driving Record Report

{
  "created_at": "2015-02-02T17:21:06Z",
  "href": "/v2/checks/713b6223-9369-47eb-8cce-d7f3b3391361/reports/99d4cd0f-6665-4425-bd8b-f2d19e890262",
  "id": "99d4cd0f-6665-4425-bd8b-f2d19e890262",
  "name": "driving_record",
  "result": "consider",
  "status": "complete",
  "breakdown": {
    "driving_license": {
      "result": "clear"
    },
    "driving_restrictions": {
      "result": "clear"
    },
    "driving_violations": {
      "result": "consider"
    },
    "driving_accidents": {
      "result": "consider"
    }
  },
  "properties": {
    "full_name": "Alfred Nagy",
    "license_number": "1234567",
    "license_status": "valid",
    "license_type": "non-commercial",
    "license_class": "C",
    "issued_date": "2008-01-01",
    "expiration_date": "2018-01-01",
    "restrictions": [],
    "accidents": [
      {
        "accident_date": "2010-01-01",
        "description": "property damage",
        "city": "Cambridge",
        "county": "Boston",
        "state": "MA",
        "points": null,
        "vehicle_speed": null,
        "reinstatement_date": null,
        "action_taken": "police report filed",
        "ticket_number": null,
        "enforcing_agency": "Cambridge PD",
        "jurisdiction": null,
        "severity": null,
        "violation_number": null,
        "license_plate": "1A2B3C4D",
        "fine_amount": null,
        "state_code": null,
        "acd_code": null,
        "additional_info": null,
        "injury_accident": false,
        "fatality_accident": false,
        "fatality_count": 0,
        "injury_count": 0,
        "vehicles_involved_count": 1,
        "report_number": null,
        "policy_number": null
      }
    ],
    "violations": [
      {
        "type": "conviction",
        "issued_date": "2014-01-01",
        "conviction_date": "2014-01-01",
        "description": "speeding",
        "points": 0,
        "city": "Cambridge",
        "county": "Boston",
        "state": "MA",
        "ticket_number": "ABCD1234",
        "disposition": null,
        "category": null,
        "court_name": null,
        "acd_code": null,
        "docket": null,
        "additional_info": null
      }
    ]
  }
}

A driving record report searches a candidate’s driving history, as recorded against their license number by the relevant state DMV.

Breakdown

driving_license hash
Asserts whether the license details provided matched a real license
driving_restrictions hash
Asserts whether restrictions were found for a given applicant’s details
driving_violations hash
Asserts whether traffic violations were found for a given applicant’s details
driving_accidents hash
Asserts whether accident records were found for a given applicant’s details

Eviction Report

{
  "created_at": "2015-01-11T16:54:56Z",
  "href": "/v2/checks/a49955d5-1e2c-417c-93e8-85ec45461c22/reports/6321a9de-f2b1-4037-bcb0-6d26947b0f4b",
  "id": "6321a9de-f2b1-4037-bcb0-6d26947b0f4b",
  "name": "eviction",
  "properties": {
    "records": [
      {
        "address": "123 PIKE ST",
        "city": "SEATTLE",
        "state": "WA",
        "zip": "98101",
        "caseno": "125GV6465464565",
        "filingdate": "03/27/2012",
        "judgementamount": "0",
        "plaintiff": "PLAINTIFF NAME",
        "noticetype": "CIVIL NEW FILING",
        "court": "CITY DISTRICT COURT"
      },
      {
        "address": "555 PIKE ST",
        "city": "SEATTLE",
        "state": "WA",
        "zip": "98101",
        "caseno": "125GV6465464999",
        "filingdate": "10/22/2014",
        "judgementamount": "0",
        "plaintiff": "PLAINTIFF NAME",
        "noticetype": "CIVIL NEW FILING",
        "court": "CITY DISTRICT COURT"
      }
    ]
  },
  "result": "consider",
  "status": "complete",
  "breakdown": {
    "eviction": {
      "result": "consider"
    }
  }
}

A eviction report performs a search of millions of landlord-tenant records, historical residential leasing behaviors, past court actions, unlawful detainers, monetary judgments, court-ordered possession and property damage claims.

If an applicant’s details match, the properties element will contain a breakdown of associated eviction record(s), including the address the applicant was evicted from, and any associated court case numbers.

Breakdown

eviction hash
Asserts whether the applicant’s details match one or more known eviction records

Properties

records list
A list of eviction records matching the details of the given applicant

US Watchlist Report

{
  "created_at": "2015-01-11T16:54:56Z",
  "href": "/v2/checks/a49955d5-1e2c-417c-93e8-85ec45461c22/reports/6321a9de-f2b1-4037-bcb0-6d26947b0f4b",
  "id": "6321a9de-f2b1-4037-bcb0-6d26947b0f4b",
  "name": "watchlist",
  "properties": {
    "records": [
      {
        "watchlist": "FEDERAL BUREAU OF INVESTIGATION TOP TEN MOST WANTED",
        "full_name": "JASON D BROWN",
        "first_name": "JASON",
        "middle_name": "D",
        "last_name": "BROWN",
        "dob": "1969-07-01",
        "year_of_birth": 1969,
        "birth_state": "CALIFORNIA",
        "gender": "MALE",
        "hair_color": "BLONDE",
        "eye_color": "GREEN",
        "weight": "170 LBS",
        "height": "5'10\"",
        "photo_uri": "https://www.crimimages.net/images/getPhoto.aspx?photo=JMgwx%2beQdOEHhZsBgsgYfhBO8Eri5Z%2f7%2fSRd%2bBGYgGnUKMhphO5uf5PepEhb%2fYom",
        "aliases": [
          {
            "full_name": "JASON DEREK BROWN"
          },
          {
            "full_name": "DEREK BROWN"
          },
          {
            "full_name": "GREG HARLINE JOHNSON"
          }
        ],
        "offenses": [
          {
            "description": "ARMED ROBBERY",
            "disposition": null,
            "comments": ""
          },
          {
            "description": "UNLAWFUL FLIGHT TO AVOID PROSECUTION - FIRST DEGREE MURDER",
            "disposition": null,
            "comments": ""
          }
        ]
      }
    ]
  },
  "result": "consider",
  "status": "complete",
  "breakdown": {
    "watchlist": {
      "result": "consider"
    }
  }
}

A US watchlist report performs a search across databases covering US and foreign sanctions and watchlists, including terrorist watchlists. A full list of the databases checked can be found here.

If an applicant’s details match, the properties element will contain a breakdown of associated watchlist record(s), including physical characteristics for further verification.

Please note that a match for a single characteristic, e.g. full_name, is not sufficient, and the service will only report positive matches where 2 or more properties match (e.g. full_name and date of birth, full_name and age and address)

Breakdown

watchlist hash
Asserts whether the applicant’s details match one or more known national or international watchlists

Properties

records list
A list of watchlist records matching the details of the given applicant

Drug Test Report

{
  "created_at": "2016-09-06T17:01:57Z",
  "href": "/v2/checks/7191e58e-30c0-4a56-8b42-2abcb6a399a9/reports/4f443e79-56d9-4a18-9e0e-616fd4efce88",
  "id": "4f443e79-56d9-4a18-9e0e-616fd4efce88",
  "name": "drug_test",
  "properties": {
    "10 Panel Test": [
      {
        "type": "Drug 2",
        "value": "Clear"
      },
      {
        "type": "Drug 1",
        "value": "Clear"
      }
    ]
  },
  "result": "consider",
  "status": "complete",
  "variant": "ten_panel",
  "breakdown": {
    "specimen_analysis": {
      "result": "consider"
    }
  }
}

A drug test report verifies applicants for abuse of illegal substances through a certified nationwide third-party specialists. There are three different variants of drug test report: five_panel, seven_panel, and ten_panel.

Breakdown

specimen_analysis hash
Asserts whether the applicant has previously failed a specimen analysis

India

The following section outlines report types that are specific to India.

ReportNameStandard checkExpress check
Aadhaar Card report aadhaar_card yes yes
Pan Card Report pan_card yes yes

Aadhaar Card

{
  "created_at": "2017-10-29T14:13:20Z",
  "href": "/v2/checks/902c4f26-4fbc-4caa-a894-d04919544554/reports/554a5788-192a-4c09-a92d-7f5f26d43960",
  "id": "554a5788-192a-4c09-a92d-7f5f26d43960",
  "name": "aadhaar_card",
  "properties": {},
  "result": "clear",
  "status": "complete",
  "sub_result": null,
  "variant": "standard",
  "breakdown": {
    "name": {
      "result": "clear"
    },
    "date_of_birth": {
      "result": "clear"
    }
  }
}

An Aadhaar Card check is comprised of a name match and a date of birth match on the provided Aadhaar number.

It can be run on its own to assert a Aadhaar number belongs to an individual or run in addition to a document report to assert the document contains a valid Aadhaar number, associated with the name and date of birth on the document.

Breakdown

name hash
Contains the result for a name match
date_of_birth hash
Contains the result for a date of birth match

PAN Card

{
  "created_at": "2017-10-25T08:56:42Z",
  "href": "/v1/checks/b7cb184b-e33f-4bf1-bffa-32b932498a4d/reports/64c7000f-c21b-46d9-abfb-eb75e4274f01",
  "id": "64c7000f-c21b-46d9-abfb-eb75e4274f01",
  "name": "pan_card",
  "properties": {},
  "result": "clear",
  "status": "complete",
  "sub_result": null,
  "variant": "standard",
  "breakdown": {
    "pan": {
      "result": "clear",
      "breakdown": {
        "name_matched": {
          "result": "clear",
          "properties": {}
        },
        "pan_is_valid": {
          "result": "clear",
          "properties": {}
        }
      }
    }
  }
}

A PAN Card Report check is comprised of a Permanent Account Number (PAN) validity check and a name match against the provided PAN.

This can be run on its own to assert a Permanent Account Number (PAN) belongs to an individual or can be run together with a document report to assert the document contains a valid PAN, associated with the name on the document.

Breakdown

name_matched hash
Contains the result and details of a name match for the provided PAN
pan_is_valid hash
Asserts whether the provided PAN is a valid one

Overview

Conditional Checks is a feature that, when enabled, allows the processing of reports based on certain conditions configured by Onfido for its clients. These conditions can be the overall result of a report, the result of a specific breakdown for a report, the applicant’s nationality, etc.

Enabling Conditional Checks

To enable this feature on your account, you need to contact api@onfido.com.

Use Cases

Conditional Checks makes the system smarter and adaptive to different workflows. Two examples of workflows:

  1. Identity and Street Level Reports: Only perform SLV if Identity Report fails to confirm the applicant address as shown in the figure below;
  2. Identity, Document and Criminal Reports: Only do the Criminal Report if both Identity and Document Reports pass as it might make no sense to do a Criminal Report on an applicant whose identity is not yet verified.

Figure 1

All these scenarios and flows also can be combined together to perform more complex workflows, without adding any complexity to how you use the API. Needless to say that these are just examples but Conditional Checks can support any business specific workflow.

When you request enabling this feature on your account, please communicate your workflow and conditions for processing the check to api@onfido.com. These conditions will be preconfigured on your account and won’t require any change in the way you create the checks via the API.

Report Status Flow

Any report that’s waiting for condition to be evaluated will be in the status paused. When the condition is evaluated the report will either move to awaiting_data and its processing starts OR to cancelled if the condition to process it is not met.

Limitations

While Conditional Checks allow reports to be processed based on a series of conditions, you still have to specify all the reports and supply all the required information for each report upfront when you create the checks.

Example

If you want a Document report only if the Identity report fails, you still have to request both reports using the Create Check endpoint and you need to satisfy all the requirements needed for the reports by providing the necessary applicant info.

Usage Notes

There are generally 2 ways to create a check via the API:

  1. By passing in all the reports of the check;
  2. Using report type groups.

If you are using the conditional checks feature, you must use report type groups because this way the system will be able to recognize the checks that you have configured with conditions as opposed to any other similar checks in your account that you might want to request without requiring any conditions to be enforced on them.