API Reference

v3

Overview

Get started (API v2)

The Onfido API is based on REST principles. It uses standard HTTP response codes and verbs, and token-based authentication.

If you're just getting started with our API, read our quick-start guides.

Request, response format

You should use a Content-Type: application/json header with all PUT and POST requests except when uploading documents or live photos. For these requests, use a Content-Type: multipart/form-data header.

Responses return JSON with a consistent structure, except downloads.

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.

Token authentication

The Onfido API uses token-based authentication. API tokens must be included in the header of all requests made to the API.

You can generate new tokens and find your existing ones in your Onfido Dashboard.

You can make requests using sandbox tokens to test our API before you go live.

Token Authentication
HTTP
Copy
Authorization: Token token=<YOUR_API_TOKEN>

API tokens

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

You must never use API tokens in the frontend of your application or malicious users could discover them in your source code. You should only use them on your server.

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

You should limit live API token access to only the minimum number of people necessary, but you can use sandbox tokens to freely experiment with the sandbox Onfido API.

Note that there are some differences between the sandbox and live APIs.

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.

You should also periodically rotate your live API tokens (see next section).

API token rotation

We highly recommend that you rotate live API tokens when staff members with access to those tokens leave your organisation. Consider creating a leaver's process which covers this.

You can create and revoke API tokens, and see when they were last used, in your Onfido Dashboard.

  1. Create a new API token

  2. Wherever you use your old API token, replace it with the new one

  3. Confirm your old token isn't in use

  4. Revoke your old token

Your old API tokens will continue to work until you revoke them, so you can rotate your tokens without users experiencing any downtime.

SDK tokens

If you're using the Android SDK at lower than version 4.11.0 or the iOS SDK lower than 12.2.0, please use Mobile tokens.

All of the latest Onfido input-capture SDKs authenticate using SDK tokens. You cannot use an API token to authenticate the SDKs.

SDK tokens are restricted to an individual applicant and expire after 90 minutes.

You can generate SDK tokens using an API endpoint.

Mobile tokens

Mobile tokens will be deprecated in the future.

You should use Mobile tokens to authenticate with the Android and iOS SDKs if:

  • you're using the Android SDK at lower than version 4.11.0
  • you're using the iOS SDK at lower than version 12.2.0

You can generate Mobile tokens in your Onfido Dashboard.

Sandbox testing

For sandbox requests, the rate limit is 30 requests per minute. When you hit the limit, you'll receive a 429 Too Many Requests error.

The type of token you use will determine whether you use the sandbox or live environment.

You can use the sandbox to test your technical integration with Onfido's software and to simulate API requests. You should never upload confidential information, including personal data, to the sandbox.

To use the sandbox, you'll need a sandbox API token. You can generate one in your Onfido Dashboard.

You can use the sandbox API to check:

  • your system's network connectivity with the Onfido API
  • your webhooks are working correctly
  • you're posting all required data in the correct format to the Onfido API
  • you're handling the Onfido API responses correctly

By default, sandbox API tokens start with a api_sandbox. prefix, while live API tokens start with a api_live. prefix. This might vary if you're using a different region environment.

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

Sandbox and live differences

The key differences between sandbox and live checks are:

  • sandbox check data is not processed by Onfido services or third parties - this means that sandbox responses are faster than live responses
  • sandbox check results are pre-determined (but contain the same result response structures as live requests)
  • sandbox applicants are isolated from the live environment (but applicant notification emails still get sent out to sandbox applicants)
  • you won't be charged for checks in sandbox

Sample document, photo

You can use the upload document endpoint with the following files as part of running test checks:

The sandbox API will always return pre-determined responses, regardless of what files are uploaded.

These files also work for testing the Onfido input-capture SDKs.

Pre-determined responses

To help you test your integration in the sandbox API, you can trigger pre-determined report responses which have a consider result.

To do this, create an applicant which has the last name "Consider". Then, create a check with this applicant.

If you use any other applicant last name, the API result will be clear.

This works for the following report types:

Different reports have different minimum requirements for applicant data (even in the sandbox).

Create an applicant with last name of "Consider"
HTTP
Copy
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": "Consider"
}

Pre-determined responses for multiple-report checks

To test multiple sandbox report responses simultaneously, pass specific report types to the consider parameter (in an array). Only these reports will return a consider sub-result.

Trigger a 'consider' result for a single report (Identity)
HTTP
Copy
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 responses for Document report sub-results

You can trigger responses for particular sub-results for sandbox Document reports. These responses show possible individual breakdown results which can lead to different sub-results.

To do this, pass the sub_result parameter using one of the following strings:

  • "clear"
  • "rejected"
  • "suspected"
  • "caution"

Passing sub_result to generate a pre-determined Document report sub-result will override any of the other options for pre-determined responses (i.e. last name "Consider", anything specified in the consider array).

Trigger a 'rejected' sub-result for a Document report
HTTP
Copy
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"
    }
  ],
  "sub_result": "rejected"
}

Postman collection

You can run the Onfido API version 2 collection in Postman:

Run in Postman

The API version 2 Postman collection is at version 1.4.

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

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

Go live

Before you go live, you may find the introductory guides on our Developer Hub useful.

API client libraries

LanguageLibraryNotes
Rubyonfido-rubyAPI v2 support only up to v0.15.0
Javaapi-java-client
JavaScriptapi-javascript-client
Pythonapi-python-client
PHPapi-php-client

OpenAPI specification

We publicly host an OpenAPI specification.

For any custom libraries you generate yourself with this specification, we can only provide support on a best-effort basis.

Rate limits

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, the rate limit is 30 requests per minute.

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

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

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

Regions

Onfido offers region-specific environments: EU (default), US, and Canada. 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 for both live and sandbox environments.

Change the region to 'US'
Bash
Copy
$ curl https://api.us.onfido.com/v2/
RegionNotesAPI base URLAPI token format
EUDefaulthttps://api.onfido.com/
UShttps://api.us.onfido.com/Tokens are prepended with api_live_us. and api_sandbox_us.
CACurrently in betahttps://api.ca.onfido.com/Tokens are prepended with api_live_ca. and api_sandbox_ca.

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

For the 'EU' region, data is physically stored in the Republic of Ireland, with backup storage in Germany.

Backwards compatibility

The following changes are considered backwards compatible:

  • adding new API endpoints
  • adding new properties to the responses from existing API endpoints
  • adding optional request parameters to existing API endpoints
  • altering the format or length of IDs
  • altering the message attributes returned by validation failures or other errors
  • sending webhooks for new event types
  • reordering properties returned from existing API endpoints

We do not class these as breaking changes.

Changelog

2020-10-22New API documentation system released
2020-09-18Added new sandbox pre-determined responses for Document reports
2020-06-09Adds Canada region base URL and Canada webhook IP addresses
2020-03-12Added documentation on the Known Faces report
2020-02-04Removed the ability to charge applicants for checks
2019-11-25Updated the example webhook event object
2019-11-19Added documentation for using line1, line2, line3 for address
2019-11-08Added documentation for building custom logic around Identity reports
2019-10-30Added documentation on forbidden characters for names and addresses
2019-09-11Added documentation on API token rotation
2019-09-04Updated documentation on Mobile tokens and SDK tokens
2019-09-01Updated documentation for Autofill endpoint and Document report results
2019-08-31Added documentation surrounding logic around Document report results
2019-06-05Added endpoint to download a live video frame
2019-03-14Removed 'Conditional checks' section
2019-03-11Added testing data for Proof of Address
2019-03-07Added a 'Run in Postman' button linking to a Postman API collection
2019-02-18Removed documentation for UK credit and criminal history reports
2019-02-06Updated the Proof of Address documentation
2018-12-18Added a new rate limits feature
2018-12-13Removed documentation for India Aadhaar and PAN Card reports
2018-12-03Added applicant deletion feature
2018-11-26Added Proof of Address report
2018-10-15Added age_validation as a new breakdown on the Document report
2018-09-18Removed documentation for US-specific reports
2018-08-15Added documents as a new report argument
2018-05-24Added new Autofill endpoint
2017-12-18Updated 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-04Added new events to the webhooks section
2017-08-25Updated documentation on Facial Similarity Report
Added support for Facial Similarity reports under sandbox responses
2017-07-14Added a new token authentication scheme for the web SDK
2017-03-03Added report options for Watchlist full report
2017-02-21Added support for additional reports under sandbox responses
2017-02-01Added new client libraries
2017-01-18Added social_insurance as a id number type
2016-12-08Added support for basic criminal history report as an Express check
2016-10-31Added support of testing multiple-report scenarios inside sandbox
2016-10-24Added support of additional criminal history report details in create check
2016-09-29Added documentation around tag support for checks
Added more detailed description of applicant address requirements
2016-09-15Added endpoint to download document for a particular applicant
2016-09-07Added 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-01Added new section on Testing
2016-08-25Added the referrer argument to the JSON web token endpoint
2016-08-25Added endpoint:
Added new report:
2016-08-25Added two new endpoints:
2016-08-15Added 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-08Added Resume Report endpoint and Conditional Checks documentation
2016-07-14Added Report Type Groups (packages) support
2016-04-25Released API v2:
  • Restructures document report results for greater clarity and detail
  • Changes the report type name for SSN trace from identity to ssn_trace

Errors

All errors are returned with the same structure:

JSON
Copy
{
  "error": {
    "type": <TYPE>,
    "message": <MESSAGE>,
    "fields": <FIELDS - NOT ALWAYS PRESENT>
  }
}

Example error object

AttributeDescription
typestring
The type of error returned.
messagestring
A human-readable message giving more details about the error.
fieldsobject
The invalid fields and their associated errors. Only applies to validation errors.
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"
        ]
      }
    }
  }
}

Error codes and what to do

StatusAction
400 bad_requestMake sure your request is formatted correctly.
401 authorization_errorMake sure you've entered your API token correctly.
The Onfido input-capture SDKs use SDK tokens for authentication, not API tokens. If you're receiving a 401 error on one of our SDKs, check you've entered a valid application ID when generating the SDK token.
401 user_authorization_errorContact an administrator about user permissions.
401 bad_referrerCheck the referrer used to generate the SDK token.
401 expired_tokenRequest a new SDK token.
403 account_disabledPlease contact client-support@onfido.com.
403 trial_limits_reachedPlease contact client-support@onfido.com.
404 resource_not_foundMake sure you've formatted the URI correctly.
410 goneThe resource has been deleted or is scheduled for deletion.
422 validation_errorCheck the fields property for a specific error message.
422 missing_billing_infoMake sure you've provided your billing information before starting a check.
422 missing_documentsMake sure you've uploaded the required documents before starting a check.
422 invalid_reports_namesMake sure you've entered the report name(s) in the correct format (string).
422 missing_id_numbersMake sure you've supplied all required ID numbers.
422 invalid_check_type_for_variantRead about report types to see which variants are compatible with different check types.
422 facial_similarity_photo_without_documentFor standard checks, Facial Similarity reports must be paired with Document reports.
422 failed_check_requirementsCheck that all required information has been provided and correctly specified.
422 incomplete_checksThere are other ongoing checks associated with this applicant.
429 rate_limitThe rate limit has been reached. Please try again later.
500 internal_server_errorThe server encountered an error. If this persists, please contact client-support@onfido.com.

Core Resources

Applicants

An applicant represents an individual who will be the subject of a check. An applicant must exist before a check can be initiated.

Different report types have different minimum requirements for applicant data, and different recommended data. For each report, this information is noted in under the relevant section of this documentation. For example, for Document reports.

Applicant object

AttributeDescription
idstring
The unique identifier for the applicant.
created_atdatetime
The date and time when this applicant was created.
delete_atdatetime
The date and time when this applicant is scheduled to be deleted, or null if the applicant is not scheduled to be deleted.
hrefstring
The URI of this resource.
titlestring
The applicant's title. Valid values are Mr, Mrs, Miss and Ms.
first_namestring
The applicant's first name.
middle_namestring
The applicant's middle name(s) or initial.
last_namestring
The applicant's surname.
emailstring
The applicant's email address.
genderstring
The applicant's gender. Valid values are male and female.
dobdate
The applicant's date of birth in YYYY-MM-DD format.
telephonestring
The applicant's landline phone number.
mobilestring
The applicant's mobile phone number.
countrystring
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_namestring
The applicant's mother's maiden name.
previous_last_namestring
The applicant's previous surname.
nationalitystring
The applicant's current nationality. This must be a three-letter ISO code e.g. GBR or USA.
country_of_birthstring
The applicant's country of birth. This must be a three-letter ISO code e.g. GBR or USA.
town_of_birthstring
The applicant's town of birth.
id_numbersarray of id number objects
A collection of identification numbers belonging to this applicant.
addressesarray of address objects
The address history of the applicant.

