NAV
shell Ruby Python PHP
v1
v2
v1

Introduction

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

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:

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/v1/applicants
require 'onfido'

Onfido.configure do |config|
  config.api_key = 'TOKEN'
end
from onfido import Api
api = Api("TOKEN")
# First add onfido/api-php-client to your compose file
require 'vendor/autoload.php';
Onfido\Configuration::getDefaultConfiguration()->setApiKey('Authorization', 'token=' . 'YOUR_API_KEY');
Onfido\Configuration::getDefaultConfiguration()->setApiKeyPrefix('Authorization', 'Token');
$api_instance = new Onfido\Api\DefaultApi();

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 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
500 Internal Server Error An unexpected error occurred in our API

Error types

Error Code Type Suggestion
400 bad_request: ‘The request could not be understood by the server, please check your request is correctly formatted’ Ensure your request is in the correct format.
401 authorization_error: ‘Authorization error: please re-check your credentials’ Ensure you have entered your API token correctly and are using the right token e.g. live or test.
401 unauthorized_request: ‘Unauthorized’ Ensure you have entered your API token correctly and are using the right token e.g. live or test.
401 user_authorization_error: ‘User is not allowed to access API: please recheck your permissions’ User is currently ‘read only’. You need to contact an Admin to change to ‘standard user’. This will enable you to access the API.
401 bad_referrer: ‘Unexpected referrer: %{referrer}, please check the referrer used to generate the token’ This relates to JWT tokens only. Check the referrer argument correctly specifies the URL of the webpage. See SDK Tokens for guidance.
401 expired_token: The token has expired, please request a new one This relates to JWT tokens only. These expire after 90 mins. You need to issue a new one. See SDK Tokens for guidance.
401 unauthorized_slv_code: ‘Unauthorized’ Applicant has not entered correct Street Level Verification Check code
404 resource_not_found: ‘The resource could not be found’ Ensure you have formatted the URI correctly.
422 validation_error: ‘There was a validation error on this request’ Check the fields property for a specific error message.
422 check_limit_reached: ‘Applicants limit reached. Please upgrade your plan or wait until the date of renewal’ Contact Client Support for guidance
422 missing_billing_info: ‘Please provide your billing information before starting a new check’ Contact Client Support for guidance
422 missing_documents: ‘Please upload the required documents before starting a check’ See Upload document for guidance
422 cant_charge_applicant: ‘charge_applicant_for_check cannot be set to true for express checks’ Either charge_applicant_for_check or express should be false
422 cant_charge_applicant_on_conditional_checks: ‘charge_applicant_for_check cannot be set to true when creating a check based on conditional-based report_type_groups’ charge_applicant_for_check should be false
422 invalid_reports_names:‘Unprocessable Entity’ Ensure you have entered the report name in the correct format. View a request example for your chosen Report Type for guidance e.g. see Document Report
422 missing_id_numbers:‘Unprocessable Entity’ Please ensure you have supplied relevant ID number e.g. National Insurance number or Social Security number
422 invalid_check_type_for_variant:‘Unprocessable Entity’ Only certain variants can be performed on certain checks. See Report Types for guidance
422 standard_check_photo_facial_sim_without_document: ‘Unprocessable Entity’ Applicant has not submitted a document image
422 invalid_or_expired_slv_code: ‘Unprocessable Entity’ Applicant has not entered Street Level Verification Check code within 15 days or has entered incorrect code
422 unprocessable_slv_code: ‘Unprocessable Entity’ Applicant has not entered correct Street Level Verification Check code
422 failed_check_requirements: ‘Check requirements have not been met for this request’ Check all required information has been provided and correctly specified. Ensure any uploads are in the correct format. View an example of a check containing your chosen report in Report Types
422 incomplete_checks: ‘Check cannot be created as there are other ongoing checks associated with this applicant’ A check on an applicant must be completed before another can commence
500 internal_server_error : ‘We’re sorry, but something went wrong’ The server encountered an error, retry the request. If this message is occuring repeatedly contact Client Support

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/v1/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):

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/v1/applicants?page=1&per_page=50>; rel="first",
        <https://api.onfido.com/v1/applicants?page=4&per_page=50>; rel="last",
        <https://api.onfido.com/v1/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/v1/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.

Applicants

Applicant object

