Introduction
The Onfido API is used to submit check requests. The API is built using RESTful endpoints and standard HTTP verbs.
- Response codes are used to indicate the status of the message and any error codes.
- JSON is returned on all our API responses, including errors, with a consistent structure for all messages.
- Authentication to the API is performed via token-based auth.
- Requests to our API should be made as JSON, except when uploading documents.
- All API requests must be made over HTTPS. Calls made over plain HTTP will fail.
- All requests must use TLS 1.2 or above, with Server Name Indication enabled
- Text fields support UTF-8, but do not allow certain special characters that could be used maliciously.
Getting Started
This step-by-step guide introduces you to the Onfido API.
It offers an opportunity to perform a Document and Face Check in the sandbox environment with a sample identity document and photo.
Let’s get going!
Select a check type
First, let’s think about our check type.
Onfido offers a Standard Check and an Express Check.
All Standard checks have a workflow that sends an email to an applicant with a link to a form. The applicant then completes the form with their information.
All Express checks involve submitting the applicant’s information up-front via the API. Express checks have the following typical workflow.
An Applicant object is created.
Documents and photos are uploaded to the Applicant object (if required).
A Check is constructed consisting of one or more Reports.
We are going to perform an Express Check.
Find your sandbox token
Creating a check requires a token for authorization.
Your sandbox token can be found under the 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 don’t have a sandbox token, one can be generated from the Onfido Dashboard. See How to generate a sandbox token
Create an applicant
CREATE AN APPLICANT
$ curl https://api.onfido.com/v2/applicants \
-H 'Authorization: Token token=YOUR_API_TOKEN' \
-d 'title=Ms' \
-d 'first_name=Jane' \
-d 'middle_name=Smith'
-d 'last_name=Doe' \
-d 'gender=female' \
-d 'dob=1990-01-01' \
-d 'country=GBR' \
require 'onfido'
Onfido.configure do |config|
config.api_key = <YOUR_API_TOKEN>
end
api = Onfido::API.new
applicant_hash = {first_name: "Jane", last_name: "Doe"}
applicant = api.applicant.create(applicant_hash)
import onfido
onfido.configuration.api_key['Authorization'] = 'token=' + <YOUR_API_TOKEN>
onfido.configuration.api_key_prefix['Authorization'] = 'Token'
api = onfido.DefaultApi()
applicant_data = onfido.Applicant()
applicant_data.first_name = 'Jane'
applicant_data.last_name = 'Doe'
applicant = api.create_applicant(data=applicant_data)
require_once('./vendor/autoload.php');
Onfido\Configuration::getDefaultConfiguration()->setApiKey('Authorization', 'token=' . <YOUR_API_TOKEN>);
Onfido\Configuration::getDefaultConfiguration()->setApiKeyPrefix('Authorization', 'Token');
$api = new Onfido\Api\DefaultApi();
$applicantData = new Onfido\Models\Applicant();
$applicantData->setFirstName('Jane');
$applicantData->setLastName('Doe');
$applicant = $api->createApplicant($applicantData);
CREATE AN APPLICANT RESPONSE
{
"id": "<APPLICANT_UUID>",
"created_at": "2018-07-20T10:50:33Z",
"sandbox": false,
"title": null,
"first_name": "Jane",
"middle_name": "Smith",
"last_name": "Doe",
"email": null,
"gender": "female",
"dob": 1990-01-01,
"telephone": null,
"mobile": null,
"nationality": null,
"country": "gbr",
"href": "/v2/applicants/<APPLICANT_UUID>",
"mothers_maiden_name": null,
"country_of_birth": null,
"town_of_birth": null,
"previous_last_name": null,
"id_numbers": [],
"addresses": []
}
The first step in any check is to create an applicant.
Copy the curl command on the right.
Replace
YOUR_API_TOKENwith your sandbox token.Run the code in your console to create an applicant object. You should see the created applicant object in the response.
Note down the
APPLICANT_UUID, you will need this for the next step.
Uploads
This check is composed of a Document Report and a Facial Similarity Report - standard (photo) variant.
This workflow performs 3 verifications:
- It checks that an applicant’s identity document is genuine
- It compares the photo on the identity document with an applicant’s ‘live’ photo to ensure it is the same person on both.
- It verifies that the ‘live’ photo is genuine and not a copy of a photo or a photo of a screen.
For the next steps, you will need to download a sample identity document and a sample photo (of the same person).
NOTE: In practice, a ‘live’ photo is acquired at the same time as the check is performed.
Upload an ID document
UPLOAD AN ID DOCUMENT
curl https://api.onfido.com/v2/applicants/<APPLICANT_ID>/documents \
-H 'Authorization: Token token=<YOUR_API_TOKEN>' \
-F 'file=@path/to/sample_driving_licence.png;type=image/png' \
-F 'type=driving_licence' \
-F 'side=front'
applicant_id = applicant['id']
file = open('./path/to/sample_driving_licence.png')
document = api.document.create(applicant_id, file: file, type: 'driving_licence', side: 'front')
applicant_id = applicant.id
document = api.upload_document(applicant_id, 'driving_licence', side='front', file='path/to/document.png')
$applicant_id = $applicant['id'];
$type = "driving_licence";
$side = "front";
$file = new SplFileObject('path/to/sample_driving_licence.png');
$document = $api->uploadDocument($applicant_id, $type, $side, $file);
UPLOAD AN ID DOCUMENT RESPONSE
{
"id": "<DOCUMENT_ID>",
"created_at": "2018-07-20T13:45:28Z",
"file_name": "path/to/sample_driving_licence.png",
"file_type": "png",
"file_size": 706584,
"type": "driving_licence",
"side": "front",
"issuing_country": null,
"href": "/v2/applicants/<APPLICANT_ID>/documents/<DOCUMENT_ID>",
"download_href":"/v2/applicants/<APPLICANT_ID>/documents/<DOCUMENT_ID>/download"
}
Copy the curl command on the right (URI ending with ‘documents’).
Replace
YOUR_API_TOKENwith your sandbox token.Run the code in your console to upload the document.
You should see the created document object in the response.
Upload a photo
UPLOAD A PHOTO
curl https://api.onfido.com/v2/live_photos \
-H 'Authorization: Token token=<YOUR_API_TOKEN>' \
-F 'applicant_id=<APPLICANT_UUID>' \
-F 'file=@path/to/sample_photo.png;type=image/png'
file = open('./path/to/sample_photo.png')
live_photo = api.live_photo.create(applicant_id, file: file)
live_photo = api.upload_live_photo(applicant_id, file='path/to/sample_photo.png')
$file = new SplFileObject('path/to/sample_photo.png');
$live_photo = $api->uploadLivePhoto($applicant_id, $file);
UPLOAD A PHOTO RESPONSE
{
"id": "<LIVE_PHOTO_ID>",
"created_at": "2018-07-23T08:37:32Z",
"file_name": "path/to/sample_photo.png",
"file_type": "png",
"file_size": 196437,
"href": "/v2/live_photos/<LIVE_PHOTO_ID>",
"download_href": "/v2/live_photos/<LIVE_PHOTO_ID>/download"
}
Copy the curl command on the right (URI ending with ‘live_photos’).
Replace
YOUR_API_TOKENwith your sandbox token.Run the code in your console to upload the photo.
You should see the created photo object in the response.
Create a check
CREATE A CHECK
curl https://api.onfido.com/v2/applicants/applicant_id/checks \
-H 'Authorization: Token token=your_api_token' \
-d 'type=express' \
-d 'reports[][name]=document'
-d 'reports[][name]=facial_similarity'
-d 'reports[][variant]=standard'
reports = [{name: 'document'}, {name: 'facial_similarity', variant: 'standard'}]
check = api.check.create(applicant_id, type: 'express', reports: reports)
check_data = onfido.CheckCreationRequest()
check_data.type = 'express'
document_report = onfido.Report()
document_report.name = 'document'
facial_similarity_report = onfido.Report()
facial_similarity_report.name = 'facial_similarity'
facial_similarity_report.variant = 'standard'
check_data.reports = [document_report, facial_similarity_report]
check = api.create_check(applicant_id, data=check_data)
$check_data = new Onfido\Models\CheckCreationRequest();
$check_data->setType('express');
$document_report = new Onfido\Models\Report();
$document_report->setName('document');
$facial_similarity_report = new Onfido\Models\Report();
$facial_similarity_report->setName('facial_similarity');
$facial_similarity_report->setVariant('standard');
$check_data->setReports(array($document_report, $facial_similarity_report));
$check = $api->createCheck($applicant_id, $check_data);
CREATE A CHECK RESPONSE
{
"id": "<CHECK_ID>",
"created_at": "2018-10-04T10:16:07Z",
"status": "complete",
"redirect_uri": null,
"type": "express",
"result": "clear",
"sandbox": true,
"report_type_groups": [
"55904"
],
"tags": [],
"results_uri": "https://onfido.com/dashboard/information_requests/<REQUEST_ID>",
"download_uri": "https://onfido.com/dashboard/pdf/information_requests/<REQUEST_ID>",
"form_uri": null,
"href": "/v2/applicants/<APPLICANT_ID>/checks/<CHECK_ID>",
"reports": [
{
"created_at": "2018-10-04T10:16:07Z",
"href": "/v2/checks/<CHECK_ID>/reports/<REPORT_ID>",
"id": "<REPORT_ID>",
"name": "document",
"properties": {
"nationality": "",
"last_name": "Doe",
"issuing_country": "GBR",
"gender": "Female",
"first_name": "Jane",
"document_type": "passport",
"document_numbers": [
{
"value": "9999999999",
"type": "passport"
}
],
"date_of_expiry": "1900-01-01",
"date_of_birth": "1900-01-01"
},
"result": "clear",
"status": "complete",
"sub_result": "clear",
"variant": "standard",
....
},
{
"created_at": "2018-10-04T10:16:07Z",
"href": "/v2/checks/<CHECK_ID>/reports/<REPORT_ID>",
"id": "<REPORT_ID>",
"name": "facial_similarity",
"properties": {
"score": "0.65"
},
"result": "clear",
"status": "complete",
"sub_result": null,
"variant": "standard",
"breakdown": {
"face_comparison": {
"result": "clear"
},
"image_integrity": {
"result": "clear"
},
"visual_authenticity": {
"result": "clear"
}
}
}
],
}
Now that the uploads are completed, you can create a check.
You will be performing an Express Check composed of a Document Report and a Facial Similarity Report.
NOTE: A Facial Similarity Report has two variants - a standard (photo) variant and a video (live video) variant. This check uses the ‘standard’ variant.
Copy the curl command on the right to perform a check.
Run the command to perform the check.
You should see the created ‘check object’ in the response.
The example response shows that the check is ‘clear’. The applicant’s identity document and photo are genuine. Also, it is the same person in the photo and identity document.
NOTE: Sandbox Check results are simulated (but contain the same result response structures as live requests).
Congratulations! you have run your first Onfido check.
Next steps
This API Reference is designed to support your use of the Onfido API.
Choose a check type A typical workflow begins with deciding whether to perform an Express or a Standard check.
Choose report(s) A check is composed of one or more reports. Some reports require specific applicant details and/or uploads.
Set up a webhook Reports can arrive at different times so before creating a check we recommend the use of webhooks.
Going live
When you have finished testing your integration, you are ready to go live in 3 easy steps!
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 a live token Contact Onfido’s Client Support to request a live token, and update your production system to use the live token.
Update webhook endpoints Update webhook endpoints to handle live check/report status update events.
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:
- Adding new API endpoints
- Adding new properties to the responses from existing API endpoints
- Adding optional request parameters to existing API endpoints
- Altering the format or length of IDs
- Altering the message attributes returned by validation failures or other errors
- Sending webhooks for new event types
- Reordering properties returned from existing API endpoints
Changelog
| Added age_validation as a new breakdown on the document report | |
| Added documents as a new report argument | |
| Added new OCR Autofill endpoint | |
| Updated documentation on basic Criminal history report Added support for additional Criminal history report details for basic Criminal history reports in create check Removed support for basic Criminal history report as an express check |
|
| Added new events to the webhooks section | |
| Updated documentation on Facial similarity checks Added support for Facial similarity reports under sandbox responses |
|
| Added a new token authentication scheme for the web SDK | |
| Added report options for Watchlist full report | |
| Added support for additional reports under sandbox responses | |
| Added new client libraries | |
| Added social_insurance as a id number type | |
| Added support for basic Criminal history report as an express check | |
| Added support of testing multiple-report scenarios inside sandbox | |
| Added support of additional Criminal history report details in create check | |
| Added documentation around tag support for checks Added more detailed description of applicant address requirements |
|
| Added endpoint to download document for a particular applicant | |
| Added charge_applicant_for_check support for standard check Added Drug Test support Updated Right to Work report document requirements Added SSN format specification |
|
| Added two new sections: | |
| Added the referrer argument to the JSON web token endpoint | |
| Added endpoint: Added new check: |
|
| Added two new endpoints: | |
| 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 |
|
| Added Resume Report endpoint and Conditional Checks documentation | |
| Added Report Type Groups (Packages) support | |
Released API version v2:
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")
# 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/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):
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:
- Checks are not actually run against real-life databases - as some checks leave fingerprint, it is not advisable to make live checks during testing.
- Check results are pre-determined (but contain the same result response structures as live requests)
- Checks do not incur any charges
- Sandbox applicants are isolated from the non-sandbox environment. However, note that applicant notification emails still get sent out to sandbox applicants.
The main reasons for using the sandbox environment are therefore to:
- Verify your system have network connectivity with the Onfido API
- Verify you are posting all the required data in the right format to the Onfido API
- Verify you are handling the Onfido API responses correctly
- Verify your webhook is working
As check results are pre-determined, the sandbox environment is NOT for:
- Testing check quality
- Testing check response time
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.
| Report | Variant | Applicant last name* | Report result |
|---|---|---|---|
| Identity | standard | unidentified | unidentified |
| Identity | kyc | consider | consider |
| Document | n/a | consider | consider |
| Watchlist | full | consider | consider |
| Credit** | n/a | consider | consider |
| Facial Similarity | n/a | consider | consider |
| Right to Work | n/a | consider | consider |
*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
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.
Required applicant data
The table below states which applicant parameters are required or recommended for each report type.
| Report | Variant | Required Parameters | Notes |
|---|---|---|---|
| Document | - | first_name last_name |
If you don’t have an applicant’s name, it is possible to enter dummy values and create an applicant |
| Facial similarity | standard (photo) | first_name last_name applicant_id |
The applicant_id is returned after the applicant is created. This is required to create the report. |
| Identity | KYC standard |
first_name last_name dob country address[]street address[]state (US only) address[]postcode address[]country |
postcode should be used to represent a zip. Ensure that the country is supported for the applicant’s address. country is the country of jurisdiction where the check will be performed. country must be entered as a three-letter ISO code e.g. GBR NOTE: The country of jurisdiction must be the same as the address[]country. |
| Watchlist | KYC | first_name last_name dob (recommended) country address[]street (recommended) address[]postcode (recommended) address[]country (recommended) |
postcode should be used to represent a zip.NOTE: The country of jurisdiction must be the same as the address[]country. |
| - | full | first_name last_name dob (recommended) |
- |
| Street Level | - | first_name last_name address[]street address[]postcode address[]country |
postcode should be used to represent a zip. |
| (UK) Credit | - | first_name last_name dob address[]street address[]postcode address[]country addresses |
addresses refers to previous addresses of the applicant |
| (UK) Right to Work | - | first_name last_name gender dob nationality |
nationality must be entered as a three-letter ISO code e.g. GBR |
| (India) Aadhaar card | - | first_name middle_name (if applicable) last_name date_of_birth identity_card |
For identity_card enter the number value |
| (India) PAN card | - | first_name middle_name (if applicable) last_name tax_id |
For tax_id enter the Permanent Account Number (PAN) |
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"
}
]
}
| 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 |
| 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. If not provided the default is GBR. |
| 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 supports both the full SSN or the last four digits. If providing the full SSN the 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, 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, as this will affect check performance (e.g. lower match rates for identity reports).
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\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": "/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. |
| 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 country where this applicant will be checked. 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 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')
$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/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.
- Partial updates
- Addresses and ID numbers present will replace existing ones
- Same applicant validations to create applicant
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. |
| 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()
$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/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. A full list of supported identity documents is available here.
| 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)
$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": "/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
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 the standard variant of the facial similarity check 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 |
| 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, and png. 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. This will return the corresponding live photo object.
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'
EXAMPLE RESPONSE
{
"live_photos": [
{
"id": "d5106665-b653-4bab-ab6f-6b537f24204e",
"created_at": "2018-05-16T14:11:40Z",
"file_name": "file_name.png",
"file_type": "image/png",
"file_size": 943492,
"href": "/v2/live_photos/d5106665-b653-4bab-ab6f-6b537f24204e",
"download_href": "/v2/live_photos/d5106665-b653-4bab-ab6f-6b537f24204e/download"
}
]
}
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
Live Videos
Live videos are footage of the applicant’s face, recorded and uploaded by the Onfido iOS or Android SDKs, at the same time as the document image is captured. These videos are used to perform the video variant of facial similarity check on the applicant.
Live video object
{
"id": "fba32342-da0d-440c-8edd-359bc4de2b9f",
"created_at": "2018-05-14T16:44:53Z",
"href": "/v2/live_photos/fba32342-da0d-440c-8edd-359bc4de2b9f",
"download_href": "/v2/live_photos/fba32342-da0d-440c-8edd-359bc4de2b9f/download",
"file_name": "video_name.mp4",
"file_type": "video/mp4",
"file_size": 1431121,
"challenge": [
{
"type": "recite",
"query": [
1,
2,
3
]
},
{
"type": "movement",
"query": "turnRight"
}
]
}
During the video recording end users are asked to perform randomily generated actions, represented in challenge. Challenges always have two parts recite and movement, but the order in which these happen can vary. The order of the challeneges is maintained in the live video object. recite asks the user to say three randomly generated digits, whearas movement asks the user to look over their right or left shoulder.
| Attribute | Description |
|---|---|
| id | string The unique identifier of the live video |
| created_at | datetime The date and time at which the live video was uploaded |
| href | string The URI of this resource |
| download_href | string The URI that can be used to download the live video |
| 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 |
| challenge | hash Challenge the end user was asked to perform during the video recording |
Retrieve live video
$ curl https://api.onfido.com/v2/live_videos/fba32342-da0d-440c-8edd-359bc4de2b9f \
-H 'Authorization: Token token=your_api_token'
You can retrieve a single live video by calling this endpoint with the live video’s unique identifier. This will return the corresponding live video object.
ENDPOINT
GET https://api.onfido.com/v2/live_videos/{live_video_id}
List live videos
$ curl https://api.onfido.com/v2/live_videos?applicant_id=293CD57E-47A4-40A9-A7F9-C8AD47FE0CE8 \
-H 'Authorization: Token token=your_api_token'
EXAMPLE RESPONSE
{
"live_videos": [
{
"id": "6ec66f88-24a8-4813-8e53-325d75a34404",
"challenge": [
{
"type": "recite",
"query": [
1,
2,
3
]
},
{
"type": "movement",
"query": "turnRight"
}
],
"created_at": "2018-05-16T14:09:04Z",
"file_name": "video_name.mp4",
"file_type": "video/mp4",
"file_size": 1431121,
"href": "/v2/live_videos/6ec66f88-24a8-4813-8e53-325d75a34404",
"download_href": "/v2/live_videos/6ec66f88-24a8-4813-8e53-325d75a34404/download"
}
]
}
This endpoint lists all the live videos that belong to an applicant. You must pass the applicant ID as a query string parameter.
GET https://api.onfido.com/v2/live_videos
Arguments
| applicant_id | required The ID of the applicant whose live videos you want to list |
Download live video
$ curl https://api.onfido.com/v2/live_videos/7410A943-8F00-43D8-98DE-36A774196D86/download \
-H 'Authorization: Token token=your_api_token'
Live videos 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 video.
Endpoint
GET https://api.onfido.com/v2/live_videos/{live_video_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/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. |
| 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" }]
})
$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": "/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 | requiredstandard 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 basic, 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 Note: setting this to true is not compatible with the use of conditional checks. |
| 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 |
| documents | optional Array of Report Documents hashes. This argument allows you to specify which document to use as part of the document report. If unspecified, the most recently uploaded document (or documents for a two-sided ID document) will be used. |
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) |
REPORT DOCUMENTS
| id | required ID of uploaded document to use. |
CRIMINAL HISTORY REPORT DETAILS ARGUMENTS
| job_role | optional The applicant’s job role for which you would like to request a UK criminal history report.* |
| purpose | optional The purpose for which you would like to request a basic UK criminal history report. If provided, this value must be either employment or other.* |
| other_purpose | optional If you are requesting a basic UK criminal history report and provided other as its purpose, you need to provide a short textual description of the purpose here.* |
| place_of_work | optional The place of work where the applicant will be carrying out their role. For basic UK criminal history reports, this is only needed if the purpose is employment, and the value provided here (if any) must be either England, Wales, or Scotland.* |
| employment_sector | optional The place of work where the applicant will be carrying out their role. For basic UK criminal history reports, this is only needed if the purpose is employment, and the value provided here (if any) must be one of those listed here.* |
*This information is required to be able to conduct basic UK criminal history reports. Our team at client-support@onfido.com can advise you with respect to how your account can be set up so that you don’t have to send this with every API call.
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)
$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/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)
$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/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)
$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/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)
$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/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
Document Report
| Report | Name | Variants | Standard check | Express check |
|---|---|---|---|---|
| Document Report | document |
- | yes | yes |
Example UK Response
{
"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"
},
"age_validation": {
"result": "clear",
"breakdown": {
"minimum_accepted_age": {
"result": "clear",
"properties": {}
}
}
}
}
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 |
| age_validation | hash Asserts that the age based on the date of birth on the document is under the minimum age set on the client account (default: 16). To have this age altered reach out to your contact at Onfido. |
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).
Facial Similarity Report
| Report | Name | Variants | Standard check | Express check |
|---|---|---|---|---|
| Facial Similarity Report | facial_similarity |
standard video |
yes* no |
yes yes |
* The standard variant of the Facial Similarity Report needs to be paired with a Document Report in order to work as a standard check.
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.789
}
}
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.
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 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 facial 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).
Identity Report
| Report | Name | Variants | Standard check | Express check |
|---|---|---|---|---|
| Identity Report | identity |
standardkyc |
yes yes |
yes yes |
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",
"variant": "kyc",
"breakdown": {
"mortality": {
"result": "clear"
},
"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 US Response where SSN was provided
{
"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"
}
}
}
},
"ssn": {
"result": "clear",
"breakdown": {
"last_4_digits_match": {
"result": "clear",
"properties": {}
},
"full_match": {
"result": "clear",
"properties": {}
}
}
},
"properties": {}
}
}
Example Response for jurisdictions other than UK and US
{
"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.
For applicants in the United States, the identity report can optionally match the Social Security Number, either the full 9 digits or the last 4.
The result breakdowns indicate which of these elements was positively matched, and the underlying source or sources of that database match.
The identity report will be run in the jurisdiction specified as country in the applicant object, not the applicant’s address country field. The country field in the applicant object will default to GBR if not provided.
Do make sure that the applicant object’s country field matches the applicant’s address country field when creating an applicant, and that the country is supported for Identity Reports.
Report results vary depending on the jurisdiction they were run in. The examples to the right detail:
- results for an identity report conducted in the United Kingdom, where sources (
credit_agencies,voting_register,telephone_database) are displayed as breakdowns with their ownresultvalue. - results for an identity report conducted in the United States, which includes Social Security Number as an additional breakdown, and lists sources as comma separated under
properties. - results for an identity report conducted on a jurisdiction other than United Kingdom or United States, where sources are shown as comma separated under
properties.
When a match for date of birth or address cannot be found (i.e. result is not clear) the corresponding properties bucket will be empty as such "properties":{}.
Sources names and definitions
| Source name | 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. To specify which one you want, pass variant with the create check request. If not provided the default is standard.
Standard
This check should be used for employment or recruitment purposes.
Overall result logic:
"result": "clear"at least one source matches the applicant’s name and address"result": "consider"the name and date of birth is matched, but no name and address matches are found"result": "unidentified"no matches are found
When the SSN or the last four digits of the SSN are provided:
"result": "clear"at least one source matches the applicant’s name and address, and the last four digits of the SSN are matched"result": "unidentified"no matches are found"result": "consider"otherwise
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.
Overall result logic:
If the applicant address is in the UK:
"result": "clear"the applicant is not found in mortality lists AND- at least one match on the applicant’s name and current address, and a match on the applicant’s name and date of birth (either in the same or different source) OR
- two matches on the applicant’s name and current address from two different sources
"result": "consider"otherwise
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:
"result": "clear"at least one source matches the applicant’s name and current address"result": "consider"the name and date of birth is matched, but no name and address matches are found"result": "unidentified"no matches are found
When the SSN or the last four digits of the SSN are provided:
"result": "clear"at least one source matches the applicant’s name and address, and the last four digits of the SSN are matched"result": "unidentified"no matches are found"result": "consider"otherwise
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.
Watchlist KYC Report
| Report | Name | Variants | Standard check | Express check |
|---|---|---|---|---|
| Watchlist Report | watchlist |
kyc |
yes | yes |
Example KYC Response
{
"created_at": "2018-08-20T16:42:52Z",
"href": "/v2/checks/000cdb43-aef9-46bd-b000-10bf888a28b8/reports/aa0b2fea-930d-41ac-9b49-e55fd7e2xxx6",
"id": "aa0r2fea-730d-41rc-9b49-e55fd7e2xxx6",
"name": "watchlist",
"result": "consider",
"status": "complete",
"variant": "kyc",
"breakdown": {
"adverse_media": {
"result": "consider"
},
"politically_exposed_person": {
"result": "consider"
},
"sanction": {
"result": "consider"
}
},
"properties": {
"records": {
"full_name": "Doe, John David",
"date_of_birth": [
"1974",
"1973"
],
"address": [
{
"locator_type": "BIRTH",
"address_line1": "District Number 1, Kanar City, Kandahar Province",
"country": "AFG"
},
{
"address_line1": "Post Office Box 2679",
"town": "Fort Myers",
"state_province": "Florida",
"postal_code": "33902",
"country": "USA"
}
],
"alias": [
{
"alias_type": "Localised name",
"alias_name": "Jon Doe"
},
{
"alias_type": "AKA",
"alias_name": "Jonny Davey Doe"
}
],
"attribute": [
{
"attribute_type": "Image URL",
"attribute_value": "https://www.interpol.int//extension/produce_sqli/design/produce_sqli/images/NotAvailable_w111.png;b54106294f"
},
{
"attribute_type": "Nationality",
"attribute_value": "AFGHANISTAN"
},
{
"attribute_type": "Remark",
"attribute_value": "Other Info: UN Ref TI.H.143.01. Believed to be in Afghanistan/Pakistan border area."
},
{
"attribute_type": "Sex",
"attribute_value": "Male"
},
{
"attribute_type": "Entity URL",
"attribute_value": "http://www.unx.org/sc/committees/1999/lists.shtml"
}
],
"associate": [
{
"relationship_direction": "To",
"relationship_type": "Employee",
"entity_name": "Taliban"
},
{
"relationship_direction": "To",
"relationship_type": "Sister in law",
"entity_name": "Sarah Jayne Doe"
}
],
"position": [
"Consulate General - Islamic Movement of Taliban in Quetta City, Pakistan",
],
"event": [
{
"category": "Watch List",
"sub_category": "Sanction",
"event_description": "On List [Canada OSFI Individuals List]",
"event_date": "2011-01-20",
"source": {
"source_name": "Canada OSFI Individuals List",
"source_URL": "http://www.osfi-bsif.gc.ca/eng/fi-if/axmlc-clxxx/atf-fat/Pages.aspx",
"source_date": "2018-03-09"
}
},
],
"source": [
{
"source_name": "BVI Financial Services Commission - Advisory Warnings",
"source_url": "http://www.bvxfsc.vg/x-gb/alerts/advisorywarnings.xspx",
"headline": "BVI Financial Services Commission - Advisory Warnings"
},
{
"source_name": "UK HM Treasury Financial Sanctions Target List",
"source_url": "http://www.hm-treasury.gov.uk/xxx_sanction_ind.htm",
"headline": "UK HM Treasury Financial Sanctions Target List"
}
]
}
}
}
Detail and Notes
A watchlist kyc check provides a granular breakdown of any records found when searching global watchlists. These include: Government Sanctions Lists, Politically Exposed Persons (PEP) Lists, and more generally Adverse Media, including Terrorism, Money Laundering, Regulatory Action, and Most Wanted lists.
If no match is found against the subject, the records field will read [] and the overall result will be clear.
If one or more matches are found, each match will be returned under records and includes, but is not limited to: name and date of birth of match, aliases and associates, and relevant events and sources. Each event will correspond to a relevant category of list, which drives one of the breakdowns (see below), and the overall result will be consider.
When available, URLs to data sources are provided, as well as pictures of the individual found in the match. This, along with other detail in the response, allows you to quickly assess the relevancy of the match and eliminate false positives.
Date of Birth
Submitting a date_of_birth with the name is optional but recommended, to narrow the search of the relevant individual.
More than one date of birth might be found per match due to the nature of the data sources, such as newspaper articles, which might include someone’s age but not their full date of birth.
Address
Submitting an address with the name is also optional but recommended. This will narrow the search to the country specified in the address, for all lists except for Sanctions and Terrorist lists.
If a match is found but the date_of_birth or address fields are null, this means there is no date_of_birth or address data on file associated with that match.
Response Breakdowns
adverse_media |
|
politically_exposed_person |
|
sanction |
Watchlist Full Report
| Report | Name | Variants | Standard check | Express check |
|---|---|---|---|---|
| Watchlist Report | watchlist |
full |
yes | yes |
Example Full Response
{
"created_at": "2017-12-14T17:26:08Z",
"href": "/v2/checks/000cdb42-aef9-46bd-b000-10bf888a28b8/reports/aa0b2fea-730d-41ac-9b49-e55fd7e2cca6",
"id": "aa0b2fea-730d-41ac-9b49-e55fd7e2cca6",
"name": "watchlist",
"properties": {
"records": [
{
"associates": "Justin Doe, Jane Doe, Maria Doe",
"keywords": "",
"last_updated_utc": "2017-12-13T06:29:27Z",
"entity_type": "person",
"sources": "PEPs list, PEPs list-adverse-media, pep-uk-parliament, pep-uk-parliament-mps",
"types": "adverse-media, pep, pep-class-1",
"name": "John David Doe",
"external_id": "A0A2LJ9AAA66J9T",
"match_types": "name_exact",
"related_urls": "http://news.bbc.co.uk/2/hi/uk_news/politics/123.stm, http://www.parliament.uk/biographies/commons/",
"picture_urls": "http://bbc.com/1234.png, http://bbc.com/abc.jpeg",
"all_dobs": "1912-01-14, 1913, 1914",
"entity_fields_dob": "1912-01-14",
"entity_fields_countries": "Austria, Bangladesh, Egypt",
"report_id": 9999999
}
]
},
"result": "consider",
"status": "complete",
"sub_result": null,
"variant": "full",
"breakdown": {
"legal_and_regulatory_warnings": {
"result": "consider"
},
"politically_exposed_person": {
"result": "consider"
},
"sanction": {
"result": "consider"
}
}
}
A watchlist full check provides a granular breakdown of any records found when searching global watchlists. The watchlists include: Government Sanctions Lists, Politically Exposed Persons Lists, and more generally Warnings Lists, such as Anti-Terrorism Watchlists, Anti-Money Laundering (AML) Watchlists and Most Wanted Watchlists.
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 will search only Politically Exposed Persons Lists. Specifying sanctions will search Sanctions Lists and Warnings lists. If no options are specified, all types will be searched: PEPs, Sanctions and Warnings.
Each match will be returned under records and 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. When available, URLs to data sources are provided, as well as pictures of the individual found in the match. This allows you to quickly assess the relevancy of the match and eliminate false positives.
More than one date of birth might be found per match, due to the nature of the data sources, such as news papers articles, which might include someone’s age but not their full date of birth.
Breakdown
| legal_and_regulatory_warnings | hash |
| politically_exposed_person | hash |
| sanction | hash |
Street Level Report
| Report | Name | Variants | Standard check | Express check |
|---|---|---|---|---|
| Street Level Report | street_level |
- | yes | yes |
Example Response
{
"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, which yeilds a "result": "clear". If after 15 days no response is received, the report will return a "result": "consider".
Delivery times
The time at which the 15 day counter starts depends on the check type. For express checks, it starts from the report creation date. For standard checks, time starts counting from the moment the applicant has submitted their details in the applicant form.
Letters to UK addresses are sent out by Royal Mail second class postal service. Letters to countries other than the UK are sent out by Royal Mail first class postal service.
All mail is collected Monday-Friday at 3:00pm UK time, excluding UK bank holidays. This means that letters for any reports created after 3pm on a Friday will only be collected on the following Monday at 3pm.
Delivery times from time of mail collection:
- UK: 2 to 3 working days, including Saturdays.
- Europe: 3 to 5 working days.
- Rest of the World: 5 to 7 working days.
Remote areas may take longer.
Royal Mail claim to have a 99% deliverability rate in the UK and 93% for Rest of the World. Providing good quality address data, with all fields correctly filled in the applicant object, greatly increases the deliverability of the letter. Do note that deliverability of the letter is not enough to clear the report. The applicant must enter the code online within the 15 days in order for the report to return as clear.
Customisation
The default letter is Onfido branded and directs the applicant to enter their code at https://onfido.com/slv.
Alternatively the letter can be customised with your branding of choice. If you wish to discuss this please contact your account manager or email client-support@onfido.com.
You can also build your own front end for the applicant to input their code using the submit code endpoint.
Breakdown
| address | hash Contains the result and details of an address match |
UK
The following section outlines report types that are specific to the United Kingdom.
| Report | Name | Variants | Standard check | Express check |
|---|---|---|---|---|
| Credit Report | credit |
yes | yes | |
| Criminal History Report | criminal_history |
basic standard enhanced |
yes | no |
| 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:
| Variant | Options |
|---|---|
standard | volunteer working_at_home_address |
enhanced | children_barred_list adults_barred_list volunteer working_at_home_address |
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 differ according to whether the check is conducted in England or Wales (DBS) or Scotland (Disclosure Scotland).
For basic criminal history report conducted in Scotland, the documents required are
- a proof of id (i.e. valid Passport, valid National ID Card, valid Driving Licence, UK Biometric Residence Permits, UK birth/adoption certificate) AND
- a proof of address* (i.e. P45, P60, Job Seekers Letter, Bank Statement, Utility Bill, valid Driving Licence, National Insurance Card Letter, HMRC Letter)
*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.
For basic criminal history report conducted in England or Wales, the documents required follow the routes specified in DBS’s Basic check identity guidance.
For standard and enhanced criminal history reports, the documents required follow the routes specified in DBS’s ID checking guidelines.
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
- a national identity document (i.e., Passport, UK Biometric Residence Permits, EU/EEA/Swiss National ID card) OR
- a UK birth certificate, along with an NI document (i.e., NI card itself, government letter displaying the name and the NI number, P45/P60 document)
for citizens of other nationalities
- a passport, along with a valid UK work visa/work permit page of same passport
When requesting a right to work report as an express check, make sure these are uploaded before the check is created.
India
The following section outlines report types that are specific to India.
| Report | Name | Standard check | Express 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 |
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 4 times within the following 12 hours.
Quick tip: for initial testing, you can create a temporary endpoint URL using free hosted services to quickly inspect webhook requests.
IP addresses
All webhook requests will be coming from the following IPs:
Europe:
52.51.171.2552.51.228.22852.51.234.203
United States:
34.232.2.22252.55.124.5834.224.182.19
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.initiated | A report has transitioned from “Awaiting Approval” to “Awaiting Data” status. Only occurs for Criminal History, Driving Record, and Credit reports |
| 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/
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
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')
$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 (UK only).
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/* |
OCR Autofill (Beta)
$ curl https://api.onfido.com/v2/ocr
-H 'Authorization: Token token=your_api_token' \
-F 'document_id=8546921-123123-123123'
EXAMPLE RESPONSE
{
"document_id": "7568415-123123-123123",
"doc_info": {
"country": "FRA",
"type": "national_identity_card"
},
"extracted_data": {
"ocr_results": {
"date_of_birth": "1973-03-21",
"document_number": "123456K12345",
"first_name": "HUGO",
"gender": "Male",
"last_name": "MARTIN"
}
}
}
OCR Autofill takes an uploaded document and returns information extracted from the document. This is a synchronous request, which means the extracted information will be presented immediately in the API response.
Endpoint
POST https://api.onfido.com/v2/ocr
Arguments
| document_id | required The unique identifier of the uploaded document to run extraction on |
Extraction result
If data has been successfully extracted, the API response will contain the properties doc_info and extracted_data.
doc_info has the following properties:
| country | Document country in three-letter ISO code |
| type | Type of document. See Document types. Note that only certain document types are supported by OCR Autofill. Please contact client-support@onfido.com to find out more. |
extracted_data has a child property ocr_results which itself contains the following properties:
| document_number | The official document number |
| first_name | First name |
| last_name | Last name |
| gender | Gender. Valid values are Male and Female. |
| date_of_birth | Date of birth in yyyy-mm-dd format |
| date_of_expiry | Date of expiry in yyyy-mm-dd format |
| nationality | Nationality in three-letter ISO code |
| mrz_line_1 | Line 1 of the MRZ code |
| mrz_line1 | Line 1 of the MRZ code |
| mrz_line_2 | Line 2 of the MRZ code |
| mrz_line2 | Line 2 of the MRZ code |
| mrz_line_3 | Line 3 of the MRZ code |
| mrz_line3 | Line 3 of the MRZ code |
Unsuccessful extraction
{
"document_id": "7568415-123123-123123",
"error": {
"type": "classification_failure",
"message": "We couldn’t recognise the type of this document."
}
}
{
"document_id": "7568415-123123-123123",
"error": {
"type": "extraction_failure",
"message": "We couldn’t extract data from this document."
}
}
If the document cannot be recognised, a classification_failure will be returned. On the other hand, if no data can be extracted, an extraction_failure will be returned.
Street Level Code
The Street Level Report sends applicants a letter with a unique verification code. This code then needs to be submited for the address to be validated.
Submit code
$ curl https://api.onfido.com/v2/slv \
-H 'Authorization: Token token=your_api_token' \
-d 'code=c2d3taql' \
EXAMPLE RESPONSE
200 OK
{
"success": true
}
You can submit street level report code to this endpoint.
ENDPOINT
POST https://api.onfido.com/v2/slv
Arguments
| code | required The unique code present in the street level report letter |
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:
- Identity and Street Level Reports: Only perform SLV if Identity Report fails to confirm the applicant address as shown in the figure below;
- 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.
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.
Charging applicants
When Conditional Checks are used, the option of having the applicant paying for their checks is not supported.
Usage Notes
There are generally 2 ways to create a check via the API:
- By passing in all the reports of the check;
- 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.