ID number object

The ID number array of objects is nested inside the applicant object.

AttributeDescription
typestring
Type of ID number. Valid values are ssn, social_insurance (e.g. UK National Insurance), tax_id, identity_card and driving_licence.
valuestring
Value of ID number. ssn supports both the full SSN or the last 4 digits. If the full SSN is provided then it must be in the format xxx-xx-xxxx.
state_codestring
Two letter code of issuing state (state-issued driving licences only).

The type in the id_numbers array uses the spelling "driving_license". The type for the Document resource in the API uses the spelling "driving_licence".

Addresses object

The addresses array of objects is nested inside the applicant object.

AttributeDescription
flat_numberstring
The flat number.
building_numberstring
The building number.
building_namestring
The building name.
streetstring
The street of the applicant's address. There is a 32-character limit on this field for UK addresses.
sub_streetstring
The sub-street.
townstring
The town.
statestring
The address state. US states must use the USPS abbreviation (see also ISO 3166-2:US), for example AK, CA, or TX.
postcodestring
The postcode or ZIP of the applicant's address. For UK postcode, specify the value in the following format: SW4 6EH.
countrystring
The 3-character ISO country code of this address. For example, GBR is the country code for the United Kingdom.
start_datedate
The date the applicant started living at this address in YYYY-MM-DD format.
end_datedate
The date the applicant left this address in YYYY-MM-DD format. If current residence, leave null.
line1string
Line 1 of the address.
line2string
Line 2 of the address.
line3string
Line 3 of the address.

postcode and country are required fields if an address is provided for an applicant. For US addresses, state is also a required field.

Most addresses will contain information such as flat_number. Make sure they are supplied as separate fields, and do not try and fit them all into the street field. Doing so is likely to affect check performance. Alternatively, if you're creating a check with an Identity KYC report on an applicant, you can provide addresses in the form line1, line2 and line3. This data will be automatically cleansed and formatted in the expected address fields.

Forbidden characters

For addresses the following characters are forbidden:

!$%^*=<>

For names the following characters are forbidden:

^!#$%*=<>;{}"

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_license",
      "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"
    }
  ]
}

Create applicant

POST
/v2/applicants/

Using this endpoint in a live context will cause you to send personal data to Onfido. Always make sure you inform your users about this and obtain any necessary permissions. For more information on how Onfido uses personal data, view our Privacy Policy.

Creates a single applicant. Returns an applicant object.

When you create an applicant, some characters are forbidden.

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 minimum required (and recommended) applicant data depends on the type of report requested. For example, for Document reports.

Request body parameters

titleoptional
The applicant's title. Valid values are Mr, Mrs, Miss and Ms.
first_namerequired
The applicant's forename.
last_namerequired
The applicant's surname.
middle_nameoptional
The applicant's middle name(s) or initials.
emailrequired if creating a Standard check
The applicant's email address.
genderoptional The applicant's gender. Valid values are male and female.
doboptional
The applicant's date of birth in YYYY-MM-DD format.
telephoneoptional
The applicant's landline phone number.
mobileoptional
The applicant's mobile phone number.
countryoptional
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_nameoptional
The applicant's mother's maiden name.
previous_last_nameoptional
The applicant's previous surname.
nationalityoptional
The applicant's current nationality. This must be a three-letter ISO code e.g. GBR or USA.
country_of_birthoptional
The applicant's country of birth. This must be a three-letter ISO code e.g. GBR or USA.
town_of_birthoptional
The applicant's town of birth.
id_numbersoptional
A collection of identification numbers belonging to this applicant.
addressesoptional
The address history of the applicant.
Create an applicant
HTTP
Copy
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-31",
  "country": "GBR",
  "addresses": [
    {
      "building_number": "100",
      "street": "Main Street",
      "town": "London",
      "postcode": "SW4 6EH",
      "country": "GBR",
      "start_date": "2013-01-31"
    }
  ]
}

Retrieve applicant

GET
/v2/applicants/{applicant_id}

Retrieves a single applicant. Returns an applicant object.

Retrieve an applicant
HTTP
Copy
GET /v2/applicants/<APPLICANT_ID> HTTP/1.1
Host: api.onfido.com
Authorization: Token token=<YOUR_API_TOKEN>

Update applicant

PUT
/v2/applicants/{applicant_id}

Using this endpoint in a live context will cause you to send personal data to Onfido. Always make sure you inform your users about this and obtain any necessary permissions. For more information on how Onfido uses personal data, view our Privacy Policy.

Updates an applicant's information. Returns the updated applicant object.

  • Partial updates are valid
  • Addresses and ID numbers present will replace existing ones
  • Takes the same request body parameters as creating an applicant
  • Applicant details can be updated between check creations
Update an applicant
HTTP
Copy
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"
}

Delete applicant

DELETE
/v2/applicants/{applicant_id}

Deletes a single applicant. If successful, returns a 204 No Content response.

Sending a deletion request adds the applicant object and all associated documents, photos, videos, checks, reports and analytics data to our deletion queue. The objects will be permanently deleted from Onfido's production object storage and relational database system, after a deletion delay which can be configured by emailing our client support team.

After deletion, applicant details cannot be recovered or queried, and Onfido will not be able to troubleshoot. Within the delay period, the applicant can be restored. For more information about Onfido's deletion service, see our Data Deletion FAQ.

Delete an applicant
HTTP
Copy
DELETE /v2/applicants/<APPLICANT_ID> HTTP/1.1
Host: api.onfido.com
Authorization: Token token=<YOUR_API_TOKEN>

Restore applicant

POST
/v2/applicants/{applicant_id}/restore

Restores a single applicant scheduled for deletion. If successful, returns a 204 No Content response.

A restore request will also restore all associated documents, photos, videos, checks, reports and analytics data.

Applicants that have been permanently deleted cannot be restored.

Restore an applicant
HTTP
Copy
POST /v2/applicants/<APPLICANT_ID>/restore HTTP/1.1
Host: api.onfido.com
Authorization: Token token=<YOUR_API_TOKEN>

List applicants

GET
/v2/applicants/

Lists all applicants you've created, sorted by creation date in descending order. Returns data in the form: {"applicants": [<LIST_OF_APPLICANT_OBJECTS>]}.

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:

NameLink relation (description)
nextNext page of results.
lastLast page of results.
firstFirst page of results.
prevPrevious page of results.

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

Return all applicants you've created
HTTP
Copy
GET /v2/applicants?page=1&per_page=5 HTTP/1.1
Host: api.onfido.com
Authorization: Token token=<YOUR_API_TOKEN>

Documents

Some reports require uploaded identity documents in order to be processed successfully.

Depending on the type of the document, we may require both sides of the image to be uploaded. See the full list of documents we support.

Documents belong to a single applicant, so they must be uploaded after an applicant has been created.

The API uses the British English spelling driving_licence.

Document object

AttributeDescription
idstring
The unique identifier of the document.
created_atdatetime
The date and time at which the document was uploaded.
hrefstring
The URI of this resource.
download_hrefstring
The URI that can be used to download the document.
file_namestring
The name of the uploaded file.
file_typestring
The file type of the uploaded file.
file_sizeinteger
The size of the file in bytes.
typestring
The type of document.
sidestring
The side of the document, if applicable. The possible values are front and back.
issuing_countrystring
The issuing country of the document, in 3-letter ISO code, specified when uploading it.
applicant_idstring
The id of the applicant to whom the document belongs.
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"
}

Document types

Identity documents

The following is a partial list of document types (i.e. type when uploading a document):

Type
national_identity_card
driving_licence
passport
voter_id
work_permit

This list is not exhaustive.

If you're unsure of the type of document you want to verify, you can submit documents with type unknown. In this case, we will attempt to classify and recognize the document type when processing a Document report.

Upload document

POST
/v2/applicants/{applicant_id}/documents/

Using this endpoint in a live context will cause you to send personal data to Onfido. Always make sure you inform your users about this and obtain any necessary permissions. For more information on how Onfido uses personal data, view our Privacy Policy.

Uploads a single document as part of a multipart request. Returns a document object.

We provide a sample document to test this endpoint.

Valid file formats for documents are jpg, png and pdf. The file size must be between 32KB and 10MB.

Supply side when uploading documents for optimal results.

Request body parameters

filerequired
The file to be uploaded.
typerequired
The type of document. For example, passport.
sideoptional
Either the front or back of the document.
issuing_countryoptional
The issuing country of the document in 3-letter ISO code.
Upload "passport.png"
HTTP
Copy
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)>

Retrieve document

GET
/v2/applicants/{applicant_id}/documents/{document_id}

Retrieves a single document. Returns a document object.

Retrieve a document for a specific applicant
HTTP
Copy
GET /v2/applicants/<APPLICANT_ID>/documents/<DOCUMENT_ID> HTTP/1.1
Host: api.onfido.com
Authorization: Token token=<YOUR_API_TOKEN>

List documents

GET
/v2/applicants/{applicant_id}/documents/

Lists all documents belonging to an applicant. Returns data in the form: {"documents": [<LIST_OF_DOCUMENT_OBJECTS>]}.

Query string parameters

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

List all documents for a specific applicant
HTTP
Copy
GET /v2/applicants/<APPLICANT_ID>/documents HTTP/1.1
Host: api.onfido.com
Authorization: Token token=<YOUR_API_TOKEN>

Download document

GET
/v2/applicants/{applicant_id}/documents/{document_id}/download

Downloads specific documents belong to an applicant. If successful, the response will be the binary data representing the image.

Download a document associated with an applicant
HTTP
Copy
GET /v2/applicant/<APPLICANT_ID>/documents/<DOCUMENT_ID>/download HTTP/1.1
Host: api.onfido.com
Authorization: Token token=<YOUR_API_TOKEN>

Live photos

Live photos are images of the applicant's face, typically taken at the same time as documents are provided. Some reports require uploaded live photos in order to be processed successfully.

Live photo object

AttributeDescription
idstring
The unique identifier of the live photo.
created_atdatetime
The date and time at which the live photo was uploaded.
hrefstring
The URI of this resource.
download_hrefstring
The URI that can be used to download the live photo.
file_namestring
The name of the uploaded file.
file_typestring
The file type of the uploaded file.
file_sizeinteger
The size of the file in bytes.
HTTP/1.1 201 Created
Content-Type: application/json

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

Upload live photo

POST
/v2/live_photos/

Using this endpoint in a live context will cause you to send personal data to Onfido. Always make sure you inform your users about this and obtain any necessary permissions. For more information on how Onfido uses personal data, view our Privacy Policy.

Uploads a live photo as part of a multipart request. Returns a live photo object.

We provide a sample photo to test this endpoint.

Valid file formats for live photos 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.

Request body parameters

filerequired
The file to be uploaded.
applicant_idrequired
The applicant_id to associate the live photo with.
advanced_validationoptional
A Boolean which defaults to true
Validates that the live photo contains exactly one face.
Upload "sample_photo.png"
HTTP
Copy
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)>

Retrieve live photo

GET
/v2/live_photos/{live_photo_id}

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

Retrieve a single live photo's object
HTTP
Copy
GET /v2/live_photos/<LIVE_PHOTO_ID> HTTP/1.1
Host: api.onfido.com
Authorization: Token token=<YOUR_API_TOKEN>

List live photos

GET
/v2/live_photos/

Lists the live photos that belong to an applicant. Returns data in the form: {"live_photos": [<LIST_OF_LIVE_PHOTO_OBJECTS>]}.

Query string parameters

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

List all live photo (objects) for a specific applicant
HTTP
Copy
GET /v2/live_photos/live_photos?applicant_id=<APPLICANT_ID> HTTP/1.1
Host: api.onfido.com
Authorization: Token token=<YOUR_API_TOKEN>

Download live photo

GET
/v2/live_photos/{live_photo_id}/download

Downloads a live photo. If successful, the response will be the binary data representing the image.

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

Live videos

Live videos are footage of the applicant's face, recorded and uploaded by the Onfido input-capture SDKs (iOS, Android or Web), at the same time as the document image is captured—also by the SDKs. These videos are used to perform the video variant of the Facial Similarity check on the applicant.