{
  "id": "1030303-123123-123123",
  "created_at": "2014-05-23T13:50:33Z",
  "href": "/v1/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",
  "id_numbers": [
    {
      "type": "ssn",
      "value": "433-54-3937"
    },
    {
      "type": "driving_licence",
      "value": "I1234562",
      "state": "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 background 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
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, 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/v1/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\Models\Applicant();
$applicant->setFirstName('John');
$applicant->setLastName('Smith');
# ...

$address1 = new \Onfido\Models\Address();
$address1->setBuildingNumber('100');
$address1->setStreet('Main Street');
$address1->setPostcode('WC2E 9LG');
$address1->setTown('London');
$address1->setCountry('GBR');

$applicant->setAddresses([$address1]);

$api_instance->createApplicant($applicant);

EXAMPLE RESPONSE

{
  "id": "1030303-123123-123123",
  "created_at": "2014-05-23T13:50:33Z",
  "href": "/v1/applicants/1030303-123123-123123",
  "title": "Mr",
  "first_name": "John",
  "middle_name": null,
  "last_name": "Smith",
  "gender": "Male",
  "dob": "2013-02-17",
  "telephone": "02088909293",
  "country": "GBR",
  "mobile": 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/v1/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.
id_numbers optional
A collection of identification numbers belonging to this applicant
addresses optional
The address history of the applicant

Retrieve applicant

$ curl https://api.onfido.com/v1/applicants/1030303-123123-123123 \
  -H "Authorization: Token token=your_api_token"
api.applicant.find('1030303-123123-123123')
api.Applicants.find('1030303-123123-123123')
$api_instance->findApplicant('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/v1/applicants/{applicant_id}

List applicants

$ curl https://api.onfido.com/v1/applicants \
  -H "Authorization: Token token=your_api_token"
api.applicant.all
api.Applicants.all()
$api_instance->listApplicants();

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/v1/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": "/v1/applicants/1030303-123123-123123/documents/7568415-123123-123123",
  "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
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 documents:

Type
work_permit
national_insurance
birth_certificate
bank_statement

Upload document

$ curl https://api.onfido.com/v1/applicants/1030303-123123-123123/documents \
  -H 'Authorization: Token token=your_api_token' \
  -d '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)
$applicant_id = '1030303-123123-123123';
$type = 'passport';
$side = 'front';
$file = "/path/to/file.txt";

$api_instance->uploadDocument($applicant_id, $type, $side, $file);

EXAMPLE RESPONSE

{
  "id": "7568415-123123-123123",
  "created_at": "2014-05-23 13:50:33Z",
  "href": "/v1/applicants/1030303-123123-123123/documents/7568415-123123-123123",
  "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/v1/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.

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": "/v1/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/information_requests/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. Append .pdf to get the pdf file.
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, background check is cancelled.
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/v1/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]=children_barred_list' \
  -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" }]
})
$applicant_id = '1030303-123123-123123'

$check = new Onfido\Models\CheckCreationRequest();
$check->setType('express');

$report = new Onfido\Models\Report();
$report->setName('identity');

$check->setReports(array($report));
$api_instance->createCheck($applicant_id, $check);

EXAMPLE RESPONSE

{
  "id": "8546921-123123-123123",
  "created_at": "2014-05-23T13:50:33Z",
  "href": "/v1/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": "/v1/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": "/v1/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.

ENDPOINT

POST https://api.onfido.com/v1/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 required
Array of Reports being requested for this check.
tags optional
Array of tags being assigned to this 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)

Retrieve check

$ curl https://api.onfido.com/v1/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)
$applicant_id = "1030303-123123-123123";
$check_id = "8546921-123123-123123";

$api_instance->findCheck($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/v1/applicants/{applicant_id}/checks/{check_id}

List checks

$ curl https://api.onfido.com/v1/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)
$applicant_id = "1030303-123123-123123";

$api_instance->listChecks($applicant_id);

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

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

Resume check

$ curl https://api.onfido.com/v1/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/v1/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,
  "variant": null,
  "options": {},
  "href": "/v1/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
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 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 clear or unidentified as their results.

Retrieve report

$ curl https://api.onfido.com/v1/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)
$check_id = "8546921-123123-123123";
$report_id = "1256879-123123-456789";

$api_instance->findReport($check_id, $report_id);

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

Endpoint

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

List reports

$ curl https://api.onfido.com/v1/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)
$check_id = "8546921-123123-123123";

$api_instance->listReports($check_id);

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

Endpoint

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

Webhooks

Onfido provides webhooks to alert you of changes in the status of your resources. 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.

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.

Events

The following events will trigger a message to registered webhooks:

Resource Events
report report.completed
report report.withdrawn
check check.started
check check.completed
check check.form_opened
check check.form_completed

Event object

{
  "payload": {
    "resource_type": "report",
    "action": "report.completed",
    "object": {
      "id": "12345-23122-32123",
      "status": "completed",
      "completed_at": "2014-05-23T13:50:33Z",
      "href": "https://api.onfido.com/v1/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/v1/webhooks \
  -H "Authorization: Token token=your_api_token" \
  -d 'url=https://webhookendpoint.url' \
  -d 'enabled=true' \
  -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": "/v1/webhooks/fcb73186-0733-4f6f-9c57-d9d5ef979443",
  "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/v1/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.
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/v1/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/v1/webhooks/{webhook_id}

List webhooks

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

EXAMPLE RESPONSE

{
  "webhooks": [
    {
      "id": "dd0a89e4-d44e-417a-aec4-01137d01ae59",
      "url": "https://demo.com","enabled":false,
      "href": "/v1/webhooks/dd0a89e4-d44e-417a-aec4-01137d01ae59",
      "token": "yV85IsmuYwmjQGlZ",
      "events": [
        "check.started"
      ]
    },
    {
      "id": "bfc727a8-f7bf-4073-b123-ed70a70f58e5",
      "url": "https://demo2.com",
      "enabled": true,
      "href": "/v1/webhooks/bfc727a8-f7bf-4073-b123-ed70a70f58e5",
      "token": "yV85IsmuYwmjQGlZ",
      "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/v1/webhooks/

Address Picker

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

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/v1/addresses/pick

Arguments

postcode string
The applicant’s postcode

Identity Verification

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

ReportName
Identity Report identity
Document Reportdocument
Street Level Reportstreet_level

Identity Report

{
  "id": "6951786-123123-316712",
  "name": "identity",
  "created_at": "2014-05-23T13:50:33Z",
  "status": "complete",
  "result": "clear",
  "href": "/v1/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": {}
        }
      }
    },
    "mortality": {
      "result": "clear"
    }
  },
  "properties": {}
}

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

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

The example to the right details results for a identity report conducted in the United Kingdom.

Breakdown

address hash
Contains the result and details of an address 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

Document Report

{
  "id": "1256879-123123-456789",
  "name": "document",
  "created_at": "2014-05-23T13:50:33Z",
  "status": "complete",
  "result": "clear",
  "href": "/v1/checks/8546921-123123-123123/reports/1256879-123123-456789",
  "breakdown": {
    "data_integrity": {
      "result": "clear",
      "breakdown": {
        "data_comparison_supplied_document_type": {
          "result": "clear"
        },
        "data_comparison_supplied_last_name": {
          "result": "clear"
        },
        "data_comparison_supplied_first_name": {
          "result": "clear"
        },
        "data_comparison_supplied_gender": {
          "result": "clear"
        },
        "check_sum_general": {
          "result": "consider"
        },
        "check_sum_document_number": {
          "result": "consider"
        },
        "check_sum_date_of_expiry": {
          "result": "consider"
        },
        "check_sum_date_of_birth": {
          "result": "consider"
        }
      }
    },
    "police_record": {
      "result": "clear"
    },
    "image_quality": {
      "result": "clear"
    }
  },
  "properties": {
    "document_type": "passport",
    "first_name": "John",
    "last_name": "Smith",
    "gender": "Male",
    "date_of_birth": "1987-12-01",
    "date_of_expiry": "2016-02-25",
    "document_number": "AA1234567",
    "issuing_country": "GBR",
    "nationality": "GBR",
    "mrz_line1": "P<GBRSMITH<<JOHN<<<<<<<<<<<<<<<<<<<<<<<<<<<<",
    "mrz_line2": "AA1234567<6GBR8710317M2204237<<<<<<<<<<<<<<<6",
    "mrz_line3": null
  }
}

The document report is composed of a data integrity analysis and a police record check. It checks the internal and external consistency of an identity document 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

data_integrity hash
Asserts whether the information contained in the document is correct for the document type.
police_record hash
Asserts whether the document has been recorded as lost, stolen or compromised.
image_quality hash
Asserts whether the document was of sufficient quality to verify

Street Level Report

{
  "id": "6951786-123123-154788",
  "name": "street_level",
  "created_at": "2014-05-23T13:50:33Z",
  "status": "complete",
  "result": "clear",
  "href": "/v1/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

Global Database

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

ReportNameVariants
Watchlist Report watchlist standard full
Education Report education
Negative Media Report negative_media

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

Standard

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

United Kingdom

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

ReportNameVariants
Credit Reportcredit
Criminal History Report criminal_history basic standard enhanced
Directorship Report directorship
Employment Reportemployment_history

Credit Report

{
  "created_at": "2015-06-19T08:52:08Z",
  "href": "/v1/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": "/v1/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. They are as follows:

VariantOptions
standardvolunteer working_at_home_address
enhancedchildren_barred_list adults_barred_list volunteer working_at_home_address