NAV
v2
v2
v1

The Onfido API

Welcome to the Onfido API reference documentation.

The API is based on REST principles and uses standard HTTP response codes.

Use the left-hand navigation bar to go to different sections of the documentation.

Request, response format

The API uses token-based authentication.

PUT and POST requests should have a Content-Type: application/json header, except when uploading documents or live photos. Such requests should have a Content-Type: multipart/form-data header.

Responses return JSON with a consistent structure, except when downloading documents, photos or videos.

Security

You must make all your requests to the API over HTTPS and TLS 1.2, with Server Name Indication enabled. Any requests made over HTTP will fail.

Text fields support UTF-8, but do not allow certain special characters that could be used maliciously.

Getting started

Follow this section to get started quickly with the Onfido API.

You should follow these steps in order. You’ll find example requests and responses for different languages on the right of the page. These assume you’re inside your working directory.

You’ll run a check in the sandbox environment with a sample identity document and photo. In a real check, ideally you should acquire a ‘live’ photo at the same time as the check is performed.

Choose your region

This guide uses the API base URL https://api.onfido.com/.

If you want to store your check data in a particular region, you must use a region-specific base URL.

Find your sandbox token for authorization

In your Onfido Dashboard, go to the ‘Developers’ tab, then ‘Tokens’. You’ll see your existing sandbox tokens, or be able to generate a new one.

The token name must start with test_ and be of type ‘Sandbox’, not ‘Live’.

Create an applicant

Create applicant “Jane Doe”

POST /v2/applicants HTTP/1.1
Host: api.onfido.com
Authorization: Token token=<YOUR_API_TOKEN>
Content-Type: application/json

{
    "first_name": "Jane",
    "last_name": "Doe",
    "dob": "1990-01-01"
}
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 sys
import onfido
import datetime
from pprint import pprint
from onfido.rest import ApiException

configuration = onfido.Configuration()
configuration.api_key['Authorization'] = 'token=' + '<YOUR_API_TOKEN>'
configuration.api_key_prefix['Authorization'] = 'Token'

api = onfido.DefaultApi(onfido.ApiClient(configuration))

applicant = onfido.Applicant(first_name='Jane', last_name='Doe')
applicant.dob = datetime.date(1990, 1, 1)
require_once(__DIR__ . '/vendor/autoload.php');

$config = Onfido\Configuration::getDefaultConfiguration();
$config->setApiKey('Authorization', 'token=' . '<YOUR_API_TOKEN>');
$config->setApiKeyPrefix('Authorization', 'Token');

$applicant = new Onfido\Model\Applicant();
$applicant->setFirstName('Jane');
$applicant->setLastName('Doe');
$applicant->setDob('1990-01-01');

The first part of any check is to create an applicant:

  1. In your working directory, run one of the example commands (in the right-hand column), replacing <YOUR_API_TOKEN> with your sandbox token. You should see the created applicant object in the response.

  2. Note the <APPLICANT_ID>. You’ll use it in the next steps.

Download example files for the check

Next, you’ll download a sample identity document and sample photo of “Jane Doe” to submit for the example check.

Save the following files in your working directory:

Upload the example ID document

Upload “sample_driving_licence.png”

POST /v2/applicants/<APPLICANT_ID>/documents HTTP/1.1
Host: api.onfido.com
Authorization: Token token=<YOUR_API_TOKEN>
Content-Type: multipart/form-data 

<YOUR FILE DATA (path/to/sample_driving_licence.png)> 
applicant_id = applicant['id']
file = open('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='sample_driving_licence.png')
$applicant_id = $applicant['id'];
$type = "driving_licence";
$file = "sample_driving_licence.png";
$side = "front";
$document = $api->uploadDocument($applicant_id, $type, $file, $side);

In your working directory, run one of the example commands (in the right-hand column). Replace <YOUR_API_TOKEN> with your sandbox token and <APPLICANT_ID> with the value you obtained when you created an applicant. You should see the created document object in the response.

Upload a photo

Upload “sample_photo.png”

POST /v2/live_photos HTTP/1.1
Host: api.onfido.com
Authorization: Token token=<YOUR_API_TOKEN>
Content-Type: multipart/form-data

<YOUR FILE DATA (path/to/sample_photo.png)>
file = open('sample_photo.png')
live_photo = api.live_photo.create(applicant_id, file: file)
check_data = onfido.Check()
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, check_data)
$file = "sample_photo.png";
$live_photo = $api->uploadLivePhoto($applicant_id, $file);

In your working directory, run one of the example commands (in the right-hand column). Replace <YOUR_API_TOKEN> with your sandbox token and <APPLICANT_ID> with the value you obtained when you created an applicant. You should see the created photo object in the response.

Create a check

Create a check for “Jane Doe” (Document report, Facial Similarity report)

POST /v2/applicants/<APPLICANT_ID>/checks HTTP/1.1
Host: api.onfido.com
Authorization: Token token=<YOUR_API_TOKEN>
Content-Type: application/json

{
    "type": "express",
    "reports": [
    {"name": "document"},
    {"name": "facial_similarity", "variant": "standard"}
  ]
}
reports = [{name: 'document'}, {name: 'facial_similarity', variant: 'standard'}]
check = api.check.create(applicant_id, type: 'express', reports: reports)
check_data = onfido.Check()
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, check_data)
$check_data = new Onfido\Model\Check();
$check_data->setType('express');

$document_report = new Onfido\Model\Report();
$document_report->setName('document');

$facial_similarity_report = new Onfido\Model\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);

With the uploads complete, you can now create a check for Jane Doe.

You will run an express check composed of a Document report and a Facial Similarity report.

In your working directory, run one of the example commands (in the right-hand column), replacing <YOUR_API_TOKEN> with your sandbox token. You should see the created ‘check object’ in the response.

The example response shows:

You’ve now completed your example check.

Go live

  1. Add billing information:

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

  2. Request a live API token:

    Contact Onfido’s Client Support at client-support@onfido.com to request a live token.

  3. Use the live API token:

    Update your production system to use the live token.

  4. Update webhook endpoints

    Update webhook endpoints to handle live check/report status update events.

Check types

The Onfido API offers two different check types: “express” and “standard”.

Depending on the type of check you wish to perform, different information will be required when you create an applicant.

A check is composed of one or more reports. Some reports require specific applicant details or uploads or both.

Express checks

If your system already has the information you require from applicants then you should use express checks. Express checks submit applicants' information via the client application.

The steps in an express check are as follows:

  1. An applicant object is created.

  2. If required: documents, photos and videos are uploaded to the applicant object (on GitHub: read about the Android, iOS and Web SDKs for capture and uploads).

  3. A check is constructed consisting of one or more reports.

After a check is created, an express check will start processing immediately.