Live video object

During the video recording end users are asked to perform randomly generated actions, represented in challenge. Challenges always have 2 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 3 randomly generated digits, whereas movement asks the user to look over their right or left shoulder.

AttributeDescription
idstring
The unique identifier of the live video.
created_atdatetime
The date and time at which the live video was uploaded.
hrefstring
The URI of this resource.
download_hrefstring
The URI that can be used to download the live video.
file_namestring
The name of the uploaded file.
file_typestring
The file type of the uploaded file.
file_sizeinteger
The size of the file in bytes.
challengearray of objects
Challenge the end user was asked to perform during the video recording.
HTTP/1.1 201 Created
Content-Type: application/json

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

Retrieve live video

GET
/v2/live_videos/{live_video_id}

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

Retrieve a single live video's object
HTTP
Copy
GET /v2/live_videos/<LIVE_VIDEO_ID> HTTP/1.1
Host: api.onfido.com
Authorization: Token token=<YOUR_API_TOKEN>

List live videos

GET
/v2/live_videos/

Lists all the live videos that belong to an applicant.

Returns data in the form: {"live_videos": [<LIST_OF_LIVE_VIDEO_OBJECTS>]}.

Query string parameters

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

List all live videos for a specific applicant
HTTP
Copy
GET /v2/live_videos?applicant_id=<APPLICANT_ID> HTTP/1.1
Host: api.onfido.com
Authorization: Token token=<YOUR_API_TOKEN>

Download live video

GET
/v2/live_videos/{live_video_id}/download

Downloads a live video. Returns the binary data representing the video.

Download the data representing a live video
HTTP
Copy
GET /v2/live_videos/<LIVE_VIDEO_ID>/download HTTP/1.1
Host: api.onfido.com
Authorization: Token token=<YOUR_API_TOKEN>

Download live video frame

GET
/v2/live_videos/{live_video_id}/frame

Instead of the whole video, a single frame can be downloaded using this endpoint. Returns the binary data representing the frame.

For best results, you should use this endpoint only after the corresponding Facial Similarity video variant report report has completed.

Download the data representing a live video frame
HTTP
Copy
GET /v2/live_videos/<LIVE_VIDEO_ID>/frame HTTP/1.1
Host: api.onfido.com
Authorization: Token token=<YOUR_API_TOKEN>

Unsuccessful frame extraction

Frame extraction failed

If a frame cannot be extracted from the live video, a frame_extraction_failed response will be returned.

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

{
  "error": {
    "type": "frame_extraction_failed",
    "message": "<Reason>"
  }
}

Frame extraction unavailable

If the extraction feature is temporarily unavailable, a frame_extraction_unavailable response will be returned instead.

HTTP/1.1 503 Service Unavailable
Content-Type: application/json

{
  "error": {
    "type": "frame_extraction_unavailable",
    "message": "Frame extraction is temporarily unavailable"
  }
}

Checks

Checks are performed on an applicant and consist of one or more reports.

Check object

AttributeDescription
idstring
The unique identifier for the check.
created_atdatetime
The date and time at which the check was initiated.
hrefstring
The API endpoint to retrieve the check.
typestring
The type of check (standard or express).
statusstring
The current state of the check in the checking process.
tagsarray of strings
A list of tags associated with this check.
resultstring
The overall result of the check, based on the results of the reports used in the check.
download_uristring
A link to a PDF output of the check results. Append .pdf to get the PDF file.
form_uristring
A link to the applicant form, if the check is of type standard.
redirect_uristring
For Standard checks, redirect to this URI when the applicant has submitted their data.
results_uristring
A link to the corresponding results page on the Onfido Dashboard.
reportsarray of strings (expandable to array of objects)
By default, an array of strings of report IDs associated with the check. If expanded when retrieving a check or listing a check, returns an array of report objects associated with the check(s).

Check status

StatusDescription
in_progressWe are currently processing the check.
awaiting_applicantThe 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.
completeAll reports for the applicant have been completed or withdrawn.
withdrawnThe check has been withdrawn.
pausedThe check is paused until you (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.
reopenedInsufficient or inconsistent information was provided by the applicant, and the report has been bounced back for further information.
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": "<RESULTS_URI>",
  "download_uri": "<DOWNLOAD_URI>",
  "reports": [
    "<REPORT_ID>",
    "<REPORT_ID>"
  ],
  "tags": [
    "My tag",
    "Another tag"
  ]
}

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.

Check results

The value of the check is derived from the results of the individual reports that it contains:

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

Create check

POST
/v2/applicants/{applicant_id}/checks/

Using this endpoint in a live context will cause you to create a check using an applicant's personal data. Always make sure you inform your users about this and obtain any necessary permissions. For more information on how Onfido uses personal data, view our Privacy Policy.

Initiates a check for an applicant, which can contain one or more reports. Returns a check object.

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.

Request body parameters

Either reports or report_type_groups must be specified when creating a check.

typerequired
standard or express. See “Checks”.
reportsrequired if report_type_groups not provided
Array of reports being requested for this check.
report_type_groupsrequired if reports not provided
Array containing ids of the report type groups being requested for.
redirect_urioptional
For Standard checks, redirect to this URI when the applicant has submitted their data.
tagsoptional
Array of tags being assigned to this check.
suppress_form_emailsoptional
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, checks will be queued for processing. You can configure webhooks to notify you when the report is complete.
Defaults to false
Note: async and asynchronous cannot be provided together.
consideroptional
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)

namerequired
The name of the report type. You can read about the different report types.
variantoptional
The name of the report type variant, if required.
optionsoptional
Array of report options objects.
documentsoptional
Array of report documents objects. 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)

namerequired
The option to be applied (used by Watchlist Full reports).

Request body parameters (report documents)

idrequired
ID of uploaded document to use.
Create a check (Document report, Facial Similarity report)
HTTP
Copy
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"
    }
  ]
}

Retrieve check

GET
/v2/applicants/{applicant_id}/checks/{check_id}

Retrieves a single check. Returns a check object.

You can expand the reports value to return an array of the report objects in the response instead of the default array of strings of report IDs.

Retrieve a single check
HTTP
Copy
GET /v2/applicants/<APPLICANT_ID>/checks/<CHECK_ID> HTTP/1.1
Host: api.onfido.com
Authorization: Token token=<YOUR_API_TOKEN>

List checks

GET
/v2/applicants/{applicant_id}/checks/

Returns all checks for an applicant. Returns data in the form: {"checks": [<LIST_OF_CHECK_OBJECTS>]}.

You can expand the reports value to return an array of the report objects in the response instead of the default array of strings of report IDs.

Query string parameters

expand=reports (Optional)

List all checks associated with an applicant
HTTP
Copy
GET /v2/applicants/<APPLICANT_ID>/checks/ HTTP/1.1
Host: api.onfido.com
Authorization: Token token=<YOUR_API_TOKEN>

Resume check

POST
/v2/checks/{check_id}/resume

Resumes a paused check. If successful, returns a 204 No Content response.

A check is paused if all the reports that it contains are in the paused state.

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

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

Reports

In the Onfido API, checks are composed of one or more reports.

Report object

The report object will differ depending on which report it concerns (see "About reports" above).

AttributeDescription
idstring
The unique identifier for the report.
created_atdatetime
The date and time at which the report was first initiated.
namestring
Report type string identifier.
hrefstring
The API endpoint to retrieve the report.
statusstring
The current state of the report in the checking process.
resultstring
The result of the report.
sub_resultstring
The sub_result of the report. It gives a more detailed result for Document reports only, and will be null otherwise.
variantstring
Report variant string identifier. Some reports have sub-types, which are identified by this field.
optionsarray
Report options usable with Watchlist Full reports.
breakdownobject
The details of the report. This is specific to each type of report.
propertiesobject
The properties associated with the report, if any.
documentsarray
The document ids that were processed. Populated for Document reports, otherwise an empty array.

The breakdown object differs for each report type. For example, for Document reports.

Report status

StatusDescription
awaiting_dataOnfido has made a request to one of its data providers and we are waiting on their reply.
awaiting_approvalReport is going through manual review.
completeReport is done.
withdrawnReport has been cancelled.
pausedReport 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.

Report results

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

Report result
clearIf all underlying verifications pass, the overall result will be clear.
considerIf the report has returned information that needs to be evaluated, the overall result will be consider.
unidentifiedIdentity 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.

Sub results (Document reports)

The sub_result field indicates a more detailed result and is unique to Document reports.

Report sub_result
clearIf all underlying verifications pass, the overall sub result will be clear.
rejectedIf the report has returned information where the check cannot be processed further (poor quality image or an unsupported document).
suspectedIf the document that is analysed is suspected to be fraudulent.
cautionIf 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

GET
/v2/checks/{check_id}/reports/{report_id}

Retrieves a single report. Returns a report object.

Retrieve a single report
HTTP
Copy
GET /v2/checks/<CHECK_ID>/reports/<REPORT_ID> HTTP/1.1
Host: api.onfido.com
Authorization: Token token=<YOUR_API_TOKEN>

List reports

GET
/v2/checks/{check_id}/reports/

Lists all reports belonging to a particular check. Returns data in the form: {"reports": [<LIST_OF_REPORT_OBJECTS>]}.

List all reports associated with a check
HTTP
Copy
GET /v2/checks/<CHECK_ID>/reports/ HTTP/1.1
Host: api.onfido.com
Authorization: Token token=<YOUR_API_TOKEN>

Resume report

POST
/v2/checks/{check_id}/reports/{report_id}/resume

Resumes a single paused report. If successful, returns a 204 No Content response.

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.

Resume a single paused report
HTTP
Copy
POST /v2/checks/<CHECK_ID>/reports/<REPORT_ID>/resume HTTP/1.1
Host: api.onfido.com
Authorization: Token token=<YOUR_API_TOKEN>

Cancel report

POST
/v2/checks/{check_id}/reports/{report_id}/cancel

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.

Cancel a single paused report
HTTP
Copy
POST /v2/checks/<CHECK_ID>/reports/<REPORT_ID>/cancel HTTP/1.1
Host: api.onfido.com
Authorization: Token token=<YOUR_API_TOKEN>

Report Types

Document report

For a general introduction to the Document report, you may wish to read our product documentation.

After you've familiarised yourself with the information here, you may also wish to read our guide on suggested client actions for different result scenarios.

By default, the most recently uploaded document will be used.

The Document report is composed of data integrity, visual authenticity and police record checks. It checks the internal and external consistency of the 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).

Required applicant data

For Document reports, first_name and last_name must be provided but can be dummy values if you don't know an applicant's name.

Document type and issuing country

If you’re creating a check containing a Document report, we do not validate that the properties type and issuing_country in the uploaded document match extracted values (which are returned in the Document report object).

ReportNameVariantsStandard checkExpress check
Document reportdocument-yesyes

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

Document report: Object

We host a separate page which contains a detailed description of the Document report object.

Results

The result field indicates the overall report result. Possible values for Document reports are clear and consider:

Report result
clearIf all underlying verifications pass, the overall result will be clear
considerIf the report has returned information that needs to be evaluated, the overall result will be consider.

Sub-results

The sub_result field indicates a more detailed result. sub_result is only applicable to Document reports. Possible values are as follows:

Sub-result
clearIf all underlying verifications pass, the overall sub result will be clear. There are no indications the document is fraudulent.
cautionWe can't successfully complete all verifications, but this doesn’t necessarily point to a suspected document (for example, expired document).
suspectedDocument shows signs of suspect fraud.
rejectedWe can't process the document image, or the document isn't supported by Onfido for processing. Another reason is if the age of the applicant is too low (the standard threshold is 16 years old but you can write to your Onfido contact to have this changed).

Document report: Breakdowns

Breakdowns can have the values clear and consider.

A breakdown will have the result consider when at least one sub-breakdown contains a consider or unidentified result. For example, a consider result for the mrz sub-breakdown will produce a consider result for the data_validation breakdown. This will then also set the report sub_result value to suspected.

Some breakdowns contain sub-breakdowns. For example, the image_integrity breakdown comprises the sub-breakdowns supported_document, image_quality, colour_picture and conclusive_document_quality.

The possible values for sub-breakdowns are clear, consider, null and unidentified.

Breakdown order priority

Breakdown sub-results have the following order of priority:

rejected->suspected->caution->clear

For example, a caution sub-result will only ever be asserted when the following conditions are met:

  • no individual breakdown has caused a rejected or suspected sub-result
  • a breakdown which maps to a caution sub-result has been flagged

Breakdown descriptions and logic

  • police_record:

    Asserts whether the document has been identified as lost, stolen or otherwise compromised.

  • compromised_document:

    Asserts whether the image of the document has been found in our internal database of compromised documents.

  • data_consistency:

    Asserts whether data represented in multiple places on the document is consistent. For example, between MRZ lines and OCR extracted text on passports. Uses the following sub-breakdowns:

    • document_type
    • gender
    • date_of_expiry
    • nationality
    • issuing_country
    • document_numbers
    • date_of_birth
    • last_name
    • first_name
  • data_validation:

    Asserts whether algorithmically validatable elements are correct. Uses the following sub-breakdowns:

    • document_expiration
    • gender
    • document_numbers
    • expiry_date
    • date_of_birth
    • mrz
  • visual_authenticity:

    Asserts whether visual (non-textual) elements are correct given the document type. Uses the following sub-breakdowns:

    • original_document_present:

      The document was not present when the photo was taken. For example, a photo of a photo of a document or a photo of a computer screen. Configurable to map to caution instead of suspected.

    • digital_tampering:

      Indication of digital tampering in the image (for example, name altered).

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

    • security_features:

      Security features expected on the document are missing or wrong.

    • template:

      The document doesn’t match the expected template for the document type and country it is from.

    • fonts:

      Fonts in the document don’t match the expected ones.

    • face_detection:

      No face was detected on the document.

    • other:

      This sub-breakdown is returned for backward compatibility reasons. Its value will be consider when at least one of the other breakdowns is consider, and clear when all the other breakdowns are clear.

  • image_integrity:

    Asserts whether the document was of sufficient quality to verify. Uses the following sub-breakdowns:

    • colour_picture:

      Asserts whether the image was a colour one. A black and white picture will map to a caution Document report sub-result. Configurable to map to rejected.

    • conclusive_document_quality:

      A result of clear for this sub-breakdown 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).

    • supported_document:

      Asserts whether the submitted document is supported. Takes value of clear or unidentified.

    • image_quality:

      Asserts whether the quality of the image was sufficient for processing.

  • data_comparison:

    Asserts whether data on the document is consistent with data provided when creating an applicant through the API. The White String Similarity Algorithm is used on the name fields. The algorithm produces a value between 0 and 1 based on how close a name is to another. Data comparison will fail if the value produced does not exceed our 0.8 threshold value. The match score is not returned. The purpose of this inexact matching is to avoid unnecessary failures if the names are mathematically close enough. Special characters in the name fields are transliterated by the algorithm, i.e. Ã becomes A. Configurable to allow for the process of special characters.

    This breakdown can be switched off if needed. The following sub-breakdowns are used:

    • gender
    • date_of_birth
    • first_name
    • last_name
  • age_validation:

    Asserts whether the age calculated from the document’s date of birth data point is greater than or equal the minimum accepted age set at account level. The standard threshold is 16 years old but you can write to your Onfido contact to have this changed.

Breakdown properties

We will return a reason whenever a report flags for one of the following breakdowns:

  • Image Integrity - Image Quality

  • Image Integrity - Conclusive Document Quality

  • Visual Authenticity - Original Document Present

This works by returning the contributing reason and corresponding fail result (a Consider result) in the breakdown properties.

There can be more than one reason per breakdown, as they aren’t mutually exclusive.

All other signals and potential reasons will be omitted.

Image Quality reasons:

dark_photo - When an image of the document is too dark to be able to see data points

glare_on_photo - When there is light reflecting on the document causing glare to obstruct data points

blurred_photo - When data points are blurred and no reference can be made elsewhere in the document or if the data points are too blurry and 'they could be something else' (e.g. "I" could be "1", "B" could be "8")

covered_photo - When data points have been covered either by the applicant or by another object such as a sticker

other_photo_issue - Any other reason not listed, such as when holograms are obscuring data points

damaged_document - When a document is damaged and we are unable to make out data points

incorrect_side - When the incorrect side of a document has been uploaded, and we have not received the front

cut_off_document - When data points are not included in the image due to the document being cut off (i.e. out of the frame of the image)

no_document_in_image - If no document has been uploaded or there is a blank image

two_documents_uploaded - When two different identity documents are submitted in the same check

Conclusive Document Quality reasons:

obscured_data_points - This refers to whenever any personal data points that aren’t meant to be extracted are obscured, e.g.: Address, Place of Birth, Nationality, Signature, Personal Number, Issue Date (when not extracted), Expiry date (when not extracted)

obscured_security_features - This refers to whenever a critical security feature is obscured. This can also refer to when the holder's wet signature, necessary for the document to be valid, is not present