Standard checks

If you require Onfido to collect information from an applicant, you may wish to use standard checks.

Standard checks require applicants to enter their information in a form, which is sent to applicants via email.

A standard check will only start processing when the applicant has submitted the form.

Client libraries

You can use supported client libraries to integrate with the Onfido API.

If you write your own library and would like us to link to it, please email api@onfido.com.

All client libraries are hosted on GitHub.

Java

Use the ‘api-java-client’ library.

JavaScript

Use the ‘api-javascript-client’ library.

Ruby

The team at Hassle have developed an open-source Ruby client library.

Python

Use the ‘api-python-client’ library.

PHP

Use the ‘api-php-client’ library.

Backwards compatibility

The following changes are considered backwards compatible:

Postman

You can run the Onfido API collection in Postman:

Run in Postman

In your Postman environment, you’ll need to define the apiToken variable. If you know you need to use a non-default region API base URL, you should also set the baseUrl variable in Postman.

You can read more in Postman’s documentation about managing environments.

Changelog

2019-03-14 Removed ‘Conditional checks’ section.
2019-03-11 Added testing data for Proof of Address.
2019-03-07 Added a ‘Run in Postman’ button linking to a Postman API collection.
2019-02-18 Removed documentation for UK credit and criminal history reports.
2019-02-06 Updated the Proof of Address documentation.
2019-12-18 Added a new rate limits feature.
2018-12-13 Removed documentation for India Aadhaar and PAN Card reports.
2018-12-03 Added applicant deletion feature
2018-11-26 Added Proof of Address report.
2018-10-15 Added age_validation as a new breakdown on the Document report
2019-09-18 Removed documentation for US-specific reports.
2018-08-15 Added documents as a new report argument
2018-05-24 Added new OCR Autofill endpoint
2017-12-18 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
2017-12-04 Added new events to the webhooks section
2017-08-25 Updated documentation on Facial Similarity checks
Added support for Facial Similarity reports under sandbox responses
2017-07-14 Added a new token authentication scheme for the web SDK
2017-03-03 Added report options for Watchlist full report
2017-02-21 Added support for additional reports under sandbox responses
2017-02-01 Added new client libraries
2017-01-18 Added social_insurance as a id number type
2016-12-08 Added support for basic criminal history report as an express check
2016-10-31 Added support of testing multiple-report scenarios inside sandbox
2016-10-24 Added support of additional criminal history report details in create check
2016-09-29 Added documentation around tag support for checks
Added more detailed description of applicant address requirements
2016-09-15 Added endpoint to download document for a particular applicant
2016-09-07 Added charge_applicant_for_check support for standard check
Added Drug Test support
Updated Right to Work report document requirements
Added SSN format specification
2016-09-01 Added two new sections:
2016-08-25 Added the referrer argument to the JSON web token endpoint
2016-08-25 Added endpoint:
Added new check:
2016-08-25 Added two new endpoints:
2016-08-15 Added Right to Work support
Added documentation on criminal history supported options
Added documentation on supported Applicant title values
Added documentation on UK Address street attribute character limit restriction
Added documentation on Create check suppress_form_email attribute
2016-08-08 Added Resume Report endpoint and Conditional Checks documentation
2016-07-14 Added Report Type Groups (packages) support
2016-04-25 Released API version v2:
  • Restructures document report results for greater clarity and detail
  • Changes the report type name for SSN trace from identity to to ssn_trace
Documentation for our previous version (v1) is available here

Authentication

Authorization: Token token=<YOUR_API_TOKEN>
require 'onfido'

Onfido.configure do |config|
  config.api_key = '<YOUR_API_TOKEN>'
end
configuration = onfido.Configuration()
configuration.api_key['Authorization'] = 'token=' + '<YOUR_API_TOKEN>'
configuration.api_key_prefix['Authorization'] = 'Token'
$config = Onfido\Configuration::getDefaultConfiguration();
$config->setApiKey('Authorization', 'token=' . '<YOUR_API_TOKEN>');
$config->setApiKeyPrefix('Authorization', 'Token');

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

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 won’t appear on your monthly bill.

Onfido’s Web SDK uses JSON Web Tokens, and the iOS and Android SDKs use Mobile SDK tokens.

API tokens

You can use API tokens to authenticate any API action described in this documentation.

If you do need to collect applicant data in the frontend of your application, we recommend that you use one of the Onfido SDKs.

You should only share live API tokens with the minimum number of people necessary, but you can use sandbox tokens to freely experiment with the Onfido API. You can read about the differences between the live and sandbox environments.

You should not embed API tokens in your backend code—even if it’s not public—because this increases the risk that they will be discovered. Instead, you should store them in configuration files or environment variables.

Mobile SDK tokens

Mobile SDK tokens are used in the Android and iOS SDKs. These tokens are restricted to only those actions needed by the SDK and are safe to use in mobile applications.

Web SDK tokens

The Web SDK uses JSON Web Tokens (JWTs). These are restricted to a particular applicant and expire after 90 minutes, so you can safely use them in the frontend of your application.

We recommend upgrading to the latest version of the SDK.

You’ll need to generate and include a new token each time you initialise the Web SDK.

You can read about generating Web SDK tokens.

Status codes

Code Name Meaning
200 OK Request succeeded
201 Created Request succeeded and resource created
400 Bad Request Malformed request
401 Unauthorized Invalid authorization credentials
403 Forbidden Action prohibited
404 Not Found Resource not found
422 Unprocessable Entity Validation error
429 Too Many Requests Rate limit reached
500 Internal Server Error An unexpected error occurred in our API

Errors

In this section you can read about explanations for errors, and suggestions about what to do.

400 bad_request:

Make sure your request is formatted correctly.

401 authorization_error

Make sure you’ve entered your API token correctly.

401 user_authorization_error:

Contact an administrator about user permissions.

401 bad_referrer:

Check the referrer used to generate the Web SDK token.

401 expired_token:

Request a new Web SDK token.

403 account_disabled:

Please contact client-support@onfido.com.

403 trial_limits_reached:

Please contact client-support@onfido.com.

404 resource_not_found:

Make sure you’ve formatted the URI correctly.

410 gone:

The resource has been deleted or is scheduled for deletion.

422 validation_error:

Check the fields property for a specific error message.

422 missing_billing_info:

Make sure you’ve provided your billing information before starting a check.

422 missing_documents:

Make sure you’ve uploaded the required documents before starting a check.

422 invalid_reports_names:

Make sure you’ve entered the report name(s) in the correct format (string).

422 missing_id_numbers:

Make sure you’ve supplied all required ID numbers.

422 invalid_check_type_for_variant:

Read about report types to see which variants are compatible with different check types.

422 standard_check_photo_facial_sim_without_document:

In standard checks, Facial Similarity reports must be paired with Document reports.

422 failed_check_requirements:

Check that all required information has been provided and correctly specified.

422 incomplete_checks:

There are other ongoing checks associated with this applicant.

429 rate_limit:

The rate limit has been reached. Please try again later.

500 internal_server_error:

The server encountered an error. If this persists, please contact client-support@onfido.com.

Error object

Validation error object

HTTP/1.1 422 Unprocessable Entity
Content-Type: application/json

{
  "error": {
    "type": "validation_error",
    "message": "",
    "fields": {
      "email": {
        "messages": [
          "invalid format"
        ]
      },
      "name": {
        "messages": [
          "can't be blank"
        ]
      }
    }
  }
}
Attribute Description
type string
The type of error returned
message string
A human-readable message giving more details about the error
fields hash
The invalid fields and their associated errors. Only applies to validation errors

Sandbox testing

Onfido offers a sandbox environment for simulating API requests. To use it, you’ll need a sandbox API token.

Sandbox tokens start with a test_ prefix, while live tokens start with a live_ prefix.

You can make all the same API requests in the sandbox environment as in the live one. You will also be notified of check and report status changes via your registered webhooks.

You can use the sandbox environment to check:

Key differences

The key differences between the sandbox and a live environment are:

Sandbox rate limits

For sandbox requests, there is currently a rate limit of 30 requests per minute.

When you hit the limit, you’ll receive a 429 Too Many Requests error. You can read more about the API’s error codes.

Pre-determined responses

Before you create the example check, create the applicant “Jane Unidentified”

POST /v2/applicants/ HTTP/1.1
Host: api.onfido.com
Authorization: Token token=<YOUR_API_TOKEN>
Content-Type: application/json

{
    "first_name": "Jane",
    "last_name": "Unidentified",
    "dob": "1990-01-01"
}

Create a check (Identity report) for “Jane Unidentified”

POST /v2/applicants/<APPLICANT_ID>/checks/ HTTP/1.1
Host: api.onfido.com
Authorization: Token token=<YOUR_API_TOKEN>
Content-Type: application/json

{
    "type": "express",
    "reports": [{
        "name": "identity"
        }]
}

Pre-determined response

HTTP/1.1 201 Created
Content-Type: application/json

{
  "id": "<CHECK_ID>",
  "created_at": "2014-05-23T13:50:33Z",
  "sandbox": true,
  "href": "/v2/applicants/<APPLICANT_ID>/checks/<CHECK_ID>",
  "type": "express",
  "status": "complete",
  "result": "consider",
  "results_uri":
  "https://onfido.com/dashboard/information_requests/<REQUEST_ID>",
  "redirect_uri": null,
  "reports": [
    {
      "id": "<REPORT_ID>",
      "name": "identity",
      "created_at": "2014-05-23T13:50:33Z",
      "status": "complete",
      "result": "unidentified",
      "href": "/v2/checks/<CHECK_ID>/reports/<REPORT_ID>"
      ...
    }
  ]
}

To help you test your integration, you can trigger pre-determined responses from the API using specific applicant last names:

ReportVariantApplicant last nameReport result
Identitystandardunidentifiedunidentified
Identitykycconsiderconsider
Documentn/aconsiderconsider
Watchlistfullconsiderconsider
Facial Similarityn/aconsiderconsider
Right to Workn/aconsiderconsider
Proof of Address*n/aconsiderconsider

All normal applicant attribute requirements apply when you create any sandbox check. For example to trigger an Identity report sandbox response, you need to specify:

Pre-determined responses for multiple-report checks


Create a check (Identity report to return ‘consider’, watchlist report) for “Jane Unidentified”

POST /v2/applicants/<APPLICANT_ID>/checks HTTP/1.1
Host: api.onfido.com
Authorization: Token token=<YOUR_API_TOKEN>
Content-Type: application/json

{
    "type": "express",
    "reports": [
        {"name": "identity"},
        {"name": "watchlist"}
    ],
    "consider": [
        "identity"
    ]
}

Pre-determined response

HTTP/1.1 201 Created
Content-Type: application/json

{
    "id": "<CHECK_ID>",
    "created_at": "2019-03-27T12:30:12Z",
    "status": "complete",
    "redirect_uri": null,
    "type": "express",
    "result": "consider",
    "sandbox": true,
    "report_type_groups": [
        "<REPORT_TYPE_GROUP_ID>"
    ],
    "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": "2019-03-27T12:30:12Z",
            "href": "/v2/checks/<CHECK_ID>/reports/<REPORT_ID>",
            "id": "<REPORT_ID>",
            "name": "watchlist",
            "properties": {
                "records": []
            },
            "result": "clear",
            "status": "complete",
            "sub_result": null,
            "variant": "full",
            "breakdown": {
                "legal_and_regulatory_warnings": {
                    "result": "clear"
                },
                "politically_exposed_person": {
                    "result": "clear"
                },
                "sanction": {
                    "result": "clear"
                }
            }
        },
        {
            "created_at": "2019-03-27T12:30:12Z",
            "href": "/v2/checks/<CHECK_ID>/reports/<REPORT_ID>",
            "id": "<REPORT_ID>",
            "name": "identity",
            "properties": {},
            "result": "unidentified",
            "status": "complete",
            "sub_result": null,
            "variant": "standard",
            "breakdown": {
                "mortality": {
                    "result": null
                },
                "date_of_birth": {
                    "result": "unidentified",
                    "breakdown": {
                        "credit_agencies": {
                            "result": "unidentified",
                            "properties": {}
                        },
                        "voting_register": {
                            "result": "none",
                            "properties": {}
                        }
                    }
                },
                "address": {
                    "result": "unidentified",
                    "breakdown": {
                        "credit_agencies": {
                            "result": "unidentified",
                            "properties": {
                                "number_of_credit_agencies": "0"
                            }
                        },
                        "telephone_database": {
                            "result": "none",
                            "properties": {}
                        },
                        "voting_register": {
                            "result": "none",
                            "properties": {}
                        }
                    }
                }
            }
        }
    ],
    "paused": false,
    "version": "2.0"
}

When you create a sandbox check with multiple reports, you can pass specific report types to the consider parameter (in an array). Only these reports will return “consider”.

Regions

Onfido.configure do |config|
  config.region = 'us'
end
$config->setHost($config->getHostFromSettings(1, array("region" => "us")));
configuration.host = configuration.get_host_from_settings(1, {'region': 'us'})

Onfido offers region-specific environments. You can use these to store the data in your Onfido account at rest within a specific geographic region.

Regions have unique base URLs and API token formats:

Region API base URL Token format
EU   Default https://api.onfido.com/ live_ and test_
US   BETA https://api.us.onfido.com/ us_live_ and us_test_