abnormal_document_features - One of three reasons: (1) OCR Assisted Scans (i.e. when you're able to move the mouse and highlight part of text), (2) Severely Washed out Background, (3) Overlapping Text

watermarks_digital_text_overlay - Any digital text or electronic watermarks on the document

corner_removed - If the corner has been physically cut off. This can be found on some documents that are no longer valid

punctured_document - A punched hole is present. This can be found on DLs that are no longer valid, for example

missing_back - When the back of a document is needed for processing (e.g. for key data points to extract, or to perform Consistency), but is not available (e.g. if the same front was uploaded twice)

digital_document - When a document has been published digitally, there aren’t enough security features to review so we cannot perform a full fraud assessment

Original Document Present reasons:

photo_of_screen - When we can see that the applicant's document is on a physical screen or device, e.g. when the device is visible, software applications are seen, a computer cursor is present, or the pixels on the image appearing to have a different texture than expected

screenshot - When the applicant has used their mobile phone, tablet, or computer to take a photo within the device, e.g. when software applications are seen, the time and mobile provider are visible, or any digitally added component that wouldn't be seen on a physical document, such as an upload icon

document_on_printed_paper - when the applicant has previously captured an image of the document, printed it out, and has now taken a photo of this print out to upload, e.g. when the edges of the paper are visible, when there are fold creases on the paper, or the document's edges blending into the background and appearing flat

scan - When the document has clearly been captured using a scanner and there are visible indicators of this, e.g. unusual shadows on the edges of the document, or written text around the document

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

{
  "id": "<CHECK_ID>",
  "created_at": "2019-07-29T15:14:29Z",
  "status": "complete",
  "redirect_uri": null,
  "type": "express",
  "result": "clear",
  "sandbox": true,
  "tags": [],
  "results_uri": "<RESULTS_URI>",
  "download_uri": "<DOWNLOAD_URI>",
  "form_uri": null,
  "reports": [
    {
      "created_at": "2019-07-29T15:14:30Z",
      "documents": [
        {
          "id": "<DOCUMENT_ID>"
        }
      ],
      "href": "/v2/checks/<CHECK_ID>/reports/<REPORT_ID>",
      "id": "<REPORT_ID>",
      "name": "document",
      "properties": {
        "nationality": "",
        "last_name": "Smith",
        "issuing_country": "GBR",
        "gender": "",
        "first_name": "John",
        "document_type": "passport",
        "document_numbers": [
          {
            "value": "999999999",
            "type": "document_number"
          }
        ],
        "date_of_expiry": "2030-01-01",
        "date_of_birth": "1990-01-01"
      },
      "result": "clear",
      "status": "complete",
      "sub_result": "clear",
      "variant": "standard",
      "breakdown": {
        "age_validation": {
          "result": "clear",
          "breakdown": {
            "minimum_accepted_age": {
              "result": "clear",
              "properties": {}
            }
          }
        },
        "compromised_document": {
          "result": "clear"
        },
        "data_comparison": {
          "result": "clear",
          "breakdown": {
            "issuing_country": {
              "result": "clear",
              "properties": {}
            },
            "gender": {
              "result": "clear",
              "properties": {}
            },
            "date_of_expiry": {
              "result": "clear",
              "properties": {}
            },
            "last_name": {
              "result": "clear",
              "properties": {}
            },
            "document_type": {
              "result": "clear",
              "properties": {}
            },
            "document_numbers": {
              "result": "clear",
              "properties": {}
            },
            "first_name": {
              "result": "clear",
              "properties": {}
            },
            "date_of_birth": {
              "result": "clear",
              "properties": {}
            }
          }
        },
        "data_consistency": {
          "result": "clear",
          "breakdown": {
            "date_of_expiry": {
              "result": "clear",
              "properties": {}
            },
            "document_numbers": {
              "result": "clear",
              "properties": {}
            },
            "issuing_country": {
              "result": "clear",
              "properties": {}
            },
            "document_type": {
              "result": "clear",
              "properties": {}
            },
            "date_of_birth": {
              "result": "clear",
              "properties": {}
            },
            "gender": {
              "result": "clear",
              "properties": {}
            },
            "first_name": {
              "result": "clear",
              "properties": {}
            },
            "last_name": {
              "result": "clear",
              "properties": {}
            },
            "nationality": {
              "result": "clear",
              "properties": {}
            }
          }
        },
        "data_validation": {
          "result": "clear",
          "breakdown": {
            "gender": {
              "result": "clear",
              "properties": {}
            },
            "date_of_birth": {
              "result": "clear",
              "properties": {}
            },
            "document_numbers": {
              "result": "clear",
              "properties": {}
            },
            "document_expiration": {
              "result": "clear",
              "properties": {}
            },
            "expiry_date": {
              "result": "clear",
              "properties": {}
            },
            "mrz": {
              "result": "clear",
              "properties": {}
            }
          }
        },
        "visual_authenticity": {
          "result": "clear",
          "breakdown": {
            "fonts": {
              "result": "clear",
              "properties": {}
            },
            "picture_face_integrity": {
              "result": "clear",
              "properties": {}
            },
            "template": {
              "result": "clear",
              "properties": {}
            },
            "security_features": {
              "result": "clear",
              "properties": {}
            },
            "original_document_present": {
              "result": "clear",
              "properties": {
                "photo_of_screen": "consider"
              }
            },
            "digital_tampering": {
              "result": "clear",
              "properties": {}
            },
            "other": {
              "result": "clear",
              "properties": {}
            },
            "face_detection": {
              "result": "clear",
              "properties": {}
            }
          }
        },
        "image_integrity": {
          "result": "clear",
          "breakdown": {
            "image_quality": {
              "result": "clear",
              "properties": {
                "glare_on_photo": "consider",
                "blurred_photo": "consider"
              }
            },
            "conclusive_document_quality": {
              "result": "clear",
              "properties": {
                "obscured_security_features": "consider"
              }
            },
            "supported_document": {
              "result": "clear",
              "properties": {}
            },
            "colour_picture": {
              "result": "clear",
              "properties": {}
            }
          }
        },
        "police_record": {
          "result": "clear"
        }
      }
    }
  ],
  "paused": false,
  "report_type_groups": [
    "<REPORT_TYPE_GROUP_ID>"
  ],
  "href": "/v2/applicants/<APPLICANT_ID>/checks/<CHECK_ID>",
  "version": "2.0"
}

Breakdowns which map to caution

  • image_integrity

    • colour_picture (configurable to map to rejected)

    • conclusive_document_quality

  • data_comparison:

    • gender

    • date_of_birth

    • first_name

    • last_name

  • data_validation:

    • document_expiration
  • visual_authenticity:

    • face_detection

Breakdowns which map to suspected

  • data_validation:

    • date_of_birth

    • expiry_date

    • mrz

    • gender

    • document_numbers

  • visual_authenticity:

    • original_document_present (configurable to map to caution)

    • digital_tampering

    • picture_face_integrity

    • security_features

    • template

    • fonts

  • data_consistency:

    • date_of_expiry

    • document_type

    • gender

    • date_of_birth

    • nationality

    • issuing_country

    • document_numbers

    • first_name

    • last_name

  • compromised_document: Document has been found in our database

  • police_record: Document has been recorded as lost, stolen or compromised

Breakdowns which map to rejected

  • image_integrity:

    • image_quality

    • supported_document

  • age_comparison:

    • minimum_accepted_age

Example client actions

We've moved this content.

Facial Similarity report

ReportNameVariantsStandard checkExpress check
Facial Similarity reportfacial_similaritystandard
video
yes
no
yes
yes

Creating a check with a Facial Similarity report will cause you to process facial biometric personal data. Always make sure you inform your users about this and obtain any necessary permissions. For more information on how Onfido uses personal data, view our Privacy Policy.

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 2 different variants of Facial Similarity report:

Required applicant data

For all Facial Similarity report variants, first_name and last_name must be provided but can be dummy values if you don't know an applicant's name.

Facial Similarity Standard

The Facial Similarity Standard report needs to be paired with a Document report in order to work as a Standard check.

The Facial Similarity Standard report 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.

Facial Similarity Standard: Object

The following table describes the unique fields returned in the Onfido API (v2) for a completed Facial Similarity Standard report:

AttributeFormatPossible values
resultString"clear", "consider"
image_integrityString or null"clear", "consider", null
(sub-breakdown) face_detectedString or null"clear", "consider", null
(sub-breakdown) source_integrityString or null"clear", "consider", null
face_comparisonString or null"clear", "consider", null
visual_authenticityString or null"clear", "consider", null
properties
        scoreFloating point number between 0 and 1

Facial Similarity Standard: Breakdowns

image_integrityobject
Asserts whether the quality and integrity of the uploaded files were sufficient to perform a face comparison
(sub-breakdown) face_detectedobject
Asserts a single face of good enough quality has been found on both the document image and the live photo
(sub-breakdown) source_integrityobject
Asserts whether the live photo is trustworthy - i.e. not digitally tampered, from a fake webcam, or from other dubious sources
face_comparisonobject
Asserts whether the face in the document matches the face in the live photo
visual_authenticityobject
Asserts whether the person in the live photo is real (not a spoof)

We will return a reason whenever a report flags for source_integrity. This works by returning the contributing reason and a consider result in the source_integrity breakdown properties. There can be more than one reason, because they aren’t mutually exclusive. All other signals and potential reasons will be omitted.

For Facial Similarity Standard, the source_integrity sub-breakdown is composed of the following properties:

  • digital_tampering - when evidence is found that the image was manipulated by Photoshop, or other software
  • fake_webcam - when evidence is found that a fake webcam was used
  • time_of_capture - when evidence is found that the live photo was taken more than 24 hours before live photo upload
  • emulator - when evidence is found that an Android emulator was used
  • reasons - additional comma separated details such as the exact digital tampering software used, or the name of the fake webcam

Facial Similarity Standard: 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. If tampering is detected, the applicant will be rejected independently of the score. Examples of tampering are photos of printed photos, or photos of digital screens.

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

{
  "id": "<CHECK_ID>",
  "created_at": "2019-09-24T14:11:05Z",
  "status": "complete",
  "redirect_uri": null,
  "result": "consider",
  "sandbox": true,
  "tags": [],
  "results_uri": "<RESULTS_URI>",
  "form_uri": null,
  "reports": [
    {
      "created_at": "2019-09-24T14:11:05Z",
      "href": "/v2/checks/<CHECK_ID>/reports/<REPORT_ID>",
      "id": "<REPORT_ID>",
      "name": "facial_similarity",
      "properties": {
        "score": 0.1512
      },
      "result": "consider",
      "status": "complete",
      "sub_result": null,
      "variant": "standard",
      "documents": [],
      "breakdown": {
        "face_comparison": {
          "result": "consider"
        },
        "image_integrity": {
          "result": "clear",
            "breakdown": {
              "face_detected": {
                 "result": "clear",
                 "properties": {}
              },
              "source_integrity": {
                "result": "clear",
                "properties": {}
              }
            }
        },
        "visual_authenticity": {
          "result": "consider"
        }
      }
    }
  ],
  "paused": false,
  "type": "express",
  "report_type_groups": [
    "<REPORT_TYPE_GROUP_ID>"
  ],
  "download_uri": "<DOWNLOAD_URI>",
  "href": "/v2/applicants/<APPLICANT_ID>/checks/<CHECK_ID>",
  "version": "2.0"
}

Facial Similarity Video

In the Video variant of the Facial Similarity report, live videos are collected and uploaded by the Onfido iOS, Android or JS SDKs.

In addition to confirming the two faces match, Facial Similarity Video assesses liveness by asking users to repeat randomly generated numbers and perform a random head movement. This prevents impersonation - for example photos of photos, or photos of screens. This process is reflected in visual_authenticity, which is composed of the sub-breakdowns spoofing_detection and liveness_detected. See the sections Facial Similarity Video Object and Facial Similarity Video Breakdowns.

In order for a Facial Similarity Video report to complete automatically, the user needs to turn their head in the correct direction and correctly say the 3 randomly generated digits in one of our supported languages (see table below).

Language nameLanguage code
English"en"
Spanish"es"
Indonesian"id"
Italian"it"
German"de"
French"fr"
Portuguese"pt"
Polish"pl"
Japanese"ja"
Dutch"nl"
Romanian"ro"
Basque"eu"
Catalan"ca"
Galician"gl"

If the user does not say the correct digits, or speak in another language, the live video will be reviewed by an analyst for evidence of spoofing.

SDK localization

We recommend that you localize the strings if you're using one of the Onfido SDKs, so the user is more likely to understand the liveness headturn and speaking instructions.

The Onfido voice processor will attempt to detect the language the user is speaking. This will be more successful if you pass the code for the expected language to the locale mechanism, in any of the Onfido SDKs:

Some string localisations are available out of the box, but this differs depending on the SDK.

You can also provide your own custom translations to your users.

Facial Similarity Video: Object

The following table describes the unique fields returned in the Onfido API (v2) for a completed Facial Similarity Video report:

AttributeFormatPossible values
resultString"clear", "consider"
image_integrityString or null"clear", "consider", null
(sub-breakdown) face_detectedString or null"clear", "consider", null
(sub-breakdown) source_integrityString or null"clear", "consider", null
face_comparisonString or null"clear", "consider", null
visual_authenticityString or null"clear", "consider", null
(sub-breakdown) spoofing_detectionString or null"clear", "consider", null
(sub-breakdown) liveness_detectedString or null"clear", "consider", null
properties
        scoreFloating point number between 0 and 1, or null

Facial Similarity Video: Breakdowns

face_comparisonobject
Asserts whether the face in the document matches the face in the live video
image_integrityobject
Asserts whether the quality of the uploaded files and the content contained within them were sufficient to perform a face comparison
(sub-breakdown) face_detectedobject
Asserts a single face of good enough quality has been found on both the document image and in the live video
(sub-breakdown) source_integrityobject
Asserts whether the live video is trustworthy - e.g. not from a fake webcam
visual_authenticityobject
Asserts whether the person in the live video is real (not a spoof) and live
(sub-breakdown) spoofing_detectionobject
Asserts whether the live video is not a spoof (such as videos of digital screens)
(sub-breakdown) liveness_detectedobject
Asserts whether the numbers and head movements were correctly executed

We will return a reason whenever a report flags for source_integrity. This works by returning the contributing reason and a consider result in the source_integrity breakdown properties. There can be more than one reason, because they aren’t mutually exclusive. All other signals and potential reasons will be omitted.

For Facial Similarity Video, the source_integrity sub-breakdown is composed of the following properties:

  • fake_webcam - when evidence is found that a fake webcam was used
  • emulator - when evidence is found that an Android emulator was used
  • challenge_reuse - when evidence is found that the video was uploaded in an attempt to circumvent the randomness of the speaking and head turn challenges
  • reasons - additional comma separated details, such as the name of the fake webcam

Facial Similarity Video: 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 video. If tampering is detected, the applicant will be rejected independently of the score. Examples of tampering are videos of digital screens, videos of masks, videos of print outs.

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

{
  "id": "<CHECK_ID>",
  "created_at": "2019-09-25T11:41:22Z",
  "status": "complete",
  "redirect_uri": null,
  "result": "consider",
  "sandbox": false,
  "tags": [
      "Under 18"
  ],
  "results_uri": "<RESULTS_URI>",
  "form_uri": null,
  "reports": [
      {
          "created_at": "2019-09-25T11:41:22Z",
          "href": "/v2/checks/<CHECK_ID>/reports/<REPORT_ID>",
          "id": "<REPORT_ID>",
          "name": "facial_similarity",
          "properties": {
              "score": 0.1252
          },
          "result": "consider",
          "status": "complete",
          "sub_result": null,
          "variant": "video",
          "documents": [],
          "breakdown": {
              "face_comparison": {
                  "result": "consider"
              },
              "image_integrity": {
                  "result": "consider",
                  "breakdown": {
                      "face_detected": {
                          "result": "clear",
                          "properties": {}
                      },
                      "source_integrity": {
                          "result": "consider",
                          "properties": {
                              "fake_webcam": "consider",
                              "reasons": "Used fake webcam Perfect Fake Webcam"
                          }
                      }
                  }
              },
              "visual_authenticity": {
                  "result": "consider",
                  "breakdown": {
                      "liveness_detected": {
                          "result": "consider",
                          "properties": {}
                      },
                      "spoofing_detection": {
                          "result": null,
                          "properties": {}
                      }
                  }
              }
          }
      }
  ],
  "paused": false,
  "type": "express",
  "report_type_groups": [
      "<REPORT_TYPE_GROUP_ID>"
  ],
  "download_uri": "<DOWNLOAD_URI>",
  "href": "/v2/applicants/<APPLICANT_ID>/checks/<CHECK_ID>",
  "version": "2.0"
}

Known Faces report

This section contains API documentation for the Known Faces report. You can also read our product documentation.

Creating a check with a Known Faces report will create a database of facial biometric identifiers (personal data) so that individuals can be identified in future checks. Always make sure you inform your users about this and obtain any necessary permissions. For more information on how Onfido uses personal data, view our Privacy Policy.

ReportNameVariantsStandard checkExpress check
Known Faces reportknown_faces-yesyes

Each applicant you run a Known Faces report against must have an uploaded live photo or live video.

If no live photo or live video is found, the Known Faces report will be automatically withdrawn and return an error in the report properties:

JSON
Copy
"properties":{
    "reason": "Report withdrawn due to missing media (photo or video) required for processing."
}

You can run Known Faces as a standalone report, but we recommend that you combine it with a Document and Facial Similarity report in the same check.

No matches will be returned against any permanently deleted applicants.

Required applicant data

For Known Face reports, first_name and last_name must be provided but can be dummy values if you don't know an applicant's name.

Known Faces: Object

The following table describes the unique fields returned in the Onfido API (v2) for a completed Known Faces report:

AttributeFormatPossible values
resultString"clear", "consider"
previously_seen_facesString or null"clear", "consider" , null
image_integrityString"clear", "consider"

Known Faces: Breakdowns

previously_seen_facesobject
Asserts whether the applicant's most recent facial media (live photo or live video) matches any other live photos or live videos already in your Onfido account database
image_integrityobject
Asserts whether the uploaded live photo or live video and the content contained within it were of sufficient quality to perform a face comparison

Known Faces: Score

The Known Faces response will return any matching applicant IDs as entries inside a matches array under a properties bag. Each applicant ID has a corresponding score and the media type (for example live_photos or live_videos), and the corresponding UUID for that media type. For example, the live photo ID or live video ID.

This score is a floating point number between 0 and 1 that expresses how similar the two faces are, where 1 is a perfect match.

For example:

JSON
Copy
"matches": [
  {
    "applicant_id": "NTH_MATCHED_APPLICANT_ID",
    "score": 0.9915,
    "media_id": "LIVE_PHOTO_ID",
    "media_type": "live_photos"
  }
]

If any matches are found, the response will also contain "result": "consider".

The score property is number from 0 to 1, where 1 is a perfect match. The higher the score the more similar the two applicants are. score is a floating point number up to 16 decimal places.

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

{
  "id": "<CHECK_ID>",
  "created_at": "2020-06-19T09:44:14Z",
  "status": "complete",
  "redirect_uri": null,
  "type": "express",
  "result": "consider",
  "sandbox": false,
  "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/<TESTED_APPLICANT_ID>/checks/<CHECK_ID>",
  "reports": [
    {
      "created_at": "2019-05-10T10:49:08Z",
      "href": "/v2/checks/<CHECK_ID>/reports/<REPORT_ID>",
      "id": "<REPORT_ID>",
      "name": "known_faces",
      "properties": {
        "matches": [
          {
            "applicant_id": "<1ST_MATCHED_APPLICANT_ID>",
            "score": 0.9216,
            "media_id": "<1ST_MEDIA_ID>",
            "media_type": "live_photos"
          },
          {
            "applicant_id": "<2ND_MATCHED_APPLICANT_ID>",
            "score": 0.9373,
            "media_id": "<2ND_MEDIA_ID>",
            "media_type": "live_videos"
          },
          {
            "applicant_id": "<3RD_MATCHED_APPLICANT_ID>",
            "score": 0.9832,
            "media_id": "<3RD_MEDIA_ID>",
            "media_type": "live_photos"
          }
        ]
      },
      "result": "consider",
      "status": "complete",
      "sub_result": null,
      "variant": "standard",
      "breakdown": {
        "previously_seen_faces": {
          "result": "consider"
        },
        "image_integrity": {
          "result": "clear"
        }
      }
    }
  ],
  "paused": false,
  "version": "2.0"
}

Identity report

ReportNameVariantsStandard checkExpress check
Identity reportidentitykyc
standard
yes
yes
yes
yes

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 checks containing Identity reports, the applicant's last name must have at least two non-whitespace characters.

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 example in the code box shows:

  • UK: Results for an Identity report conducted in the United Kingdom, where sources (credit_agencies, voting_register, telephone_database) are displayed as breakdowns with their own result value.
  • US with SSN: Results for an Identity report conducted in the United States, which includes Social Security Number as an additional breakdown, and lists sources as comma separated under properties.
  • Non-UK: Results for an Identity report conducted on a jurisdiction other than United Kingdom, where sources are shown as comma separated under properties.

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

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": {},
    "documents": []
  }
}

Supported countries for Identity reports

This is not a list of documents that Onfido supports. You can review that list separately

You can also review the full list of supported countries for Identity reports. The column Onfido Identity Report on that page lists supported and unsupported countries.

Required applicant data

For all Identity report variants, the following applicant data must be provided:

first_name

last_name

dob

country (the country of jurisdiction, where the check will be performed. Must be a three-letter ISO code e.g. "GBR")

address[]state (US only)

address[]postcode (ZIP code in US)

address[]country (must be a three-letter ISO code e.g. "GBR")

The country of jurisdiction must be the same as the value in address[]country

address[]street

The address object is nested inside the applicant object. If you create an applicant object with an address, you must always provide postcode and country, and state for US addresses.

Source names and definitions

Source
name
Definition
Credit AgenciesData comprised of consumer credit applications
Voting RegisterData comprised of voter registration within a country
Telephone DatabaseData provided by both landline and mobile providers. In the UK, this is landline only
GovernmentAny 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 RegistrationData comprised of business registrations, corporate directors filings and business hierarchy data
Consumer DatabaseOpt-in consumer data leveraging database marketing and other similar opt-in data sources
Utility RegistrationData comprised of utility registrations such as electricity, gas, water accounts
Postal AuthoritiesData provided by postal authorities
Commercial DatabaseThese 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
ProprietaryThis 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 DeathsNegative 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.

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": {},
  "documents": []
}

Identity KYC

This check should be used for "Know Your Customer" (KYC) purposes, for instance, if you are providing a financial service.

Overall result logic:

If the applicant address is in the UK:

  • "result": "clear" the applicant is not found in mortality lists AND
    • at least one match on the applicant's name and current address, and a match on the applicant's name and date of birth (either in the same or different source) OR
    • two matches on the applicant's name and current address from two different sources
  • "result": "consider" either:
    • the applicant is found in mortality lists, or;
    • only one match on the applicant's name and current address or name and date of birth
  • "result": "unidentified" no matches are found

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

If the applicant address is outside of the UK:

  • "result": "clear" at least one source matches the applicant's name and current address
  • "result": "consider" the name and date of birth is matched, but no name and address matches are found
  • "result": "unidentified" no matches are found

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

  • "result": "clear" at least one source matches the applicant's name and address, and the last four digits of the SSN are matched
  • "result": "unidentified" no matches are found
  • "result": "consider" otherwise

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

Mortality: Only checked in the UK.

Identity Standard

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

Overall result logic:

  • "result": "clear" at least one source matches the applicant's name and address
  • "result": "consider" the name and date of birth is matched, but no name and address matches are found
  • "result": "unidentified" no matches are found

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

  • "result": "clear" at least one source matches the applicant's name and address, and the last four digits of the SSN are matched
  • "result": "unidentified" no matches are found
  • "result": "consider" otherwise

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

Mortality: Not checked.

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

{
    "id": "<CHECK_ID>",
    "created_at": "2019-10-08T14:27:08Z",
    "status": "complete",
    "redirect_uri": null,
    "result": "clear",
    "sandbox": true,
    "tags": [],
    "results_uri": "<RESULTS_URI>",
    "form_uri": null,
    "reports": [
        {
            "created_at": "2019-10-08T14:27:08Z",
            "href": "/v2/checks/<CHECK_ID>/reports/<REPORT_ID>",
            "id": "<REPORT_ID>",
            "name": "identity",
            "properties": {
                "matched_address": <MATCHED_ADDRESS_ID>,
                "matched_addresses": [
                    {
                        "id": <MATCHED_ADDRESS_ID>,
                        "match_types": [
                            "credit_agencies",
                            "voting_register"
                        ]
                    }
                ]
            },
            "result": "clear",
            "status": "complete",
            "sub_result": null,
            "variant": "standard",
            "documents": [],
            "breakdown": {
                 "sources": {
                  "result": "clear",
                  "breakdown": {
                    "total_sources": {
                      "result": "clear",
                      "properties": {
                        "total_number_of_sources": "3"
                      }
                    },
                  }
                },
                "address": {
                    "result": "clear",
                    "breakdown": {
                        "credit_agencies": {
                            "result": "clear",
                            "properties": {
                                "number_of_credit_agencies": "1"
                            }
                        },
                        "telephone_database": {
                            "result": "clear",
                            "properties": {}
                        },
                        "voting_register": {
                            "result": "clear",
                            "properties": {}
                        }
                    }
                },
                "date_of_birth": {
                    "result": "clear",
                    "breakdown": {
                        "credit_agencies": {
                            "result": "clear",
                            "properties": {}
                        },
                        "voting_register": {
                            "result": "clear",
                            "properties": {}
                        }
                    }
                },
                "mortality": {
                    "result": null
                }
            }
        }
    ],
    "paused": false,
    "type": "express",
    "report_type_groups": [
        "<REPORT_TYPE_GROUP_ID>"
    ],
    "download_uri": "<DOWNLOAD_URI>",
    "href": "/v2/applicants/<APPLICANT_ID>/checks/<CHECK_ID>",
    "version": "2.0"
}

Identity report custom logic

You can (optionally) build your own logic around report results.

For example, you may require matches to be found on 2 or more sources and at least 1 match on the applicant's name and current address.

In this example, you would add criteria of:

  1. >=2 against total_number of sources under the total_sources sub-breakdown that is under the sources parent breakdown.

  2. clear against the result value under the address parent breakdown.

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