Unless specified, all examples in the documentation refer to the https://api.onfido.com/ base URL and token format.

If you’re using one of the Onfido client libraries, then you must specify the region using the ISO 3166 two-letter country-code in lowercase. For example, us. The correct base URL will be picked up automatically.

Rate limits

Rate limit reached error object

HTTP/1.1 429 Too Many Requests
Content-Type: application/json

{
  "error": {
    "id": "544f95539648607d03001542",
    "type": "rate_limit",
    "message": "Rate limit exceeded. Please try again later."
  }
}

Onfido’s API enforces a maximum volume of requests per minute for all clients. Unless contractually agreed otherwise, the maximum rate is 400 requests per minute.

For sandbox requests, there is currently a rate limit of 30 requests per minute.

Any request over the limit will return a 429 Too Many Requests error.

Avoiding the limit

The tips below are some simple suggestions to help reduce the possibility of being rate limited. We recommend:

Applicants

An applicant represents the individual the check is being performed on. An applicant must exist before a check can be initiated.

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 video first_name
last_name
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) Right to Work - first_name
last_name
gender
dob
nationality
email
nationality must be entered as a three-letter ISO code e.g. GBR
Proof of Address - first_name
last_name
address[]street
address[]town
address[]postcode
address[]country
country must be entered as a three-letter ISO code e.g. GBR

Applicant object

An example applicant object

HTTP/1.1 201 Created
Content-Type: application/json