...

  "breakdown": {
    "sources": {
      "result": "clear",
      "breakdown": {
          "total_sources": {
              "result": "clear",
              "properties": {
                "total_number_of_sources": "3" ## --< ADD ">=2" CRITERIA HERE>
              }
            },
          }
        },
    "address": {
      "result": "clear", ## --< ADD "clear" CRITERIA HERE>
      "breakdown": {
        "credit_agencies": {
          "result": "clear",
          "properties": {
            "number_of_credit_agencies": "1"
          }
        },
        "telephone_database": {
          "result": "clear",
          "properties": {}
        },
        "voting_register": {
          "result": "clear",
          "properties": {}
        }
      }
    },
    "date_of_birth": {
      "result": "clear",
      "breakdown": {
        "credit_agencies": {
          "result": "clear",
          "properties": {}
        },

...

Watchlist KYC report

ReportNameVariantsStandard checkExpress check
Watchlist reportwatchlistkycyesyes

A Watchlist KYC report provides a granular breakdown of any records found when screening global watchlists. These include the following breakdowns:

  • sanction: Government and International Organisations Sanctions Lists.
  • politically_exposed_person: Proprietary database of Politically Exposed Persons sourced from government lists, websites and other media sources.
  • monitored_lists: Law-Enforcement and Regulatory bodies Monitored Lists (including Terrorism, Money Laundering and Most Wanted lists).
  • adverse_media: Negative events reported by publicly and generally available media sources.

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

Required applicant data

For Watchlist (KYC) reports, the following applicant data must be provided:

first_name

last_name

dob

address[]postcode (ZIP code in US)

address[]country

address[]state (required for US addresses)

The applicant address object is nested inside the applicant object. If you create an applicant object with an address, you must always provide postcode and country, and state for US addresses.

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 politically_exposed_person and adverse_media breakdown matches except Money Laundering and Terrorist related matches. This will not filter sanction breakdown matches.

If a match is found with either Sanctions, Money Laundering or Terrorist related events, all the other events of that match will be returned, even if the other events are not related to the country specified in the address.

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.

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

{
    "id": "<CHECK_ID>",
    "created_at": "2019-10-08T14:31:20Z",
    "status": "complete",
    "redirect_uri": null,
    "result": "clear",
    "sandbox": true,
    "tags": [],
    "results_uri": "<RESULTS_URI>",
    "form_uri": null,
    "reports": [
        {
            "created_at": "2019-10-08T14:31:20Z",
            "href": "/v2/checks/<CHECK_ID>/reports/<REPORT_ID>",
            "id": "<REPORT_ID>",
            "name": "watchlist",
            "properties": {
                "records": []
            },
            "result": "clear",
            "status": "complete",
            "sub_result": null,
            "variant": "kyc",
            "documents": [],
            "breakdown": {
                "politically_exposed_person": {
                    "result": "clear"
                },
                "sanction": {
                    "result": "clear"
                },
                "adverse_media": {
                    "result": "clear"
                },
                 "monitored_lists": {
                  "result": "clear"
                }
            }
        }
    ],
    "paused": false,
    "type": "express",
    "report_type_groups": [
        "<REPORT_TYPE_GROUP_ID>"
    ],
    "download_uri": "<DOWNLOAD_URI>",
    "href": "/v2/applicants/<APPLICANT_ID>/checks/<CHECK_ID>",
    "version": "2.0"
}

Watchlist Full report

ReportNameVariantsStandard checkExpress check
Watchlist reportwatchlistfullyesyes

A Watchlist Full check provides a granular breakdown of any records found when screening global watchlists. These include:

  • sanction: Government and International Organisations Sanctions Lists.
  • politically_exposed_person: Proprietary database of Politically Exposed Persons sourced from government lists, websites and other media sources.
  • legal_and_regulatory_warnings: Law-Enforcement and Regulatory bodies Monitored Lists (including Terrorism, Money Laundering and Most Wanted lists).

Required applicant data

For Watchlist Full checks, the following applicant data must be provided:

first_name

last_name

dob

Extra report options

For Watchlist Full reports, you can use the options array when creating a check. You can populate this with the following:

  • peps - returns politically_exposed_person breakdown matches only
  • sanctions - returns sanction breakdown matches only

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.

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

{
    "id": "<CHECK_ID>",
    "created_at": "2019-10-08T14:32:40Z",
    "status": "complete",
    "redirect_uri": null,
    "result": "clear",
    "sandbox": true,
    "tags": [],
    "results_uri": "<RESULTS_URI>",
    "form_uri": null,
    "reports": [
        {
            "created_at": "2019-10-08T14:32:40Z",
            "href": "/v2/checks/<CHECK_ID>/reports/<REPORT_ID>",
            "id": "<REPORT_ID>",
            "name": "watchlist",
            "properties": {
                "records": []
            },
            "result": "clear",
            "status": "complete",
            "sub_result": null,
            "variant": "full",
            "documents": [],
            "breakdown": {
                "sanction": {
                    "result": "clear"
                },
                "politically_exposed_person": {
                    "result": "clear"
                },
                "legal_and_regulatory_warnings": {
                    "result": "clear"
                }
            }
        }
    ],
    "paused": false,
    "type": "express",
    "report_type_groups": [
        "<REPORT_TYPE_GROUP_ID>"
    ],
    "download_uri": "<DOWNLOAD_URI>",
    "href": "/v2/applicants/<APPLICANT_ID>/checks/<CHECK_ID>",
    "version": "2.0"
}

Street Level report

ReportNameVariantsStandard checkExpress check
Street Level reportstreet_level-yesyes

Creating a check with a Street Level report will cause you to process personal data. Always make sure you inform your users about this and obtain any necessary permissions. For more information on how Onfido uses personal data, view our Privacy Policy.

A Street Level report 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".

Required applicant data

For Street Level reports, the following applicant data must be provided:

first_name

last_name

address[]street

address[]postcode (ZIP code in US)

address[]country

The applicant address object is nested inside the applicant object. If you create an applicant object with an address, you must provide postcode and country, and state for US addresses.

Delivery times

The time at which the 15 day counter starts depends on the check type. For Express checks, it starts from the report creation date. For Standard checks, time starts counting from the moment the applicant has submitted their details in the applicant form.

Letters to UK addresses are sent out by Royal Mail second class postal service. Letters to countries other than the UK are sent out by Royal Mail first class postal service.

All mail is collected Monday-Friday at 3:00pm UK time, excluding UK bank holidays. This means that letters for any reports created after 3pm on a Friday will only be collected on the following Monday at 3pm.

Delivery times from time of mail collection:

  • UK: 2 to 3 working days, including Saturdays.
  • Europe: 3 to 5 working days.
  • Rest of the World: 5 to 7 working days.

Remote areas may take longer.

Royal Mail claim to have a 99% deliverability rate in the UK and 93% for Rest of the World. Providing good quality address data, with all fields correctly filled in the applicant object, greatly increases the deliverability of the letter. Do note that deliverability of the letter is not enough to clear the report. The applicant must enter the code online within the 15 days in order for the report to return as clear.

Customisation

The default letter is Onfido branded and directs the applicant to enter their code at https://onfido.com/slv.

Alternatively the letter can be customised with your branding of choice. If you wish to discuss this please contact your account manager or email client-support@onfido.com.

You can also build your own front end for the applicant to input their code using the submit code endpoint.

Street Level: Breakdowns

addressobject
Contains the result and details of an address match
HTTP/1.1 201 Created
Content-Type: application/json

{
    "id": "<CHECK_ID>",
    "created_at": "2019-10-08T14:35:55Z",
    "status": "complete",
    "redirect_uri": null,
    "result": "clear",
    "sandbox": true,
    "tags": [],
    "results_uri": "<RESULTS_URI>",
    "form_uri": null,
    "reports": [
        {
            "created_at": "2019-10-08T14:35:55Z",
            "href": "/v2/checks/<CHECK_ID>/reports/<REPORT_ID>",
            "id": "<REPORT_ID>",
            "name": "street_level",
            "properties": {},
            "result": "clear",
            "status": "complete",
            "sub_result": null,
            "variant": "standard",
            "documents": [],
            "breakdown": {
                "slv_address": {
                    "result": "clear"
                }
            }
        }
    ],
    "paused": false,
    "type": "express",
    "report_type_groups": [
        "<REPORT_TYPE_GROUP_ID>"
    ],
    "download_uri": "<DOWNLOAD_URI>",
    "href": "/v2/applicants/<APPLICANT_ID>/checks/<CHECK_ID>",
    "version": "2.0"
}

Proof of Address report

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.

ReportNameVariantsStandard checkExpress check
Proof of Address reportproof_of_address-noyes

Required applicant data

For Proof of Address reports, the following applicant data must be provided:

first_name

last_name

address[]street

address[]town

address[]postcode

address[]country (must be a three-letter ISO code e.g. "GBR")

The applicant address object is nested inside the applicant object. If you create an applicant object with an address, you must provide postcode and country, and state for US addresses.

Supported document types

Bank Statement/Building Society Statementsbank_building_society_statement
Utility Bill (electricity, water, gas, broadband )utility_bill
Council Taxcouncil_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 Statementsbank_building_society_statement
Utility Bill (electricity, water, gas, broadband )utility_bill
Government Lettersgovernment_letter

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

Proof of Address: Breakdowns

image_integrityobject
Asserts whether the quality of the uploaded document was sufficient to verify the address
document_classificationobject
Asserts whether the document is of a valid type as PoA
data_comparisonobject
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:

Proof of Address: Properties

document_typeThis property provides the document type according to the set of supported documents
issue_dateThis property provides the issue date of the document
summary_period_startThis property provides the summary period start date
summary_period_endThis property provides the summary period end date
issuerThis property provides the document issuer (e.g. HSBC, British Gas)
first_namesThis property provides the first names on the document, including any initials and middle names
last_namesThis property provided the last names on the document
addressThis 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 quality of the provided PoA document is sufficient to process it
  • the provided PoA document is a supported UK PoA document
  • the data provided by the applicant matches the data that is on their PoA document

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

  • the issuing_country field set when uploading the document is from an unsupported country (i.e. it is different from "GBR")
  • the issuing_country field is not provided when uploading the document

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:

  • the document was not of enough quality to be processed (e.g. image blurred, data points not visible on the document). In this scenario, the value of the image_quality breakdown (which is part of the image_integrity breakdown) will be unidentified and no data will be extracted from the document, hence the report properties attribute will be empty and all the other breakdowns will be null
  • the document is not a valid UK PoA document (i.e. it does not feature in the list of supported document types). In this scenario the value of the supported_document breakdown (which is part of the document_classification breakdown) will be unidentified, no data will be extracted from the document, hence the report properties attribute will be empty and the data comparison breakdowns will be set to null
  • the data provided by the applicant does not match the data extracted from the PoA document. In this scenario the breakdowns first_name, last_name and address (which are part of the data_comparison breakdown) will have a value of unidentified. Data is extracted from the document and returned as part of the report properties attribute.

Right to Work report

ReportNameVariantsStandard checkExpress check
Right to work reportright_to_workyesyes

The Right to Work report is for use in the United Kingdom only.

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

Required applicant data

For Right to Work reports, first_name and last_name must be provided but can be dummy values if you don't know an applicant's name.

Document requirements

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

UK citizens

UK citizens - document requirements
Passport
UK birth certificate AND proof of national insurance number
UK adoption certificate AND proof of national insurance number
UK Certificate of Naturalisation (or Registration) AND proof of national insurance number

EU/EEA/Swiss citizens

EU/EEA/Swiss citizens - document requirements
Passport
National Identity Card
Registration Certificate

Citizens of other nationalities

Non-UK/EU/EEA/Swiss citizens - document requirements
Biometric Residence Permit (or Biometric Residence Card) - cannot be expired
Passport AND visa within current passport - cannot be expired
UK Immigration Status Document AND proof of national insurance number
Home Office letter - must have been issued within the last 6 months
Application Registration Card - cannot be expired
Positive Verification Notice - cannot be expired

Supporting documents

Depending on documents already provided, additional documents may be required for proof of a name change, student status, Tier 2 or Tier 5 visa status, or National Insurance number. Additional documents that may be required are detailed in the next sections.

Proof of name change

One of the following:

  • Marriage certificate
  • Divorce decree (absolute)
  • Deed poll
  • Adoption certificate

Tier 4 (General) student

  • Proof of term (and vacation) dates

Tier 2 and Tier 5 Permit visas

  • Certificate of Sponsorship

Proof of National Insurance number

One of the following:

  • P45 or P60
  • Payslip
  • HMRC letter
  • Benefits letter
HTTP/1.1 201 Created
Content-Type: application/json

{
    "id": "<CHECK_ID>",
    "created_at": "2019-10-08T14:38:21Z",
    "status": "complete",
    "redirect_uri": null,
    "result": "clear",
    "sandbox": true,
    "tags": [],
    "results_uri": "<RESULTS_URI>",
    "form_uri": null,
    "reports": [
        {
            "created_at": "2019-10-08T14:38:21Z",
            "href": "/v2/checks/<CHECK_ID>/reports/<REPORT_ID>",
            "id": "<REPORT_ID>",
            "name": "right_to_work",
            "properties": {
                "nationality": "",
                "last_name": "Smith",
                "issuing_country": "GBR",
                "gender": "",
                "first_name": "John",
                "document_type": "passport",
                "document_numbers": [
                    {
                        "value": "999999999",
                        "type": "document_number"
                    }
                ],
                "date_of_expiry": "2030-01-01",
                "date_of_birth": "1990-01-01"
            },
            "result": "clear",
            "status": "complete",
            "sub_result": null,
            "variant": "standard",
            "documents": [],
            "breakdown": {
                "data_comparison": {
                    "result": "clear",
                    "breakdown": {
                        "issuing_country": {
                            "result": "clear",
                            "properties": {}
                        },
                        "gender": {
                            "result": "clear",
                            "properties": {}
                        },
                        "date_of_expiry": {
                            "result": "clear",
                            "properties": {}
                        },
                        "last_name": {
                            "result": "clear",
                            "properties": {}
                        },
                        "document_type": {
                            "result": "clear",
                            "properties": {}
                        },
                        "document_numbers": {
                            "result": "clear",
                            "properties": {}
                        },
                        "first_name": {
                            "result": "clear",
                            "properties": {}
                        },
                        "date_of_birth": {
                            "result": "clear",
                            "properties": {}
                        }
                    }
                },
                "data_validation": {
                    "result": "clear",
                    "breakdown": {
                        "gender": {
                            "result": "clear",
                            "properties": {}
                        },
                        "date_of_birth": {
                            "result": "clear",
                            "properties": {}
                        },
                        "document_numbers": {
                            "result": "clear",
                            "properties": {}
                        },
                        "document_expiration": {
                            "result": "clear",
                            "properties": {}
                        },
                        "expiry_date": {
                            "result": "clear",
                            "properties": {}
                        },
                        "mrz": {
                            "result": "clear",
                            "properties": {}
                        }
                    }
                },
                "image_integrity": {
                    "result": "clear",
                    "breakdown": {
                        "image_quality": {
                            "result": "clear",
                            "properties": {}
                        },
                        "supported_document": {
                            "result": "clear",
                            "properties": {}
                        },
                        "colour_picture": {
                            "result": "clear",
                            "properties": {}
                        }
                    }
                },
                "visual_authenticity": {
                    "result": "clear",
                    "breakdown": {
                        "fonts": {
                            "result": "clear",
                            "properties": {}
                        },
                        "picture_face_integrity": {
                            "result": "clear",
                            "properties": {}
                        },
                        "template": {
                            "result": "clear",
                            "properties": {}
                        },
                        "security_features": {
                            "result": "clear",
                            "properties": {}
                        },
                        "original_document_present": {
                            "result": "clear",
                            "properties": {}
                        },
                        "digital_tampering": {
                            "result": "clear",
                            "properties": {}
                        },
                        "other": {
                            "result": "clear",
                            "properties": {}
                        },
                        "face_detection": {
                            "result": "clear",
                            "properties": {}
                        }
                    }
                },
                "data_consistency": {
                    "result": "clear",
                    "breakdown": {
                        "date_of_expiry": {
                            "result": "clear",
                            "properties": {}
                        },
                        "document_numbers": {
                            "result": "clear",
                            "properties": {}
                        },
                        "issuing_country": {
                            "result": "clear",
                            "properties": {}
                        },
                        "document_type": {
                            "result": "clear",
                            "properties": {}
                        },
                        "date_of_birth": {
                            "result": "clear",
                            "properties": {}
                        },
                        "gender": {
                            "result": "clear",
                            "properties": {}
                        },
                        "first_name": {
                            "result": "clear",
                            "properties": {}
                        },
                        "last_name": {
                            "result": "clear",
                            "properties": {}
                        },
                        "nationality": {
                            "result": "clear",
                            "properties": {}
                        }
                    }
                },
                "police_record": {
                    "result": "clear"
                },
                "right_to_work": {
                    "result": "clear",
                    "breakdown": {
                        "applicant_has_the_right_to_work": {
                            "result": "clear",
                            "properties": {}
                        }
                    }
                },
                "compromised_document": {
                    "result": "clear"
                }
            }
        }
    ],
    "paused": false,
    "type": "express",
    "report_type_groups": [
        "<REPORT_TYPE_GROUP_ID>"
    ],
    "download_uri": "<DOWNLOAD_URI>",
    "href": "/v2/applicants/<APPLICANT_ID>/checks/<CHECK_ID>",
    "version": "2.0"
}

Other Endpoints

Ping

GET
/ping

Runs a health check on the Onfido API.

If api.onfido.com is operational, the ping endpoint will return OK in Text format.

You can also subscribe to webhook notifications from https://status.onfido.com.

Ping (check api.onfido.com can receive requests)
HTTP
Copy
GET /ping HTTP/1.1
Host: api.onfido.com

Webhooks

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

You can create and configure webhooks to receive status changes from live, sandbox or both environments.

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 5 times according to the following schedule:

  • 30 seconds after the first attempt
  • 2 minutes after the first attempt
  • 15 minutes after the first attempt
  • 2 hours after the first attempt
  • 10 hours after the first attempt

We also use circuit breaking for webhooks: if any 5 requests to the same webhook fail in a row, then that webhook will be disabled for one minute.

You can quickly inspect webhook requests with temporary endpoint URLs. You can create these using free hosted services such as https://webhook.site.

Webhook object

AttributeDescription
idstring
The unique identifier for the webhook.
urlstring
The url to listen to notifications (must be HTTPS).
enabledBoolean
Determines if the webhook should be active. If omitted, will be set to true by default.
eventsarray
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.
tokenstring
The webhook token (read more about verifying webhook signatures.
hrefstring
The URI of this resource.
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"
      ]
    }
  ]
}

Webhook IP addresses

All webhook requests will come from the following IPs:

Europe:

  • 52.51.171.25
  • 52.51.228.228
  • 52.51.234.203

United States:

  • 34.232.2.222
  • 52.55.124.58
  • 34.224.182.19

Canada:

  • 15.223.105.11
  • 15.222.176.53
  • 15.222.71.172

Please make sure that you allow these IPs in order to receive webhook notifications.

Events

By default, webhooks are subscribed to all events, but can be subscribed to a subset using the events array.

You can configure the following events to trigger a message to registered webhooks:

ResourceEventsDescription
checkcheck.startedA check has been started. For Standard checks, this indicates the applicant has submitted all required information.
checkcheck.reopenedA check has been reopened. This indicates the applicant needs to re-submit required information.
checkcheck.withdrawnA check has been withdrawn.
checkcheck.completedA check has been completed.
checkcheck.form_completedAn applicant has submitted their information using the check form.
reportreport.withdrawnA report has been withdrawn.
reportreport.resumedA paused report has been resumed.
reportreport.cancelledA paused report has been cancelled.
reportreport.awaiting_approvalA report has transitioned to the "Awaiting Approval" status.
reportreport.completedA report has been completed and results are available.

Event object

Attributes

AttributeDescription
payloadobject
The top level element.
resource_typestring
Indicates the resource affected by this event.
actionstring
The event that triggered this webhook, e.g. report.completed.
objectobject
The object affected by this event. This will contain an id and an href to retrieve that resource.
HTTP/1.1 201 Created
Content-Type: application/json

{
  "payload": {
    "resource_type": "report",
    "action": "report.completed",
    "object": {
      "id": "<REPORT_ID>",
      "status": "complete",
      "completed_at_iso8601":"2019-11-25T10:11:36Z",
      "href": "https://api.onfido.com/v2/checks/<CHECK_ID>/reports/<REPORT_ID>",
      "completed_at": "2019-11-25 10:11:36 UTC"
    }
  }
}

Verifying webhook signatures

If you're already verifying webhooks in production using SHA-1, this will continue to work and we'll support this for the lifetime of API version 2.

You should verify request signatures on your server to prevent attackers from imitating valid webhook events.

Each webhook you register will return a single secret token in the token field of the API response body, which is used to generate an HMAC using SHA-256. You only need to register a webhook once. The token for each webhook is also displayed on the Onfido Dashboard ‘Webhook Management’ page.

We provide a detailed guide in our Developer Hub for manually verifying webhook signatures.

HTTP
Copy
X-SHA2-Signature: <HMAC_VALUE>

Register webhook

POST
/v2/webhooks/

Registers a webhook. Returns a webhook object.

You can read more about how to verify request signatures on your server.

You cannot use sandbox tokens to create or manage webhooks for live environments.

Request body parameters

urlrequired
The url that will listen to notifications (must be HTTPS).
enabledoptional
Determine if the webhook should be active.<br/ > If omitted, will be set to true by default.
environmentsoptional
The environments from which the webhook will receive events.<br/ > Allowed values are "sandbox" or "live" but sandbox tokens cannot be used for the "live" environment.
If omitted (with a live token), the webhook will receive events from both environments.
eventsoptional
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.

Register a webhook using the Dashboard

You can also register webhooks through the Onfido Dashboard.

Webhook logs

To help you diagnose webhook issues, you can review logs on the Onfido Dashboard.

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

List webhooks

GET
/v2/webhooks/

Lists all webhooks you've created.

List all webhooks you've created
HTTP
Copy
GET /v2/webhooks/ HTTP/1.1
Host: api.onfido.com
Authorization: Token token=<YOUR_API_TOKEN>

Retrieve webhook

GET
/v2/webhooks/{webhook_id}

Retrieves a single webhook.

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

Edit webhook

PUT
/v2/webhooks/{webhook_id}

Edits a webhook.

Edit a webhook (change the URL)
HTTP
Copy
PUT /v2/webhooks/<WEBHOOK_ID> HTTP/1.1
Host: api.onfido.com
Authorization: Token token=<YOUR_API_TOKEN>
Content-Type: application/json

{
    "url": "https://<NEW_URL>"
}

Delete webhook

DELETE
/v2/webhooks/{webhook_id}

Deletes a webhook.

Delete a webhook
HTTP
Copy
DELETE /v2/webhooks/<WEBHOOK_ID> HTTP/1.1
Host: api.onfido.com
Authorization: Token token=<YOUR_API_TOKEN>
Content-Type: application/json

Address picker

GET
/v2/addresses/pick?postcode={postcode}

Performs a search for addresses by postcode (UK only).

Returns data in the form: {"addresses": [<LIST_OF_ADDRESS_OBJECTS>]}.

This resource can be used to make sure addresses passed to the create applicant endpoint are valid.

Query string parameters

postcode (required): the applicant's postcode.

Search for an address using a postcode
HTTP
Copy
GET /v2/addresses/pick?postcode=SW46EH HTTP/1.1
Host: api.onfido.com
Authorization: Token token=<YOUR_API_TOKEN>

Generate SDK token

POST
/v2/sdk_token

Generating an SDK token will enable applicants to send personal data to Onfido via one of our SDKs. For more information on how Onfido uses personal data, view our Privacy Policy.

Generates an SDK token. Returns a token object containing the SDK token.

SDK tokens are JWTs. These are restricted to an individual applicant and expire after 90 minutes, so you can safely use them in the frontend of your application.

You’ll need to generate and include a new token each time you initialize the Onfido SDKs.

Read more about the Onfido SDKs.

The SDK token object returned in the response is of the form: {"token": "header.payload.signature"}.

Request body parameters

applicant_idrequired
Specifies the applicant for the SDK instance.
application_idrequired if referrer not provided
The application ID (or "application bundle ID") - used with the iOS and Android SDKs.
referrerrequired if application_id not provided
The referrer URL pattern - used with the Web SDK.
cross_device_urloptional enterprise feature
The URL to be used by the Web SDK for the cross device flow. (Max 24 characters).

Each authenticated instance of the SDK will correspond to a single Onfido applicant as specified by the applicant_id.

The application_id is the “Application ID” or “Bundle ID” on iOS and Android that was set up during development. For iOS, this is usually in the form com.your-company.app-name. For Android, this is usually in the form com.example.yourapp. Make sure to use a valid application_id or you'll receive a 401 error.

The referrer argument

The referrer argument specifies the URL of the web page where the Web SDK will be used. The referrer sent by the browser must match the referrer URL pattern in the SDK token for the SDK to successfully authenticate. The referrer is based on the Google Chrome match pattern URLs. URLs can contain wild card characters.

The referrer pattern guarantees that other malicious websites cannot reuse the token in case it is lost. You can read more about referrer policy in Mozilla's documentation.

You must use a site referrer policy that lets the Referer header be sent. If your policy does not allow this (e.g. Referrer-Policy: no-referrer), then you'll receive a 401 bad_referrer error when trying to use the Web SDK.

Permitted referrer patterns are as follows:

SectionFormatExample
Referrerscheme://host/pathhttps://*.<DOMAIN>/<PATH>/*
Scheme* or http or httpshttps
Host* or *. then any char except / and **.<DOMAIN>
PathAny char or none<PATH>/*

An example of a valid referrer is https://*.example.com/example_page/*.

The cross_device_url argument

The cross device flow of the Web SDK allows users to continue the identity verification process from their phone where they can take pictures of their document and themselves rather than uploading images from their desktop. The cross_device_url argument specifies the URL of the web page that the Web SDK should direct to instead of the Onfido default. This argument has a limit of 24 characters including https:// and is an enterprise feature that must be activated for your account before it may be used. Please talk to your account executive for more information about purchasing this feature.

Generate a new SDK token with a referrer
HTTP
Copy
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>",
  "cross_device_url": "https://example.com"
}

Autofill BETA

POST
/v2/ocr

Using this endpoint in a live context will cause you to send personal data to Onfido. Always make sure you inform your users about this and obtain any necessary permissions. For more information on how Onfido uses personal data, view our Privacy Policy.

Autofill is currently a BETA product. Please contact client-support@onfido.com if you would like to find out more.

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.

Request body parameters

document_idrequired
The unique identifier of the uploaded document to run extraction on
Return information extracted from a document
HTTP
Copy
POST /v2/ocr HTTP/1.1
Host: api.onfido.com
Authorization: Token token=<YOUR_API_TOKEN>
Content-Type: application/json

{
  "document_id": "<DOCUMENT_ID>"
}

Extraction result

If data has been successfully extracted, the API response will contain the properties document_classification and extracted_data.

document_classification has the following properties:

issuing_countryDocument country in 3-letter ISO code
document_typeType of document. See Document types. Only certain document types are supported by Autofill. Please contact client-support@onfido.com to find out more.
issuing_stateThe state that issued the document

extracted_data has the following properties:

As extraction is done on a best-effort basis, and also information varies across different documents, none of these properties are guaranteed be present in the response.

document_numberThe official document number.
first_nameFirst name.
last_nameLast name.
middle_nameMiddle name.
full_nameFull name.
genderGender. Valid values are Male and Female.
date_of_birthDate of birth in YYYY-MM-DD format.
date_of_expiryDate of expiry in YYYY-MM-DD format.
nationalityNationality in 3-letter ISO code.
mrz_line1Line 1 of the MRZ code.
mrz_line2Line 2 of the MRZ code.
mrz_line3Line 3 of the MRZ code.
address_line_1Line 1 of the address.
address_line_2Line 2 of the address.
address_line_3Line 3 of the address.
address_line_4Line 4 of the address.
address_line_5Line 5 of the address.
HTTP/1.1 201 Created
Content-Type: application/json

{
  "document_id": "<DOCUMENT_ID>",
  "document_classification": {
    "issuing_country": "FRA",
    "document_type": "national_identity_card"
  },
  "extracted_data": {
    "date_of_birth": "1990-07-21",
    "date_of_expiry": "2025-07-07",
    "document_number": "200407512345",
    "first_name": "AMANDINE CHANTAL",
    "gender": "Female",
    "last_name": "MAVARINE",
    "mrz_line1": "IDFRAMAVARINE<<<<<<<<<<<<<<<<<075123",
    "mrz_line2": "2004075123457AMANDINE<CHANT9007219F5",
    "nationality": "FRA"
  }
}

Unsuccessful extraction

Classification failure

If the document cannot be recognised, a classification_failure will be returned.

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

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

Extraction failure

If no data can be extracted, an extraction_failure will be returned.

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

{
  "document_id": "<DOCUMENT_ID>",
  "error": {
    "type": "extraction_failure",
    "message": "We couldn’t extract data from this document."
  }
}

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

POST
/v2/slv

You can submit Street Level report codes to this endpoint.

Request body parameters

coderequired
The unique code present in the Street Level report letter
Submit a street level code
HTTP
Copy
POST /v2/slv HTTP/1.1
Host: api.onfido.com
Authorization: Token token=<YOUR_API_TOKEN>
Content-Type: application/json

{
  "code": "<STREET_LEVEL_CODE>"
}
HTTP/1.1 200 OK
Content-Type: application/json

{
  "success": true
}

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

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

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

AttributeDescription
idstring
The unique identifier for the group.
namestring
The group's name, as specified under your account.
group_onlyboolean
If false, individual reports in that group can be requested; if true, all reports must be requested together.
report_typesarray of report type group objects
A list of objects containing information regarding the different report types included in this group.
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"
    }
  ]
}

Retrieve report type group

GET
/v2/report_type_groups/{report_type_group_id}

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

List report type groups

GET
/v2/report_type_groups/

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