{
  "id": "<APPLICANT_ID>",
  "created_at": "2014-05-23T13:50:33Z",
  "delete_at": "2018-10-31T04:39:52Z",
  "href": "/v2/applicants/<APPLICANT_ID>",
  "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
delete_at datetime
The date and time when this applicant is scheduled to be deleted, or null if the applicant is not scheduled to be deleted
href string
The URI of this resource
title string
The applicant’s title. Valid values are Mr, Mrs, Miss and Ms
first_name string
The applicant’s first name
middle_name string
The applicant’s middle name(s) or initial
last_name string
The applicant’s surname
email string
The applicant’s email address
gender string
The applicant’s gender. Valid values are male and female
dob date
The applicant’s date of birth in yyyy-mm-dd format
telephone string
The applicant’s landline phone number
mobile string
The applicant’s mobile phone number
country string
The country where this applicant will be checked. This must be a three-letter ISO code e.g. GBR or USA. 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_licence
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 licences 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 recommended.

Create applicant

Create applicant “Jane Doe”

POST /v2/applicants/ HTTP/1.1
Host: api.onfido.com
Authorization: Token token=<YOUR_API_TOKEN>
Content-Type: application/json

{
    "first_name": "Jane",
    "last_name": "Doe",
    "gender": "female",
    "dob": "1990-01-01",
    "telephone": "02088909293",
    "country": "GBR",
    "addresses": [
      {
      "building_number": "100",
      "street": "Main Street",
      "town": "London",
      "postcode": "SW4 6EH",
      "country": "GBR",
      "start_date": "2013-08-10"
      }
    ]
}
applicant_details = {
  title: "Ms",
  first_name: "Jane",
  last_name: "Doe",
  gender: "female",
  dob: Date.new(1990, 1, 1),
  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_details)
applicant_details = {
  title: "Ms",
  first_name: "Jane",
  last_name: "Doe",
  gender: "male",
  dob: datetime.date(1990, 1, 1),
  telephone: "02088909293",
  country: "GBR",
  addresses: [{
    building_number: 100,
    street: "Main Street",
    town: "London",
    postcode: "SW4 6EH",
    country: "GBR",
    start_date: datetime.date(2013, 8, 10)
  }]
}

api.create_applicant(applicant_details)
$applicant = new Onfido\Model\Applicant();
$applicant->setFirstName('Jane');
$applicant->setLastName('Doe');
$applicant->setGender('Female');
$applicant->setDob('1990-01-01');
$applicant->setTelephone('02088909293');
$applicant->setCountry('GBR');
$address1 = new \Onfido\Model\Address();
$address1->setBuildingNumber('100');
$address1->setStreet('Main Street');
$address1->setTown('London');
$address1->setPostcode('SW4 6EH');
$address1->setCountry('GBR');
$address1->setStartDate('2013, 8, 10');

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

$api->createApplicant($applicant);

Creates a single applicant.

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/

Request body parameters

title optional
The applicant’s title. Valid values are Mr, Mrs, Miss and Ms.
first_name required
The applicant’s forename.
last_name required
The applicant’s surname.
middle_name optional
The applicant’s middle name(s) or initials.
email required if doing a US check or a standard UK check
The applicant’s email address.
gender optional The applicant’s gender. Valid values are male and female.
dob optional
The applicant’s date of birth in yyyy-mm-dd format.
telephone optional
The applicant’s landline phone number.
mobile optional
The applicant’s mobile phone number.
country optional
The 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 optional
A collection of identification numbers belonging to this applicant
addresses optional
The address history of the applicant

Retrieve applicant

Retrieve an applicant

GET /v2/applicants/<APPLICANT_ID> HTTP/1.1
Host: api.onfido.com
Authorization: Token token=<YOUR_API_TOKEN>
api.applicant.find('<APPLICANT_ID>')
api.find_applicant('<APPLICANT_ID>')
$api->findApplicant('<APPLICANT_ID>');

Retrieves a single applicant.

Endpoint

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

Update applicant

Update an applicant

PUT /v2/applicants/<APPLICANT_ID> HTTP/1.1
Host: api.onfido.com
Authorization: Token token=<YOUR_API_TOKEN>
Content-Type: application/json

{
    "first_name": "New",
    "last_name": "Name"
}
applicant_details = {
  first_name: "New",
  last_name: "Name"
}

api.applicant.update('<APPLICANT_ID>', applicant_details)
applicant_details = onfido.Applicant()

applicant_details.first_name = "New"
applicant_details.last_name = "Name"

api.update_applicant('<APPLICANT_ID>', applicant_details)
$applicant = new Onfido\Model\Applicant();

$applicant->setFirstName('New');
$applicant->setLastName('Name');

$api->updateApplicant('<APPLICANT_ID>', $applicant);

Updates an applicant’s information.

Endpoint

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

Request body parameters

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

Delete applicant

Delete an applicant

DELETE /v2/applicants/<APPLICANT_ID> HTTP/1.1
Host: api.onfido.com
Authorization: Token token=<YOUR_API_TOKEN>
api.applicant.destroy('<APPLICANT_ID>')
api.destroy_applicant('<APPLICANT_ID>')
$api->destroyApplicant('<APPLICANT_ID>');

Deletes a single applicant.

Sending a deletion request adds the applicant and all associated documents, photos, videos, checks, and reports to our deletion queue. A 204 response is sent back to confirm the deletion request has been received. The objects will be permanently deleted 20 days after a deletion request is made.

Deleting an applicant that does not have an associated check will immediately delete the applicant and any resources.

Endpoint

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

Restore applicant

Restore an applicant

POST /v2/applicants/<APPLICANT_ID>/restore HTTP/1.1
Host: api.onfido.com
Authorization: Token token=<YOUR_API_TOKEN>
api.applicant.restore('<APPLICANT_ID>')
api.restore_applicant('<APPLICANT_ID>')
$applicant->restoreApplicant('<APPLICANT_ID>');

Restores a single applicant scheduled for deletion.

A restore request will also restore all associated documents, photos, videos, checks, and reports. A 204 response is sent back to confirm the restore request has been received. Applicants that have been permanently deleted cannot be restored.

Endpoint

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

List applicants

Return all applicants you’ve created

GET /v2/applicants/ HTTP/1.1
Host: api.onfido.com
Authorization: Token token=<YOUR_API_TOKEN>
api.applicant.all(page:1, per_page: 20)
api.list_applicants(page=1, per_page=20)
$page = 1;
$per_page = 20;
$api_instance->listApplicants($page, $per_page);

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

Returns all applicants you’ve created, sorted by creation date in descending order.

Requests to this endpoint will be paginated to 20 items by default.

Query string parameters

include_deleted=true (optional): include applicants scheduled for deletion.

per_page (optional): set the number of results per page. Defaults to 20.

page (optional): return specific pages. Defaults to 1.

The Link header contains pagination information. For example:

Link: <https://api.onfido.com/v2/applicants?page=3059>; rel="last", <https://api.onfido.com/v2/applicants?page=2>; rel="next"

Possible rel values are:

Name Link relation (description)
next Next page of results
last Last page of results
first First page of results
prev Previous page of results

The custom X-Total-Count header gives the total resource count.

You can read more about Link headers on the IETF website.

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

An example document object

HTTP/1.1 201 Created
Content-Type: application/json

{
  "id": "<DOCUMENT_ID>",
  "created_at": "2019-02-11T13:49:20Z",
  "file_name": "sample_driving_licence.png",
  "file_type": "png",
  "file_size": 490408,
  "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"
}

The example given is for a driving licence document.

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
issuing_country string
The issuing country of the document, in 3-letter ISO code, specified when uploading it.

Document types

Identity documents

The following table is a list of some of the identity documents that we accept. You can review a full list of supported identity documents.

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, which are specific to certain reports (such as the Right to Work report):

Type
work_permit
national_insurance_card
birth_certificate
bank_statement

Upload document

Upload “passport.png”

POST /v2/applicants/<APPLICANT_ID>/documents/ HTTP/1.1
Host: api.onfido.com
Authorization: Token token=<YOUR_API_TOKEN>
Content-Type: multipart/form-data

<YOUR FILE DATA (path/to/passport.png)>
applicant_id = '<APPLICANT_ID>'
file = File.new('path/to/passport.png')
type = 'passport'

api.document.create(applicant_id, file: file, type: type)
applicant_id = '<APPLICANT_ID>'
file = 'path/to/passport.png'
type = 'passport'

api.upload_document(applicant_id, type, file)
$applicant_id = '<APPLICANT_ID>';
$type = 'passport';
$side = null;
$file = 'path/to/passport.png';

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

You can upload documents to this endpoint as part of multipart requests.

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/

Request body parameters

file required
The file to be uploaded
type required
The type of document
side optional
Either the front or back of the document.
issuing_country optional
The issuing country of the document in 3-letter ISO code.

Retrieve document

Retrieve a document for a specific applicant

POST /v2/applicants/<APPLICANT_ID>/documents/<DOCUMENT_ID> HTTP/1.1
Host: api.onfido.com
Authorization: Token token=<YOUR_API_TOKEN>
applicant_id = '<APPLICANT_ID>'
document_id = '<DOCUMENT_ID>'

api.document.find('applicant_id', 'document_id')
applicant_id = '<APPLICANT_ID>'
document_id = '<DOCUMENT_ID>'

api.find_document(applicant_id, document_id)
$applicant_id = '<APPLICANT_ID>';
$document_id = '<DOCUMENT_ID>';

$api->findDocument($applicant_id, $document_id);

Retrieves a single document.

ENDPOINT

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

List documents

List all documents for a specific applicant

GET /v2/applicants/<APPLICANT_ID>/documents/ HTTP/1.1
Host: api.onfido.com
Authorization: Token token=<YOUR_API_TOKEN>
applicant_id = '<APPLICANT_ID>'

api.document.all(applicant_id)
applicant_id = '<APPLICANT_ID>'

api.list_documents(applicant_id)
$applicant_id = '<APPLICANT_ID>';

$api->listDocuments($applicant_id);

Lists all documents belonging to an applicant.

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

Download document

Download a document associated with an applicant

GET /v2/applicants/<APPLICANT_ID>/documents/<DOCUMENT_ID>/download HTTP/1.1
Host: api.onfido.com
Authorization: Token token=<YOUR_API_TOKEN>
applicant_id = '<APPLICANT_ID>'
document_id = '<DOCUMENT_ID>'

api.document.download(applicant_id, document_id)
applicant_id = '<APPLICANT_ID>'
document_id = '<DOCUMENT_ID>'

api.download_document(applicant_id, document_id)
$applicant_id = '<APPLICANT_ID>';
$document_id = '<DOCUMENT_ID>';

$api->downloadDocument($applicant_id, $document_id);

Downloads specific documents belong to an applicant.

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

An example live photo object

HTTP/1.1 201 Created
Content-Type: application/json

{
  "id": "<LIVE_PHOTO_ID>",
  "created_at": "2016-05-11T11:45:26Z",
  "href": "/v2/live_photos/<LIVE_PHOTO_ID>",
  "download_href": "/v2/live_photos/<LIVE_PHOTO_ID>/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

Upload “sample_photo.png”

POST /v2/live_photos/ HTTP/1.1
Host: api.onfido.com
Authorization: Token token=<YOUR_API_TOKEN>
Content-Type: multipart/form-data

<YOUR FILE DATA (path/to/sample_photo.png)>

You can upload live photos to this endpoint as part of multipart requests.

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/

Request body parameters

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

Retrieve a single live photo’s object

GET /v2/live_photos/<LIVE_PHOTO_ID> HTTP/1.1
Host: api.onfido.com
Authorization: Token token=<YOUR_API_TOKEN>

Retrieves a single live photo. Returns the corresponding live photo object.

ENDPOINT

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

List live photos

List all live photo (objects) for a specific applicant

GET /v2/live_photos/live_photos?applicant_id=<APPLICANT_ID> HTTP/1.1
Host: api.onfido.com
Authorization: Token token=<YOUR_API_TOKEN>

Lists the live photos that belong to an applicant. Returns the corresponding live photo objects.

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

Query string parameters

applicant_id (required): the ID of the applicant whose live photos you want to list.

Download live photo

Download the data representing a photo

GET /v2/live_photos/<LIVE_PHOTO_ID>/download HTTP/1.1
Host: api.onfido.com
Authorization: Token token=<YOUR_API_TOKEN>

Downloads a live photo.

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 the Facial Similarity check on the applicant.

Live video object

An example live video object

HTTP/1.1 201 Created
Content-Type: application/json

{
    "id": "<LIVE_VIDEO_ID>",
    "created_at": "2018-05-14T16:44:53Z",
    "href": "/v2/live_photos/<LIVE_VIDEO_ID>",
    "download_href": "/v2/live_photos/<LIVE_VIDEO_ID>/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 challenges 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

Retrieve a single live video’s object

GET /v2/live_videos/<LIVE_VIDEO_ID> HTTP/1.1
Host: api.onfido.com
Authorization: Token token=<YOUR_API_TOKEN>

Retrieves a single live video. This will return the corresponding live video object.

ENDPOINT

GET https://api.onfido.com/v2/live_videos/{live_video_id}

List live videos

List all live videos for a specific applicant

GET /v2/live_videos?applicant_id=<APPLICANT_ID> HTTP/1.1
Host: api.onfido.com
Authorization: Token token=<YOUR_API_TOKEN>

Lists all the live videos that belong to an applicant.

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

Query string parameters

applicant_id (required): the ID of the applicant whose live videos you want to list.

Download live video

Download the data representing a live video

GET /v2/live_videos/<LIVE_VIDEO_ID>/download HTTP/1.1
Host: api.onfido.com
Authorization: Token token=<YOUR_API_TOKEN>

Downloads a live video.

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.

A check consists of many reports. You can read about the different report types.

Check object

An example check object

HTTP/1.1 201 Created
Content-Type: application/json

{
  "id": "<CHECK_ID>",
  "created_at": "2014-05-23T13:50:33Z",
  "href": "/v2/applicants/<APPLICANT_ID>/checks/<CHECK_ID>",
  "type": "express",
  "status": "complete",
  "result": "clear",
  "redirect_uri": "https://somewhere.else",
  "results_uri":
  "https://onfido.com/dashboard/information_requests/<REQUEST_ID>",
  "download_uri":
  "https://onfido.com/dashboard/pdf/information_requests/<REQUEST_ID>",
  "reports": [
    "<REPORT_ID>",
    "<REPORT_ID>"
  ],
  "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

Create a check (Identity report, standard variant)

POST /v2/applicants/<APPLICANT_ID>/checks/ HTTP/1.1
Host: api.onfido.com
Authorization: Token token=<YOUR_API_TOKEN>
Content-Type: application/json

{
    "type": "express",
    "reports": [{
        "name": "identity",
        "variant": "standard"
    }]
}
reports = [{name: 'document'}, {name: 'facial_similarity', variant: 'standard'}]
check = api.check.create(applicant_id, type: 'express', reports: reports)
check_data = onfido.Check()
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, check_data)
$check_data = new Onfido\Model\Check();
$check_data->setType('express');

$document_report = new Onfido\Model\Report();
$document_report->setName('document');

$facial_similarity_report = new Onfido\Model\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);

Initiates a check for an applicant.

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/

Request body parameters

type required
standard or express. See “Check Types”.
redirect_uri optional
For standard checks, redirect to this URI when the applicant has submitted their data.
reports optional
Array of reports being requested for this check.
report_type_groups optional
Array containing ids of the report type groups** being requested for
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
asynchronous (alias)
recommended
If this is set to true, we will queue checks for processing and return a response immediately. You can configure webhooks to notify you when the report is complete.
Defaults to false
Note: async and asynchronous cannot both be provided.
charge_applicant_for_check optional
For standard checks, applicants will be presented with a mandatory payment screen before they can submit the applicant form, if this is set to true. In this case, your account will not be charged.
Defaults to false
consider optional
Array of names of the reports to return consider as their results. This is a sandbox testing specific argument for testing multiple-report scenarios.

Request body parameters (report)

name required
The name of the report type. You can read about the different report types.
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.

Request body parameters (report options)

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)

Request body parameters (report documents)

id required
ID of uploaded document to use.

Retrieve check

Retrieve a single check’s object

POST /v2/applicants/<APPLICANT_ID>/checks/<CHECK_ID> HTTP/1.1
Host: api.onfido.com
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.find_check(applicant_id, check_id)
$applicant_id = "1030303-123123-123123";
$check_id = "8546921-123123-123123";

$api->findCheck($applicant_id, $check_id);

Retrieves a single check.

ENDPOINT

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

List checks

List all checks associated with an applicant

GET /v2/applicants/<APPLICANT_ID>/checks/ HTTP/1.1
Host: api.onfido.com
Authorization: Token token=<YOUR_API_TOKEN>
api.check.all('<APPLICANT_ID>')
applicant_id = "<APPLICANT_ID>"

checks = api.list_checks(applicant_id)
$applicant_id = "<APPLICANT_ID>";

$api->listChecks($applicant_id);

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

Returns all checks for an applicant.

You can expand the reports value to return a list of the report objects in the response instead of the default list of report IDs.

Query string parameters

expand=reports (Optional)

Resume check

Resume a paused check

GET /v2/checks/<CHECK_ID>/resume HTTP/1.1
Host: api.onfido.com
Authorization: Token token=<YOUR_API_TOKEN>

Resumes a paused check.

A check is paused if all the reports that it contains are in the paused state. A 204 No Content response is sent back to confirm the request has been received.

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

An example report object (Identity report, awaiting data)

HTTP/1.1 201 Created
Content-Type: application/json

{
  "id": "<REPORT_ID>",
  "name": "identity",
  "created_at": "2014-05-23T13:50:33Z",
  "status": "awaiting_data",
  "result": null,
  "sub_result": null,
  "variant": null,
  "options": {},
  "href": "/v2/checks/<CHECK_ID>/reports/<REPORT_ID>",
  "breakdown": {},
  "properties": {},
  "documents": []
}

The report object contains the state and relevant details of the particular report. The structure of the object is listed at right, under the shell tab.

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 in the “Document report” section.

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 have sub-types, which are identified by this field. These are detailed in the “Report types” section
options string
Report options. Some reports expose additional options. These are detailed in the “Report types” section
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
documents array
The document ids that were processed. Only for Document report.

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.

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

Retrieve a single report

GET /v2/checks/<CHECK_ID>/reports/<REPORT_ID> HTTP/1.1
Host: api.onfido.com
Authorization: Token token=<YOUR_API_TOKEN>
api.report.find('<CHECK_ID>', '<REPORT_ID>')
check_id = "<CHECK_ID>"
report_id = "<REPORT_ID>"

report = api.find_report(check_id, report_id)
$check_id = "<CHECK_ID>";
$report_id = "<REPORT_ID>";

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

Retrieves a single report.

Endpoint

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

List reports

List all reports

GET /v2/checks/<CHECK_ID>/reports/ HTTP/1.1
Host: api.onfido.com
Authorization: Token token=<YOUR_API_TOKEN>
api.report.all('<CHECK_ID>')
check_id = "<CHECK_ID>"

api.list_reports(check_id)
$check_id = "<CHECK_ID>";

$api->listReports($check_id);

Lists all reports belonging to a particular check.

Endpoint

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

Resume report

Resume a single paused report

POST /v2/checks/<CHECK_ID>/reports/<REPORT_ID>/resume HTTP/1.1
Host: api.onfido.com
Authorization: Token token=<YOUR_API_TOKEN>

Resumes a single paused report.

A 204 No Content response is sent back to confirm the request has been received.

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

Cancel a single paused report

POST /v2/checks/<CHECK_ID>/reports/<REPORT_ID>/cancel HTTP/1.1
Host: api.onfido.com
Authorization: Token token=<YOUR_API_TOKEN>

Cancels single paused reports. If successful, returns a 204 No Content response.

When a 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

An example document report object (UK passport)

HTTP/1.1 201 Created
Content-Type: application/json

{
  "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.

An example Facial Similarity report object

HTTP/1.1 200 OK
Content-Type: application/json

{
  "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’ variant response

HTTP/1.1 200 OK
Content-Type: application/json

{
    "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 report will compare the most recent live photo or live video provided by the applicant to the face on the most recent identity document provided, where the attribute side is front. If none exists the latest document will be used.

When side is not specified, it will take a default value of front. It is recommended that all documents contain the side attribute, as this minimises the cases where the back of the document is used for comparison and thus failed as no face is detected.

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 person in the live photo or live video is real (not a spoof) and live (only done for live videos)

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 face matching algorithm fails to detect a face, the score property will not be present and the face matching task will be done manually. 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

In the video variant, live videos are collected and uploaded by the Onfido iOS, Android or JS 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. This is reflected in visual_authenticity which is augmented with two sub breakdowns: spoofing_detection and liveness_detected.

spoofing_detection hash
Asserts whether the live video is not a spoof (such as videos of digital screens)
liveness_detected hash
Asserts whether the numbers and head movements were correctly executed

Identity report

Report Name Variants Standard check Express check
Identity report identity kyc
standard
yes
yes
yes
yes

An example Identity report object

HTTP/1.1 200 OK
Content-Type: application/json

{
  "id": "<REPORT_ID>",
  "name": "identity",
  "created_at": "2014-05-23T13:50:33Z",
  "status": "complete",
  "result": "clear",
  "href": "/v2/checks/<CHECK_ID>/reports/<REPORT_ID>",
  "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 with social security number provided

HTTP/1.1 201 Created
Content-Type: application/json

{
  "id": "<REPORT_ID>",
  "name": "identity",
  "created_at": "2014-05-23T13:50:33Z",
  "status": "complete",
  "result": "clear",
  "href": "/v2/checks/<CHECK_ID>/reports/<REPORT_ID>",
  "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

HTTP/1.1 201 Created
Content-Type: application/json

{
  "id": "<REPORT_ID>",
  "name": "identity",
  "created_at": "2014-05-23T13:50:33Z",
  "status": "complete",
  "result": "clear",
  "href": "/v2/checks/<CHECK_ID>/reports/<REPORT_ID>",
  "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. Please 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:

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":{}.

Source 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. In the UK, this is landline only
Government Any standard publicly accessible data collected by government entities. These include driving licence 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 the Identity report: kyc and standard. To specify which one you want, pass variant with the create check request. If not provided the default is standard.

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:

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:

When the SSN or the last four digits of the SSN are provided:

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.

Standard

This check should be used for employment or recruitment purposes, or where identity verification is performed in an unregulated industry.

Overall result logic:

When the SSN or the last four digits of the SSN are provided:

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.

Watchlist KYC report

Report Name Variants Standard check Express check
Watchlist report watchlist kyc yes yes

An example Watchlist ‘KYC’ report object

HTTP/1.1 201 Created
Content-Type: application/json

{
    "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

An example Watchlist ‘full’ report object

HTTP/1.1 201 Created
Content-Type: application/json

{
    "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

An example Street Level report object

HTTP/1.1 201 Created
Content-Type: application/json

{
  "id": "<REPORT_ID>",
  "name": "street_level",
  "created_at": "2014-05-23T13:50:33Z",
  "status": "complete",
  "result": "clear",
  "href": "/v2/checks/<CHECK_ID>/reports/<REPORT_ID>",
  "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:

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

Proof of Address report

Report Name Variants Standard check Express check
Proof of Address report proof_of_address - no yes

The Onfido Proof of Address (PoA) solution allows users to upload PoA documents from anywhere in the world. Currently, the Onfido platform can only process UK PoA documents.

The document’s issuing country must be specified when uploading the document via the document upload endpoint by setting the issuing_country field. If the issuing_country field is not specified or is from an unsupported country (i.e. it is different from “GBR”), the document will be uploaded on the system however it will not be processed and the report will complete with the status set to cancelled and the result set to null.

Supported document types

Bank Statement/Building Society Statements bank_building_society_statement
Utility Bill (electricity, water, gas, broadband ) utility_bill
Council Tax council_tax
Benefits Letter (i.e. Job seeker allowance, House benefits, Tax credits) benefit_letters

For PoA documents from unsupported countries (i.e. non-UK PoA documents), the following document types can be uploaded to the system:

“Capture Only” Document Types

Bank Statement/Building Society Statements bank_building_society_statement
Utility Bill (electricity, water, gas, broadband ) utility_bill
Government Letters government_letter

A PoA report upon completion is composed of three breakdowns: image integrity, document classification and data comparison.

Breakdowns

image_integrity hash
Asserts whether the quality of the uploaded document was sufficient to verify the address
document_classification hash
Asserts whether the document is of a valid type as PoA
data_comparison hash
Asserts whether the first name, last name and address provided by the applicant match those on the PoA document

In addition, data points extracted from PoA documents are returned in the properties attribute:

Properties

document_type This property provides the document type according to the set of supported documents
issue_date This property provides the issue date of the document
summary_period_start This property provides the summary period start date
summary_period_end This property provides the summary period end date
issuer This property provides the document issuer (e.g. HSBC, British Gas)
first_names This property provides the first names on the document, including any initials and middle names
last_names This property provided the last names on the document
address This property provides the address on the document

The summary period and the issue date are mutually exclusive, in the sense that only one of them is returned in the report properties attribute (either the summary period start and end dates or the issue date).

Overall result logic

The PoA report can return a result of clear or consider or null.

The overall report result will be clear if all of the following are true:

The overall report result will be null if any of the following is true:

Please note that if the report result is null, the report status will be cancelled.

The overall report result will be consider if any of the following is true:

UK

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

ReportNameVariantsStandard checkExpress check
Right to work report right_to_work yes yes

Right to Work report

An example “Right to Work” report object

HTTP/1.1 201 Created
Content-Type: application/json

{
  "id": "<REPORT_ID>",
  "name": "right_to_work",
  "created_at": "2014-05-23T13:50:33Z",
  "status": "complete",
  "result": "clear",
  "href": "/v2/checks/<CHECK_ID>/reports/<REPORT_ID>",
  "breakdown": {},
  "properties": {}
}

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

Document requirements

Document requirements for a Right to Work report are

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

for citizens of other nationalities

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

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. You 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 within 10 seconds. 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:

United States:

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

Webhook object

An example webhook object (check started)

HTTP/1.1 200 OK 
Content-Type: application/json

{
  "webhooks": [
    {
      "id": "<WEBHOOK_ID>",
      "url": "https://demo.com","enabled":false,
      "href": "/v2/webhooks/<WEBHOOK_ID>",
      "token": "<WEBHOOK_TOKEN>",
      "environments": [
        "sandbox"
      ],
      "events": [
        "check.started"
      ]
    }
  ]
}

Lists all the webhooks you’ve created.

Events

The following events will trigger a message to registered webhooks:

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

Event object

An example event object (report completed)

HTTP/1.1 201 Created
Content-Type: application/json

{
  "payload": {
    "resource_type": "report",
    "action": "report.completed",
    "object": {
      "id": "<REPORT_ID>",
      "status": "completed",
      "completed_at": "2014-05-23 13:50:33 UTC",
      "href": "https://api.onfido.com/v2/checks/<CHECK_ID>/reports/<REPORT_ID>"
    }
  }
}

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

Register a webhook

POST /v2/webhooks/ HTTP/1.1
Host: api.onfido.com
Authorization: Token token=<YOUR_API_TOKEN>
Content-Type: application/json

{
    "url": "https://<URL>",
    "enabled": true,
    "environments": [
        "live",
        "sandbox"
    ],
    "events": [
        "report.completed",
        "report.withdrawn",
        "check.completed",
        "check.started",
        "check.form_opened",
        "check.form_completed"
    ]
}

Example response

HTTP/1.1 201 Created
Content-Type: application/json

{
  "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/

Request body parameters

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. If omitted, all events will be subscribed by default. You can read about the supported events.

Retrieve webhook

Retrieve a webhook

GET /v2/webhooks/<WEBHOOK_ID> HTTP/1.1
Host: api.onfido.com
Authorization: Token token=<YOUR_API_TOKEN>

Retrieves a single webhook.

Endpoint

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

List webhooks

List all webhooks you’ve created

GET /v2/webhooks/ HTTP/1.1
Host: api.onfido.com
Authorization: Token token=<YOUR_API_TOKEN>

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 and a right_to_work 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

An example report type group object (Identity, Right to Work)

HTTP/1.1 201 Created
Content-Type: application/json

{
  "id": "<REPORT_TYPE_GROUP_ID>",
  "name": "Junior level",
  "group_only": false,
  "report_types": [
    {
      "id": "<REPORT_ID>",
      "name": "identity"
    },
    {
      "id": "<REPORT_ID>",
      "name": "right_to_work"
    }
  ]
}

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

Retrieve a single report type group

GET /v2/report_type_groups/<REPORT_TYPE_GROUP_ID> HTTP/1.1
Host: api.onfido.com
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

List report type groups

GET /v2/report_type_groups/ HTTP/1.1
Host: api.onfido.com
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

Example request: search for address using a postcode

GET /v2/addresses/pick?postcode=SW46EH HTTP/1.1
Host: api.onfido.com
Authorization: Token token=<YOUR_API_TOKEN>
api.address.all('SW4 6EH')
api.find_addresses('SW4 6EH')
$postcode = 'SW4 6EH';
$api->findAddresses($postcode);

Example response: search for address using a postcode

HTTP/1.1 201 Created
Content-Type: application/json

{
  "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?postcode={postcode}

Query string parameters

postcode (required): the applicant’s postcode.

Generate Web SDK token

Example request: generate a new SDK token

POST /v2/sdk_token HTTP/1.1
Host: api.onfido.com
Authorization: Token token=<YOUR_API_TOKEN>
Content-Type: application/json

{
  "applicant_id":"<APPLICANT_ID>"
  "referrer:"https://<URL>"
}

Example response: generate a new SDK token

HTTP/1.1 201 Created
Content-Type: application/json

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

Web SDK tokens are specifically for use with the Onfido Web SDK. You can read more about how to use them.

Endpoint

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

Request body parameters

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 Web SDK will be used. The referrer must match the web page for the SDK to authenticate. The referrer is based on the Google 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)

Example request: return information extracted from a document

POST /v2/ocr HTTP/1.1
Host: api.onfido.com
Authorization: Token token=<YOUR_API_TOKEN>
Content-Type: application/json

{
  "document_id": "<DOCUMENT_ID>"
}

Example response: return information extracted from a document

HTTP/1.1 201 Created
Content-Type: application/json

{
  "document_id": "<DOCUMENT_ID>",
  "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

Request body parameters

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

Unsuccessful extraction response: classification failure

HTTP/1.1 500 Internal Server Error
Content-Type: application/json

{
  "document_id": "<DOCUMENT_ID>",
  "error": {
    "type": "classification_failure",
    "message": "We couldn’t recognise the type of this document."
  }
}

Unsuccessful extraction response: extraction failure

HTTP/1.1 500 Internal Server Error
Content-Type: application/json

{
  "document_id": "<DOCUMENT_ID>",
  "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 submitted for the address to be validated.

Submit code

Example request: submit a street level code

POST /v2/slv HTTP/1.1
Host: api.onfido.com
Authorization: Token token=<YOUR_API_TOKEN>
Content-Type: application/json

{
    "code": "<STREET_LEVEL_CODE>"
}

Example response: submit a street level code

HTTP/1.1 200 OK
Content-Type: application/json

{
  "success": true
}

You can submit Street Level report codes to this endpoint.

ENDPOINT

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

Request body parameters

code required
The unique code present in the Street Level report letter