Overview

Get started (API v3.2)

Welcome to our new API v3.2 documentation. If you're migrating and are currently using api.onfido.com, please make sure you use api.eu.onfido.com with API v3.2.


You'll find migration guides on our main Developer Hub.

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 can create and revoke API tokens, and see when they were last used, in your Onfido Dashboard.

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.

  1. In your Onfido Dashboard, 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 update your integration to use a Mobile SDK version which supports SDK 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 on 1st June 2021. From this date new Mobile SDK versions will no longer support Mobile tokens. Please migrate your integration to use SDK tokens so that you can upgrade to new Mobile SDK versions 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

You should never upload confidential information, including personal data, to the sandbox.

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

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

You can use the sandbox API to simulate API requests and 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 Onfido API responses correctly

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

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

For sandbox requests, the rate limit is 30 requests per minute.

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
  • sandbox applicants are isolated from the live environment*
  • you won't be charged for checks in sandbox

* applicant notification emails still get sent out to sandbox applicants

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.

Pre-determined responses work for the following report types:

Pre-determined 'consider' results

To test only 'consider' report responses:

  1. Create an applicant which has the last name "Consider"
  2. Create a check with this applicant

All reports specified in check creation will return a consider report result. If you use any other applicant last name, the result will be clear.

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

Create an applicant with last name of 'Consider'
HTTP
Copy
POST /v3.2/applicants/ HTTP/1.1
Host: api.eu.onfido.com
Authorization: Token token=<YOUR_API_TOKEN>
Content-Type: application/json

{
  "first_name": "Jane",
  "last_name": "Consider"
}

Pre-determined 'consider' and 'clear' results

To test multiple different sandbox report responses simultaneously, you can pass specific report types to the consider parameter (in an array).

Only the reports specified in the consider array will return a consider report result. All other reports in the check will return a clear result.

Trigger multiple report results simultaneously
HTTP
Copy
POST /v3.2/checks/ HTTP/1.1
Host: api.eu.onfido.com
Authorization: Token token=<YOUR_API_TOKEN>
Content-Type: application/json

{
  "applicant_id": "<APPLICANT_ID>",
  "report_names": [
    "watchlist_standard",
    "identity_enhanced"
  ],
  "consider": [
    "watchlist_standard"
  ]
}

Pre-determined responses for Document reports

The sandbox API supports additional functionality for testing Document reports. You can trigger pre-determined Document report responses for specific:

For Document reports, first_name and last_name must be provided when creating an applicant (even in the Sandbox).

Breakdowns and sub-breakdowns

You can trigger responses for particular breakdowns and sub-breakdowns for sandbox Document reports. These responses show possible breakdown and sub-breakdown combinations that can be flagged for a consider report result.

To test breakdown - sub-breakdown combinations:

  1. Create an applicant which has the first_name as the "breakdown - sub-breakdown" combination you would like to trigger.

Sandbox supports the following options:

  • "Image Integrity - Supported Document"
  • "Image Integrity - Image Quality"
  • "Visual Authenticity - Fonts"
  • "Visual Authenticity - Security Features"
  • "Visual Authenticity - Face Detection"
  • "Data Validation - Document Numbers"
  • "Data Consistency - Document Type"
You can also include a document type by specifing `last_name` as a supported sandbox document type during applicant creation.
  1. Create a check with this applicant.

Passing a first_name option to generate a Document report pre-determined response will override any conflicting option passed to the applicant's last_name.

Trigger an 'Image Integrity - Supported Document' breakdown combination for a Document report
HTTP
Copy
POST /v3.2/applicants/ HTTP/1.1
Host: api.eu.onfido.com
Authorization: Token token=<YOUR_API_TOKEN>
Content-Type: application/json

{
  "first_name": "Image Integrity - Supported Document",
  "last_name": "Smith"
}

Document types

You can trigger responses for particular document types for sandbox Document reports. These responses show a Document report response including the specific properties for the associated document type.

To test different document types:

  1. Create an applicant which has the last_name as the document type you would like to test.

Sandbox supports the following options:

Sandbox optionSandbox option *Document type **
"CA DL 2018""CA DL 2018 front only"US drivers license for California state
"NY DL 2017""NY DL 2017 front only"US drivers license for New York state
"Ontario ID 2010"-Canadian national identity card for Ontario
"FRA ID 1994""FRA ID 1994 front only"French identity card

* Specifying "front only" means only data contained on the front side of the document will be returned in the properties.

** The document type properties returned are specific to the document version supported in Sandbox.

You can also trigger a flagged "breakdown - sub-breakdown" combination by specifying `first_name` as a supported combination during applicant creation.
  1. Create a check with this applicant.
Trigger a Document report with US drivers license for California state
HTTP
Copy
POST /v3.2/applicants/ HTTP/1.1
Host: api.eu.onfido.com
Authorization: Token token=<YOUR_API_TOKEN>
Content-Type: application/json

{
  "first_name": "Jane",
  "last_name": "CA DL 2018"
}

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:

  1. Create an applicant which has the last_name as one of the following strings:
  • "clear"
  • "rejected"
  • "suspected"
  • "caution"
  1. Create a check with this applicant.
You can't also specify a document type when testing sub-results.
Trigger a 'rejected' sub-result for a Document report
HTTP
Copy
POST /v3.2/applicants/ HTTP/1.1
Host: api.eu.onfido.com
Authorization: Token token=<YOUR_API_TOKEN>
Content-Type: application/json

{
  "first_name": "Jane",
  "last_name": "rejected"
}

Pre-determined responses for Facial Similarity reports

The sandbox API supports additional functionality for testing breakdowns and sub-breakdowns for Facial Similarity Photo and Photo Fully Auto reports.

For Facial Similarity reports, first_name and last_name must be provided when creating an applicant (even in the Sandbox).

Breakdowns and sub-breakdowns

You can trigger responses for particular breakdowns and sub-breakdowns for sandbox Facial Similarity reports. These responses show possible breakdown and sub-breakdown combinations that can be flagged for a consider report result.

To test breakdown - sub-breakdown combinations:

  1. Create an applicant which has the first_name as the "breakdown - sub-breakdown" combination you would like to trigger.

Sandbox supports the following options:

  • "Visual Authenticity - Spoofing Detection"
  • "Face Comparison - Face Match"
  • "Image Integrity - Source Integrity"
  • "Image Integrity - Face Detected"
  1. Create a check with this applicant.
Trigger an 'Visual Authenticity - Spoofing Detection' breakdown combination for a Facial Similarity report
HTTP
Copy
POST /v3.2/applicants/ HTTP/1.1
Host: api.eu.onfido.com
Authorization: Token token=<YOUR_API_TOKEN>
Content-Type: application/json

{
  "first_name": "Visual Authenticity - Spoofing Detection",
  "last_name": "Smith"
}

Postman collection

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

Run in Postman

The API version 3.2 Postman collection is at version 1.0.

In your Postman environment, you'll need to define the apiToken and baseUrl variables. See region base URLs for baseUrl options.

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

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

LanguageLibraryNotes
Rubyonfido-ruby
Javaonfido-java
Node.jsonfido-nodeAlso supports TypeScript.
Pythononfido-python
PHPapi-php-clientMade with OpenAPI generator.

Refer to our API versioning guide for details on client library versioning.

Please email api@onfido.com if you write your own library and would like us to link to it.

OpenAPI specification

We use an OpenAPI specification to generate our PHP library, which we also host publicly.

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

There is no default region in API v3.2. If you were previously using api.onfido.com, you should use api.eu.onfido.com with v3.2.

Initialization with region 'EU'
Bash
Copy
$ curl https://api.eu.onfido.com/v3.2/

Onfido offers region-specific environments: EU, US, and Canada. You can use these to store the data in your Onfido account at rest within a specific geographic region.

Initialization with region 'US'
Bash
Copy
$ curl https://api.us.onfido.com/v3.2/

Regions have unique base URLs and API token formats for both live and sandbox environments.

Initialization with region 'CA'
Bash
Copy
$ curl https://api.ca.onfido.com/v3.2/
RegionNotesAPI base URLAPI token format
EUReplaces api.onfido.com for EU region in v3.1 and v3.2https://api.eu.onfido.com/Tokens are prepended with api_live. and api_sandbox.
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 https://api.eu.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.

If you're using one of the officially supported API client libraries, follow that library's GitHub documentation to change the region.

Versioning policy

Refer to our API versioning guide for details on Onfido's versioning policy.

Changelog

DateDescription
2021-11-15Added documentation for Trusted Faces.
2021-08-19Added documentation for Face Authenticate.
2021-08-03Added documentation on the Driver's License Data Verification report.
2021-07-21Added documentation for new Sandbox functionality.
2021-06-24General release of API version 3.2. Please see our release notes.

Upcoming maintenance

There's currently no scheduled maintenance.

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.
400 incorrect_base_urlPlease use api.eu.onfido.com for API v3.1 onwards if you were previously using api.onfido.com.
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 report_names_blankMake sure you've specified report_names in your request.
422 report_names_formatreport_names must be an array of strings, not an array of objects.
422 check_type_deprecatedtype is not used in this version of the API. Please read about the applicant_provides_data feature.
422 document_ids_with_unsupported_reportYou should only specify the optional document_ids argument when creating a check containing a Document report or a Facial Similarity report, or both.
422 facial_similarity_photo_without_documentFor applicant_provides_data checks, Facial Similarity reports must be paired with a Document report.
422 facial_similarity_video_not_supportedThe Facial Similarity Video report is not supported for checks where applicant_provides_data is true.
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.

If you're requesting multiple checks for the same individual, you should reuse the id returned in the initial applicant response object in the applicant_id field when creating a check.

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.
first_namestring
The applicant's first name.
last_namestring
The applicant's surname.
emailstring
The applicant's email address.
dobdate
The applicant's date of birth in YYYY-MM-DD format.
id_numbersarray of id number objects
A collection of identification numbers belonging to this applicant.
addressaddress object
The address of the applicant.
sandboxBoolean
Indicates whether the object was created in the sandbox or not.

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

Address object

The applicant address object 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 (ZIP code) of the applicant's address. For UK postcodes, 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.
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, you can provide addresses in the form line1, line2 and line3 if you're creating a check with an Identity Enhanced report. If you provide address data in this form, Onfido uses a third-party subprocessor for address cleansing.

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": "2019-10-09T16:52:42Z",
  "sandbox": true,
  "first_name": "Jane",
  "last_name": "Doe",
  "email": null,
  "dob": "1990-01-01",
  "delete_at": null,
  "href": "/v3.2/applicants/<APPLICANT_ID>",
  "id_numbers": [],
  "address": {
    "flat_number": null,
    "building_number": null,
    "building_name": null,
    "street": "Second Street",
    "sub_street": null,
    "town": "London",
    "state": null,
    "postcode": "S2 2DF",
    "country": "GBR",
    "line1": null,
    "line2": null,
    "line3": null
  }
}

Create applicant

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

Request body parameters

ParameterDescription
first_namerequired
The applicant's forename.
last_namerequired
The applicant's surname.
emailrequired only if creating a check where applicant_provides_data is true
The applicant's email address.
doboptional
The applicant's date of birth in YYYY-MM-DD format.
id_numbersoptional
A collection of identification numbers belonging to this applicant.
addressoptional
The address of the applicant.
Create an applicant
HTTP
Copy
POST /v3.2/applicants/ HTTP/1.1
Host: api.eu.onfido.com
Authorization: Token token=<YOUR_API_TOKEN>
Content-Type: application/json

{
  "first_name": "Jane",
  "last_name": "Doe",
  "dob": "1990-01-31",
  "address": {
    "building_number": "100",
    "street": "Main Street",
    "town": "London",
    "postcode": "SW4 6EH",
    "country": "GBR"
  }
}

Retrieve applicant

GET
/v3.2/applicants/{applicant_id}

Retrieves a single applicant. Returns an applicant object.

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

Update applicant

PUT
/v3.2/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 /v3.2/applicants/<APPLICANT_ID> HTTP/1.1
Host: api.eu.onfido.com
Authorization: Token token=<YOUR_API_TOKEN>
Content-Type: application/json

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

Delete applicant

DELETE
/v3.2/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.

Once deleted, Onfido will not be able to carry out any troubleshooting or investigate any queries raised by the client. It is for this reason we recommend a longer deletion period, for example, a minimum of thirty days.

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

Restore applicant

POST
/v3.2/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 /v3.2/applicants/<APPLICANT_ID>/restore HTTP/1.1
Host: api.eu.onfido.com
Authorization: Token token=<YOUR_API_TOKEN>

List applicants

GET
/v3.2/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.eu.onfido.com/v3.2/applicants?page=3059>; rel="last", <https://api.eu.onfido.com/v3.2/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 /v3.2/applicants?page=1&per_page=5 HTTP/1.1
Host: api.eu.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,
  "applicant_id": "<APPLICANT_ID>",
  "href": "/v3.2/documents/<DOCUMENT_ID>",
  "download_href": "/v3.2/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
/v3.2/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. Maximum supported resolution is 64MPx.

Supply side when uploading documents for optimal results.

Request body parameters

ParameterDescription
applicant_idrequired
The ID of the applicant who owns the document.
filerequired
The file to be uploaded.
typerequired
The type of document. For example, passport.
sideoptional (required for documents which have multiple sides)
Either the front or back of the document.
issuing_countryoptional (required for Proof of Address reports)
The issuing country of the document in 3-letter ISO code.
validate_image_qualityoptional
A Boolean. Defaults to false. When true the submitted image will undergo an image quality validation which may take up to 5 seconds.

Image quality

Please contact your Account Executive to enable this feature.

You can request image quality validation when uploading a document. It is conducted synchronously and you'll receive the result as a response to your request.

When the image passes validation, returns a document object.

When the image fails validation, returns a 422 validation_error. There can be one or more failed image quality validations for a request. The list of reasons is provided in the fields property.

If the image fails validation, you should ask the end user to retake the photo of their document.
FieldMessage
detect_blurblur detected in image
detect_cutoffcutoff document detected in image
document_detectionno document in image

Sample images to trigger various error responses can be provided.

Upload "passport.png"
HTTP
Copy
POST /v3.2/documents/ HTTP/1.1
Host: api.eu.onfido.com
Authorization: Token token=<YOUR_API_TOKEN>
Content-Type: multipart/form-data

Retrieve document

GET
/v3.2/documents/{document_id}

Retrieves a single document. Returns a document object.

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

List documents

GET
/v3.2/documents?applicant_id={applicant_id}

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 /v3.2/documents?applicant_id=<APPLICANT_ID> HTTP/1.1
Host: api.eu.onfido.com
Authorization: Token token=<YOUR_API_TOKEN>

Download document

GET
/v3.2/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 /v3.2/documents/<DOCUMENT_ID>/download HTTP/1.1
Host: api.eu.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_PHOTO_ID>",
  "created_at": "2019-10-09T16:59:06Z",
  "file_name": "<FILE_NAME>.png",
  "file_type": "image/png",
  "file_size": 536630,
  "href": "/v3.2/live_photos/<LIVE_PHOTO_ID>",
  "download_href": "/v3.2/live_photos/<LIVE_PHOTO_ID>/download"
}

Upload live photo

POST
/v3.2/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

ParameterDescription
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 /v3.2/live_photos/ HTTP/1.1
Host: api.eu.onfido.com
Authorization: Token token=<YOUR_API_TOKEN>
Content-Type: multipart/form-data

Retrieve live photo

GET
/v3.2/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 /v3.2/live_photos/<LIVE_PHOTO_ID> HTTP/1.1
Host: api.eu.onfido.com
Authorization: Token token=<YOUR_API_TOKEN>

List live photos

GET
/v3.2/live_photos/?applicant_id={applicant_id}

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 /v3.2/live_photos/live_photos?applicant_id=<APPLICANT_ID> HTTP/1.1
Host: api.eu.onfido.com
Authorization: Token token=<YOUR_API_TOKEN>

Download live photo

GET
/v3.2/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 /v3.2/live_photos/<LIVE_PHOTO_ID>/download HTTP/1.1
Host: api.eu.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 for Facial Similarity Video reports.

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": "/v3.2/live_videos/<LIVE_VIDEO_ID>",
  "download_href": "/v3.2/live_videos/<LIVE_VIDEO_ID>/download",
  "file_name": "<FILE_NAME>.mp4",
  "file_type": "video/mp4",
  "file_size": 1431121,
  "challenge": [
    {
      "type": "recite",
      "query": [
        1,
        2,
        3
      ]
    },
    {
      "type": "movement",
      "query": "turnRight"
    }
  ]
}

Upload live video

Live videos can only be uploaded via one of Onfido's input-capture SDKs, not via the API directly.

As a result, Onfido does not provide an upload live video endpoint.

To upload live videos for Facial Similarity Video reports, integrate with one of our input-capture SDKs (iOS, Android or Web).

Retrieve live video

GET
/v3.2/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 /v3.2/live_videos/<LIVE_VIDEO_ID> HTTP/1.1
Host: api.eu.onfido.com
Authorization: Token token=<YOUR_API_TOKEN>

List live videos

GET
/v3.2/live_videos?applicant_id={applicant_id}

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 /v3.2/live_videos?applicant_id=<APPLICANT_ID> HTTP/1.1
Host: api.eu.onfido.com
Authorization: Token token=<YOUR_API_TOKEN>

Download live video

GET
/v3.2/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 /v3.2/live_videos/<LIVE_VIDEO_ID>/download HTTP/1.1
Host: api.eu.onfido.com
Authorization: Token token=<YOUR_API_TOKEN>

Download live video frame

GET
/v3.2/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 report has completed.

Download the data representing a live video frame
HTTP
Copy
GET /v3.2/live_videos/<LIVE_VIDEO_ID>/frame HTTP/1.1
Host: api.eu.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.
privacy_notices_read_consent_givenBoolean
Indicates that the privacy notices and terms of service have been read and, where specific laws require, that consent has been given for Onfido. This will be true if specified during check creation, otherwise it will be null.
webhook_idsarray of strings
The list of registered webhook IDs to notify as part of this check. Unless the value is included during check creation, this parameter will be null.
hrefstring
The API endpoint to retrieve the check.
applicant_provides_dataBoolean
Run an applicant_provides_data check or not. Default is false.
applicant_idstring
The ID for the applicant associated with the check.
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.
form_uristring
A link to the applicant form, if applicant_provides_data is true.
redirect_uristring
For checks where applicant_provides_data is true, redirect to this URI when the applicant has submitted their data.
results_uristring
A link to the corresponding results page on the Onfido Dashboard
report_idsarray of strings
The list of report object IDs associated with the check.
sandboxBoolean
Indicates whether the object was created in the sandbox or not.

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

{
  "applicant_id": "<APPLICANT_ID>",
  "applicant_provides_data": false,
  "created_at": "2021-03-22T17:13:12Z",
  "form_uri": null,
  "href": "/v3.2/checks/<CHECK_ID>",
  "id": "<CHECK_ID>",
  "paused": false,
  "privacy_notices_read_consent_given": true,
  "redirect_uri": null,
  "report_ids": [
    "<REPORT_ID>"
  ],
  "result": null,
  "results_uri": "<RESULTS_URI>",
  "sandbox": true,
  "status": "in_progress",
  "tags": [],
  "version": "3.2",
  "webhook_ids": null
}

Check results

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

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

Create check

POST
/v3.2/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.

If you are creating multiple checks for the same applicant you should reuse the same applicant_id in every check request. This ensures all checks are associated with the same individual.

When creating checks, you must use the report_names field (which takes an array of strings). For example, to create a check with 2 reports:

"report_names": ["report_name_1", "report_name_2"]

Request body parameters

ParameterDescription
applicant_idrequired
The ID of the applicant to run the check on.
report_namesrequired
Array of strings describing reports requested for the check.
privacy_notices_read_consent_givenoptional
Boolean to indicate that the privacy notices and terms of service have been read and, where specific laws require, that consent has been given for Onfido. This parameter should be set to true after gaining the necessary consent, and if it's set to false the request will fail with a validation error. If this parameter is omitted when creating the check, it will be returned as null in the check response object.
document_idsoptional
Array of strings describing which document to process in checks containing a Document report, a Facial Similarity report or both, which takes a maximum of 2 strings (document IDs) 1. By default, the most recently uploaded document is used. document_ids is only usable with Document and Facial Similarity reports.
applicant_provides_dataoptional
Default is false. If true, applicant provides required information and documents using the Onfido applicant form.
asynchronousoptional
Default is true.2 It’s strongly recommended that you leave this as the default, and configure webhooks to notify you when a check or report is complete.
tagsoptional
Array of tags being assigned to this check.
suppress_form_emailsoptional
For checks where applicant_provides_data is true, applicant form will not be automatically sent if suppress_form_email is 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).
redirect_urioptional
For checks where applicant_provides_data is true, redirect to this URI when the applicant has submitted their data.
consideroptional
Array of names of particular reports to return consider as their results. This is a feature available in sandbox testing which you can read more about.
webhook_idsoptional
Array of strings describing which webhooks to trigger for this check. By default, all webhooks registered in the account will be triggered and this value will be null in the responses.
us_driving_licenceoptional
An object that contains all accepted fields for the Driver's License Data Verification report.

1: For a check containing a Document and Facial Similarity report, you only need to specify 1 document ID which will be used for both reports. You should only specify 2 document IDs when the uploaded document has a front and a back side. If 2 document IDs are submitted in any other case, the Document report will be rejected for Image Quality: two_documents_uploaded.

2: If asynchronous is set to false:

  • the request to create a check will only return a response when all the reports in the check complete the automatic part of the review, or the request times out after 29 seconds
  • if all reports are completed automatically, the check response is returned with a status of complete
  • if one of the reports goes to manual review (the status of the report is awaiting_approval) the check response is returned with a status of in_progress
  • a check created in sandbox will always complete automatically and never time out, so may not give an accurate representation of the behaviour

webhook_ids

The majority of users do not need to set this parameter. By default, events will be sent to all configured webhooks.

If you need a check to only trigger a subset of your webhooks (for example, if you have multiple regional specific webhooks subscribed to report.completed), you can list the IDs of the webhooks this check should trigger by passing the following array as part of your check request:

"webhook_ids": ["<VALID-WEBHOOK-ID-1>", "<VALID-WEBHOOK-ID-2>", ...]

If an invalid webhook ID is included in the list, that ID will be ignored and the request will be processed as though it were not included.

Omitting webhook_ids from the request, or including any of the following in your request will cause the default behavior of setting the check to trigger all webhooks you've created:

  • "webhook_ids": undefined
  • "webhook_ids": null
  • "webhook_ids": []

To make a check ignoring all webhooks you've created, pass the following as part of your check request:

"webhook_ids": ["no_webhooks"]

If any webhook IDs are included in addition to "no_webhooks", you will receive an error.

Inclusion of a webhook ID in webhook_ids does not affect the type of events that webhook is subscribed to.

Report names in API

The following table is of report names as they are described in the API.

Report nameAPI report name(s)
Documentdocument
Document with Address Informationdocument_with_address_information
Document with Driving Licence Informationdocument_with_driving_licence_information
Facial Similarityfacial_similarity_photo
facial_similarity_photo_fully_auto
facial_similarity_video
Known Facesknown_faces
Identityidentity_enhanced
Watchlistwatchlist_enhanced
watchlist_standard
watchlist_peps_only
watchlist_sanctions_only
Proof of Addressproof_of_address
Right to Workright_to_work
Driver's License Data Verificationus_driving_licence

When creating a check, pass these in an array of strings to report_names.

Create a check (Document report, Facial Similarity report)
HTTP
Copy
POST /v3.2/checks/ HTTP/1.1
Host: api.eu.onfido.com
Authorization: Token token=<YOUR_API_TOKEN>
Content-Type: application/json

{
  "applicant_id": "<APPLICANT_ID>",
  "report_names": [
    "document",
    "facial_similarity_photo"
  ]
}

Retrieve check

GET
/v3.2/checks/{check_id}

Retrieves a single check. Returns a check object.

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

List checks

GET
/v3.2/checks?applicant_id={applicant_id}

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

Query string parameters

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

List all checks associated with an applicant
HTTP
Copy
GET /v3.2/checks?applicant_id=<APPLICANT_ID> HTTP/1.1
Host: api.eu.onfido.com
Authorization: Token token=<YOUR_API_TOKEN>

Resume check

POST
/v3.2/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 check where applicant_provides_data is true 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 /v3.2/checks/<CHECK_ID>/resume HTTP/1.1
Host: api.eu.onfido.com
Authorization: Token token=<YOUR_API_TOKEN>

Download check

GET
/v3.2/checks/{check_id}/download

Downloads a PDF of a check with a given check ID. Returns the binary data representing the PDF.

Download a check PDF
HTTP
Copy
GET /v3.2/checks/{check_id}/download HTTP/1.1
Host: api.eu.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 the report itself.

AttributeDescription
idstring
The unique identifier for the report.
created_atdatetime
The date and time at which the report was first initiated.
namestring
The type of report.
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 (null if report is incomplete).
sub_resultstring
The sub_result of the report. It gives a more detailed result for Document reports only, and will be null otherwise.
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 and Facial Similarity reports, otherwise an empty array.
check_idstring
The ID of the check to which the report belongs.

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.
cancelledReport has been cancelled using the cancel report endpoint.
completeReport is done.
withdrawnReport has been automatically withdrawn by the system. For example, due to missing data.
pausedReport is paused until you, i.e. the client, switch it on manually. Special case used by clients who want 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 resultDescription
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.
unidentifiedFor Identity Enhanced and Driver's License Data Verification reports only.
nullFor Proof of Address and Right to Work reports only.

Sub results (Document reports)

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

Report sub_resultDescription
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
/v3.2/reports/{report_id}

Retrieves a single report. Returns a report object.

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

List reports

GET
/v3.2/reports?check_id={check_id}

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

Query string parameters

check_id (required): the ID of the check whose reports you want to list.

List all reports associated with a check
HTTP
Copy
GET /v3.2/reports?check_id=<CHECK_ID> HTTP/1.1
Host: api.eu.onfido.com
Authorization: Token token=<YOUR_API_TOKEN>

Resume report

POST
/v3.2/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 check where applicant_provides_data is true, 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 /v3.2/reports/<REPORT_ID>/resume HTTP/1.1
Host: api.eu.onfido.com
Authorization: Token token=<YOUR_API_TOKEN>

Cancel report

POST
/v3.2/reports/{report_id}/cancel

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

When a report gets cancelled in a check where applicant_provides_data is true, its status will change from paused to cancelled and the report will never get processed.

Cancel a single paused report
HTTP
Copy
POST /v3.2/reports/<REPORT_ID>/cancel HTTP/1.1
Host: api.eu.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.

There are 3 different types of Document reports:

Request body in APINotes
"report_names": ["document"]Primary Document report
"report_names": ["document_with_address_information"]In beta
"report_names": ["document_with_driving_licence_information"]In beta

Document with Address Information and Document with Driving Licence Information are in beta. They are supersets of the Document report which add functionality for specific use cases. Contact your account manager for more information about the features in these beta reports.

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

To specify which uploaded document to run the Document report against in the API, or specify document IDs extracted from the Onfido SDK callback, use the document_ids field. This takes an array of up to 3 strings (3 document IDs):

"document_ids": ["<DOCUMENT_ID>"]

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.

If available, the Document report uses Near Field Communication (NFC) to validate the document's chip in order to verify the document. In this case, the visual authentication, image integrity and data consistency checks will not be performed. Please read our NFC for Document report guide for details on how to integrate and use NFC for Document reports.

In addition, any data extracted from the document 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).

Document report: Object

Our newly expanded OpenAPI specification, which is currently in beta, is the best resource for understanding the Document report response object structure. We welcome feedback on this beta initiative under the 'Issues' tab on GitHub, or at (openapi-feedback@onfido.com)[mailto:openapi-feedback@onfido.com].

We host a separate page which contains a detailed description of the Document report object values from an API user's perspective.

Results

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

Report resultDescription
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, and is unique to Document reports. Possible values of sub_result are as follows:

Sub-resultDescription
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, consider and null.

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.

A breakdown will have the result null when it has not been completed, or is not available. For example, issuing_authority will return null if NFC is not available or inconclusive.

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 mapping

Breakdowns and sub-breakdowns are mapped to particular sub-results. Certain mappings can be changed, where possible, depending on your configuration.

Diagram showing the possible breakdowns and sub-breakdowns for a Document report.

Note: Some breakdowns have sub-breakdowns that are mapped to different sub-results. For example, in the Data Validation breakdown, gender, document_numbers, expiry_date, date_of_birth, mrz and barcode map to suspected whereas document_expiration maps to caution.

Note: When a sub-breakdown mapped to a rejected sub-result is flagged, all other breakdowns and the document properties will be omitted from the response object.

Breakdown descriptions and logic

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.5 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. In this case, data_comparison itself and all its sub-breakdowns return null.

The following sub-breakdowns are used:

  • last_name 1
  • first_name
  • date_of_birth
  1. last_name is not compared against the spouse_name, widow_name or given_name extracted data fields.

Any other sub-breakdowns present under data_comparison in the Document report object exist only for legacy reasons.

data_validation:

Asserts whether the format and length of the fields are correct for that document type. Uses the following sub-breakdowns:

  • gender
  • date_of_birth
  • document_numbers
  • document_expiration 1
  • expiry_date 2
  • mrz
  • barcode
  1. If this is flagged, the document has expired.
  2. If this is flagged, the expiration date has the incorrect format or the date is in the past.

age_validation:

Asserts whether the age calculated from the document’s date of birth data point is greater than or equal to the minimum accepted age set at account level. The default minimum accepted age is 16 years. Configurable to set a different minimum age value. Uses the following sub-breakdown:

  • minimum_accepted_age

image_integrity:

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

  • image_quality:

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

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

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

visual_authenticity:

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

  • fonts:

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

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

  • template:

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

  • security_features:

    Security features expected on the document are missing or wrong.

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

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

  • face_detection:

    No face was detected on the document.

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:

  • multiple_data_sources_present1
  • document_type
  • gender
  • date_of_expiry
  • nationality
  • issuing_country
  • document_numbers
  • date_of_birth
  • last_name
  • first_name
  1. multiple_data_sources_present is for cases where we don’t obtain a US barcode because it wasn’t extracted, wasn’t decoded, or wasn’t there at all (e.g. if the back of the document wasn’t available). It acts as a validation for the data_consistency breakdown: if 2 sources are present, then data consistency is possible and the other sub-breakdowns are enabled. multiple_data_sources_present can be disabled if needed. In this case, it will be returned as null and have no impact on the sub-result.

police_record:

Asserts whether the document has been identified as lost, stolen or otherwise compromised. Applies to all UK documents or any document that has been reported stolen in the UK.

compromised_document:

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

issuing_authority:

Asserts whether data on the document matches the issuing authority data. Uses the following sub-breakdowns:

  • nfc_active_authentication:

    Asserts whether the document NFC chip is original or cloned.

  • nfc_passive_authentication:

    Asserts whether the document NFC chip data was tampered.

If NFC is completed, the visual authentication, image integrity and data consistency checks will not be performed and the breakdowns will be null.1

  1. You can configure your account to always trigger Visual Document Verification if nfc_active_authentication is returned as null (even if nfc_passive_authentication is clear). In this case, the visual authentication, image integrity and data consistency checks will be performed and the results returned in the breakdowns.

Document report: Breakdown reasoning

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

  • visual_authenticity : original_document_present

  • image_integrity : conclusive_document_quality

  • image_integrity : image_quality

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.

The following diagram illustrates this logic:

Diagram showing the possible reasons for a Document report to be flagged.

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

Conclusive Document Quality reasons:

obscured_data_points - This refers to when data points are obscured to the point that we cannot confirm if the fonts match the expected ones

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 3 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), 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

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 2 different documents are submitted in the same check

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

{
  "breakdown": {
    "age_validation": {
      "breakdown": {
        "minimum_accepted_age": {
          "properties": {},
          "result": "clear"
        }
      },
      "result": "clear"
    },
    "compromised_document": {
      "result": "clear"
    },
    "data_comparison": {
      "breakdown": {
        "date_of_birth": {
          "properties": {},
          "result": "clear"
        },
        "date_of_expiry": {
          "properties": {},
          "result": "null"
        },
        "document_numbers": {
          "properties": {},
          "result": "null"
        },
        "document_type": {
          "properties": {},
          "result": "null"
        },
        "first_name": {
          "properties": {},
          "result": "clear"
        },
        "gender": {
          "properties": {},
          "result": "null"
        },
        "issuing_country": {
          "properties": {},
          "result": "null"
        },
        "last_name": {
          "properties": {},
          "result": "clear"
        }
      },
      "result": "clear"
    },
    "data_consistency": {
      "breakdown": {
        "date_of_birth": {
          "properties": {},
          "result": "clear"
        },
        "date_of_expiry": {
          "properties": {},
          "result": "clear"
        },
        "document_numbers": {
          "properties": {},
          "result": "clear"
        },
        "document_type": {
          "properties": {},
          "result": "clear"
        },
        "first_name": {
          "properties": {},
          "result": "clear"
        },
        "gender": {
          "properties": {},
          "result": "clear"
        },
        "issuing_country": {
          "properties": {},
          "result": "clear"
        },
        "last_name": {
          "properties": {},
          "result": "clear"
        },
        "multiple_data_sources_present": {
          "properties": {},
          "result": "clear"
        },
        "nationality": {
          "properties": {},
          "result": "clear"
        }
      },
      "result": "clear"
    },
    "data_validation": {
      "breakdown": {
        "date_of_birth": {
          "properties": {},
          "result": "clear"
        },
        "document_expiration": {
          "properties": {},
          "result": "clear"
        },
        "document_numbers": {
          "properties": {},
          "result": "clear"
        },
        "expiry_date": {
          "properties": {},
          "result": "clear"
        },
        "gender": {
          "properties": {},
          "result": "clear"
        },
        "mrz": {
          "properties": {},
          "result": "clear"
        },
        "barcode": {
          "properties": {},
          "result": "clear"
        }
      },
      "result": "clear"
    },
    "image_integrity": {
      "breakdown": {
        "colour_picture": {
          "properties": {},
          "result": "clear"
        },
        "conclusive_document_quality": {
          "properties": {},
          "result": "clear"
        },
        "image_quality": {
          "properties": {},
          "result": "clear"
        },
        "supported_document": {
          "properties": {},
          "result": "clear"
        }
      },
      "result": "clear"
    },
    "police_record": {
      "result": "clear"
    },
    "visual_authenticity": {
      "breakdown": {
        "digital_tampering": {
          "properties": {},
          "result": "clear"
        },
        "face_detection": {
          "properties": {},
          "result": "clear"
        },
        "fonts": {
          "properties": {},
          "result": "clear"
        },
        "original_document_present": {
          "properties": {},
          "result": "clear"
        },
        "other": {
          "properties": {},
          "result": "clear"
        },
        "picture_face_integrity": {
          "properties": {},
          "result": "clear"
        },
        "security_features": {
          "properties": {},
          "result": "clear"
        },
        "template": {
          "properties": {},
          "result": "clear"
        }
      },
      "result": "clear"
    },
    "issuing_authority": {
      "breakdown": {
        "nfc_active_authentication": {
          "properties": {},
          "result": null 
        },
        "nfc_passive_authentication": {
          "properties": {},
          "result": null
        }
      },
      "result": null
    }
  },
  "check_id": "<CHECK_ID>",
  "created_at": "2021-03-22T17:13:12Z",
  "documents": [
    {
      "id": "<DOCUMENT_ID>"
    }
  ],
  "href": "/v3.2/reports/<REPORT_ID>",
  "id": "<REPORT_ID>",
  "name": "document",
  "properties": {
    "date_of_birth": "1990-01-01",
    "date_of_expiry": "2030-01-01",
    "document_numbers": [
      {
        "type": "document_number",
        "value": "999999999"
      }
    ],
    "document_type": "passport",
    "first_name": "Jane",
    "gender": "",
    "issuing_country": "GBR",
    "last_name": "Doe",
    "nationality": ""
  },
  "result": "clear",
  "status": "complete",
  "sub_result": "clear"
}

BETA Document report options

Document with Address Information

This report is in beta. Contact your account manager for more information about the features in this report.

To request a Document with Address Information report as part of a check in the API, use the report_names field (which takes an array of strings):

"report_names": ["document_with_address_information"]

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

If you use this report, Onfido will use a third-party subprocessor for address cleansing after the address has been extracted.

To specify which uploaded document to run the Document with Address Information report against in the API, use the document_ids field. This takes an array of up to 2 strings (2 document IDs):

"document_ids": ["<DOCUMENT_ID>"]

For a clear result, the following snippet is an example showing what is added to the Document report response object:

JSON
Copy
...
        "address_lines": {
            "city": "EDINBURGH",
            "country": "United Kingdom (UK)",
            "postal_code": "EH1 9GP",
            "state": "",
            "street_address": "122 BURNS CRESCENT",
            "country_code": null
        },
        "address": "<ADDRESS_STRING>",
...

Contact your account manager for more information about the features in the Document with Address Information report.

Document with Driving Licence Information

This report is in beta. Contact your account manager for more information about the features in this report.

To request a Document with Driving Licence Information report as part of a check in the API, use the report_names field (which takes an array of strings):

"report_names": ["document_with_driving_licence_information"]

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

To specify which uploaded document to run the Document with Driving Licence Information report against in the API, use the document_ids field. This takes an array of up to 2 strings (2 document IDs):

"document_ids": ["<DOCUMENT_ID>"]

For a clear result, the following snippet is an example showing what is added to the Document report response object:

JSON
Copy
...
"driving_licence_information": [
    {
      "category": "A",
      "codes": "79.03,79.04",
      "expiry_date": "<YYYY-MM-DD>",
      "obtainment_date": "<YYYY-MM-DD>"
    },
    {
      "category": "A1",
      "codes": "79.03,79.04",
      "expiry_date": "<YYYY-MM-DD>",
      "obtainment_date": "<YYYY-MM-DD>"
    },
    {
      "category": "AM",
      "codes": "",
      "expiry_date": "<YYYY-MM-DD>",
      "obtainment_date": "<YYYY-MM-DD>"
    },
    {
      "category": "B",
      "codes": "",
      "expiry_date": "<YYYY-MM-DD>",
      "obtainment_date": "<YYYY-MM-DD>"
    }
  ],
...
The report must be completed using a manual only review process to guarantee the driving license data is extracted.

Contact your account manager for more information about the features in the Document with Driving Licence Information report.

Facial Similarity reports

This section contains API documentation for the Facial Similarity reports. You can also read our product documentation.

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

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.

There are 3 different types of Facial Similarity report:

Report nameRequest body in API
Photo"report_names": ["facial_similarity_photo"]
Photo Fully Auto"report_names": ["facial_similarity_photo_fully_auto"]
Video"report_names": ["facial_similarity_video"]

All Facial Similarity reports will compare the most recent live photo or live video provided by the applicant to the face on the specified document provided during check creation in the document_ids field.

"document_ids": ["<DOCUMENT_ID>"]

By default, the most recently uploaded document specified will be used. Where the document has two sides, we will search both sides of the document for a face. If unspecified, the most recently uploaded document will be used.

When document IDs are associated with a Facial Similarity report, the document IDs of the documents used will be returned under the documents attribute of the report object.

When side is not specified, it will take a default value of front. We recommend 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.

Required applicant data

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

Facial Similarity Photo

If applicant_provides_data is true, the Facial Similarity Photo report needs to be paired with a Document report.

Facial Similarity Photo: Object

The following table describes the unique fields returned in this version of the Onfido API for a completed Facial Similarity Photo 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_integrity1String or null"clear", "consider", null
face_comparisonString or null"clear", "consider", null
(sub-breakdown) face_match2String or null"clear", "consider", null
visual_authenticityString or null"clear", "consider", null
(sub-breakdown) spoofing_detection3String or null"clear", "consider", null

1: source_integrity may contain reasons under the properties bag (see Facial Similarity Photo: Source Integrity)

2: face_match contains a score value and document_id unique identifier under the properties bag (see Facial Similarity Photo: Face Match properties)

3: spoofing_detection contains a score value under the properties bag (see Facial Similarity Photo: Spoofing Detection Score)

Facial Similarity Photo: Breakdowns

BreakdownDescription
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 in 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.
(sub-breakdown) face_matchobject
Contains a score value and document_id unique identifier for the matched document under the properties bag (see Facial Similarity Photo: Match properties).
visual_authenticityobject
Asserts whether the person in the live photo is real (not a spoof).
(sub-breakdown) spoofing_detectionobject
Contains a score value under the properties bag (see Facial Similarity Photo: Spoofing Detection Score).

Facial Similarity Photo: Source Integrity

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 Photo, 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 Photo: Face Match properties

The face_match breakdown contains a properties object with a score value and document_id unique identifier.

  • The score value is a floating point 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 spoofing (such as photos of printed photos or photos of digital screens) is detected the applicant will be rejected independently of the face match score.

  • document_id returns the UUID for the document containing the extracted face that was used for face matching.

    If no face is detected, no document is recorded and the property is returned as null.

Facial Similarity Photo: Spoofing Detection Score

The spoofing_detection breakdown contains a properties object with a score value. This score is a floating point number between 0 and 1. The closer the score is to 0, the more likely it is to be a spoof (i.e. photos of printed photos, or photos of digital screens). Conversely, the closer it is to 1, the less likely it is to be a spoof.

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

{
  "created_at": "2019-12-11T09:39:05Z",
  "href": "/v3.2/reports/<REPORT_ID>",
  "id": "<REPORT_ID>",
  "name": "facial_similarity_photo",
  "properties": {},
  "result": "clear",
  "status": "complete",
  "sub_result": null,
  "breakdown": {
    "face_comparison": {
      "result": "clear",
      "breakdown": {
        "face_match": {
          "result": "clear",
          "properties": {
            "score": 0.6512,
            "document_id": "<DOCUMENT_ID>"
          }
        }
      }
    },
    "image_integrity": {
      "result": "clear",
      "breakdown": {
        "face_detected": {
          "result": "clear",
          "properties": {}
        },
        "source_integrity": {
          "result": "clear",
          "properties": {}
        }
      }
    },
    "visual_authenticity": {
      "result": "clear",
      "breakdown": {
        "spoofing_detection": {
          "result": "clear",
          "properties": {
            "score": 0.9512
          }
        }
      }
    }
  },
  "check_id": "<CHECK_ID>",
  "documents": []
}

Photo Fully Auto

If applicant_provides_data is true, the Photo Fully Auto report needs to be paired with a Document report.

Photo Fully Auto: Object

The following table describes the unique fields returned in this version of the Onfido API for a completed Photo Fully Auto 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_integrity1String or null"clear", "consider", null
face_comparisonString or null"clear", "consider", null
(sub-breakdown) face_match2String or null"clear", "consider", null
visual_authenticityString or null"clear", "consider", null
(sub-breakdown) spoofing_detection3String or null"clear", "consider", null

1: source_integrity may contain reasons under the properties bag (see Source Integrity for Photo Fully Auto)

2: face_match contains a score value and document_id unique identifier under the properties bag (see Face Match properties for Photo Fully Auto)

3: spoofing_detection contains a score value under the properties bag (see Spoofing Detection Score for Photo Fully Auto)

Photo Fully Auto: Breakdowns

BreakdownDescription
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 in 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.
(sub-breakdown) face_matchobject
Contains a score value and document_id unique identifier for the matched document under the properties bag (see Face Match properties for Fully Auto).
visual_authenticityobject
Asserts whether the person in the live photo is real (not a spoof).
(sub-breakdown) spoofing_detectionobject
Contains a score value under the properties bag (see Spoofing Detection Score for Fully Auto).

Photo Fully Auto: Source Integrity

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 Photo Fully Auto, 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

Photo Fully Auto: Face Match properties

The face_match breakdown contains a properties object with a score value and document_id unique identifier.

  • The score value is a floating point 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. The score only measures how similar the faces are, and does not make an assessment of the nature of the photo. If spoofing (such as photos of printed photos or photos of digital screens) is detected the applicant will be rejected independently of the face match score.

  • document_id returns the UUID for the document containing the extracted face that was used for face matching.

    If no face is detected, no document is recorded and the property is returned as null.

Photo Fully Auto: Spoofing Detection Score

The spoofing_detection breakdown contains a properties object with a score value. This score is a floating point number between 0 and 1. The closer the score is to 0, the more likely it is to be a spoof (i.e. photos of printed photos, or photos of digital screens). Conversely, the closer it is to 1, the less likely it is to be a spoof.

If the anti-spoofing algorithm fails to detect a face, the score property will not be present.

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

{
  "created_at": "2020-01-01T14:16:21Z",
  "href": "/v3.2/reports/<REPORT_ID>",
  "id": "<REPORT_ID>",
  "name": "facial_similarity_photo_fully_auto",
  "result": "clear",
  "status": "complete",
  "sub_result": null,
  "breakdown": {
    "visual_authenticity": {
      "result": "clear",
      "breakdown": {
        "spoofing_detection": {
          "result": "clear",
          "properties": {
            "score": 0.9901
          }
        }
      }
    },
    "image_integrity": {
      "result": "clear",
      "breakdown": {
        "face_detected": {
          "result": "clear",
          "properties": {}
        },
        "source_integrity": {
          "result": "clear",
          "properties": {}
        }
      }
    },
    "face_comparison": {
      "result": "consider",
      "breakdown": {
        "face_match": {
          "result": "consider",
          "properties": {
            "score": 0.2097,
            "document_id": "<DOCUMENT_ID>"
          }
        }
      }
    }
  },
  "check_id": "<CHECK_ID>"
}

Facial Similarity Video

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

Checks where applicant_provides_data is true are not compatible with Facial Similarity Video reports.

In addition to confirming the two faces match, Facial Similarity Video assesses active liveness by asking users to repeat randomly generated numbers and perform a random head movement. This prevents impersonation - for example masks, and deep fakes displayed on digital screens. This process is reflected in visual_authenticity, which is composed of the sub-breakdowns spoofing_detection and liveness_detected. See 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"
Italian"it"
Indonesian"id"
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 this version of the Onfido API 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_integrity1String or null"clear", "consider", null
face_comparisonString or null"clear", "consider", null
(sub-breakdown) face_match2String or null"clear", "consider", null
visual_authenticityString or null"clear", "consider", null
(sub-breakdown) spoofing_detection3String or null"clear", "consider", null
(sub-breakdown) liveness_detectedString or null"clear", "consider", null

1: source_integrity may contain reasons under the properties bag (see Facial Similarity Video: Source Integrity)

2: face_match contains a score value and document_id unique identifier under the properties bag (see Facial Similarity Video: Face Match properties)

3: spoofing_detection contains a score value under the properties bag (see Facial Similarity Video: Spoofing Detection Score)

Facial Similarity Video: Breakdowns

BreakdownDescription
face_comparisonobject
Asserts whether the face in the document matches the face in the live video.
(sub-breakdown) face_matchobject
Contains a score value and document_id unique identifier for the matched document under the properties bag (see Facial Similarity Video: Face Match properties).
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 in 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.

Facial Similarity Video: Source Integrity

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: Face Match properties

The face_match breakdown contains a properties object with a score value and document_id unique identifier.

  • The score value is a floating point 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 live video. If spoofing (such as videos of digital screens, masks or print-outs) is detected the applicant will be rejected independently of the face match score.

  • document_id returns the UUID for the document containing the extracted face that was used for face matching.

    If no face is detected, no document is recorded and the property is returned as null.

Facial Similarity Video: Spoofing Detection Score

The spoofing_detection breakdown contains a properties object with a score value. This score is a floating point number between 0 and 1. The closer the score is to 0, the more likely it is to be a spoof (i.e. videos of digital screens, masks or print-outs). Conversely, the closer it is to 1, the less likely it is to be a spoof.

The score value is based on passive facial information only, regardless of whether or not the user said the expected digits or turned their head in the correct direction. For example, a user who performs no action but is a real person should receive a score close to 1.

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

{
  "created_at": "2019-12-11T10:06:38Z",
  "href": "/v3.2/reports/<REPORT_ID>",
  "id": "<REPORT_ID>",
  "name": "facial_similarity_video",
  "properties": {},
  "result": "clear",
  "status": "complete",
  "sub_result": null,
  "breakdown": {
    "face_comparison": {
      "result": "clear",
      "breakdown": {
        "face_match": {
          "result": "clear",
          "properties": {
            "score": 0.6512,
            "document_id": "<DOCUMENT_ID>"
          }
        }
      }
    },
    "image_integrity": {
      "result": "clear",
      "breakdown": {
        "face_detected": {
          "result": "clear",
          "properties": {}
        },
        "source_integrity": {
          "result": "clear",
          "properties": {}
        }
      }
    },
    "visual_authenticity": {
      "result": "clear",
      "breakdown": {
        "liveness_detected": {
          "result": "clear",
          "properties": {}
        },
        "spoofing_detection": {
          "result": "clear",
          "properties": {
            "score": 0.9512
          }
        }
      }
    }
  },
  "check_id": "<CHECK_ID>",
  "documents": []
}

Suggested client actions

We host a guide on our Developer Hub for suggested client actions in specific scenarios for clients using our Facial Similarity reports.

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.

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.

To request a Known Faces report as part of a check in the API, use the report_names field (which takes an array of strings):

"report_names": ["known_faces"]

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 this version of the Onfido API 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

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

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

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

{
  "created_at": "2020-06-19T09:44:14Z",
  "documents": [],
  "href": "/v3.2/reports/<REPORT_ID>",
  "id": "<REPORT_ID>",
  "name": "known_faces",
  "properties": {
    "matches": [
      {
        "applicant_id": "<1ST_MATCHED_APPLICANT_ID>",
        "score": 1,
        "media_id": "<1ST_MEDIA_ID>",
        "media_type": "live_photos"
      },
      {
        "applicant_id": "<2ND_MATCHED_APPLICANT_ID>",
        "score": 1,
        "media_id": "<2ND_MEDIA_ID>",
        "media_type": "live_videos"
      },
      {
        "applicant_id": "<3RD_MATCHED_APPLICANT_ID>",
        "score": 0.8903,
        "media_id": "<3RD_MEDIA_ID>",
        "media_type": "live_photos"
      },
      {
        "applicant_id": "<4TH_MATCHED_APPLICANT_ID>",
        "score": 0.8903,
        "media_id": "<4TH_MEDIA_ID>",
        "media_type": "live_photos"
      },
      {
        "applicant_id": "<5TH_MATCHED_APPLICANT_ID>",
        "score": 0.8903,
        "media_id": "<5TH_MEDIA_ID>",
        "media_type": "live_photos"
      }
    ]
  },
  "result": "consider",
  "status": "complete",
  "sub_result": null,
  "breakdown": {
    "previously_seen_faces": {
      "result": "consider"
    },
    "image_integrity": {
      "result": "clear"
    }
  },
  "check_id": "<CHECK_ID>"
}

Identity Enhanced report

This section contains API documentation for the Identity Enhanced report. You can also read our product documentation, which includes a list of the sources used in the Identity Enhanced report, with corresponding definitions, and the report logic.

To request an Identity Enhanced report as part of a check in the API, use the report_names field (which takes an array of strings):

"report_names": ["identity_enhanced"]

For checks containing Identity Enhanced reports, the applicant's last name must have at least 2 characters.

Required applicant data

For Identity Enhanced reports, the following applicant data must be provided:

first_name

last_name

dob

address[]state (US only)

address[]postcode (ZIP code in US)

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

address[]street 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 countries for Identity Enhanced

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

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

Identity Enhanced report custom logic

We've moved this content.

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

{
  "created_at": "2019-10-03T15:54:20Z",
  "href": "/v3.2/reports/<REPORT_ID>",
  "id": "<REPORT_ID>",
  "name": "identity_enhanced",
  "properties": {
    "matched_address": 19099121,
    "matched_addresses": [
      {
        "id": 19099121,
        "match_types": [
          "credit_agencies",
          "voting_register"
        ]
      }
    ]
  },
  "result": "clear",
  "status": "complete",
  "sub_result": null,
  "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_matches": "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": "clear"
    }
  },
  "check_id": "<CHECK_ID>",
  "documents": []
}

Watchlist reports

This section contains API documentation for the Onfido Watchlist reports. You can also read our product documentation.

There are 4 different types of Watchlist report:

Report nameRequest body in API
Watchlist Standard"report_names": ["watchlist_standard"]
Watchlist Enhanced"report_names": ["watchlist_enhanced"]
Watchlist PEPs Only"report_names": ["watchlist_peps_only"]
Watchlist Sanctions Only"report_names": ["watchlist_sanctions_only"]

Watchlist Enhanced

The Watchlist Enhanced 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.

Records

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 the overall result will be consider. Each event will correspond to a relevant category of list, which drives one of the breakdowns.

As matches are done based on the available information, none of these properties are guaranteed to be present in the response.
FieldDescriptionSub-fields
addressarray of objects
All addresses on file
address_line1
country
postal_code
state_province
town
locator_type
aliasarray of objects
Any names that the person is also known as
alias_name
alias_type
associatearray of objects
Any linked persons, for example family relatives or business partners
entity_name
relationship_direction
relationship_type
attributearray of objects
Information about the person, for example hair color or nationality
attribute_type
attribute_value
date_of_birtharray of DOB objects
All the date of births on file
eventarray of objects
Information about events that have occurred to the person, for example deportation or arrest
category
event_date
event_description
source (source_date, source_format, source_name)
sub_category
full_namestring
The name on file
positionarray of strings
The role, country and date of each position
sourcearray of objects
Details about where the information was obtained
source_headline
source_name
source_url

Required applicant data

For watchlist_enhanced reports, first_name and last_name must be provided.

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

{
  "created_at": "2019-10-03T15:37:03Z",
  "href": "/v3.2/reports/<REPORT_ID>",
  "id": "<REPORT_ID>",
  "name": "watchlist_enhanced",
  "properties": {
    "records": []
  },
  "result": "clear",
  "status": "complete",
  "sub_result": null,
  "breakdown": {
    "politically_exposed_person": {
      "result": "clear"
    },
    "sanction": {
      "result": "clear"
    },
    "adverse_media": {
      "result": "clear"
    },
     "monitored_lists": {
      "result": "clear"
    }
  },
  "check_id": "<CHECK_ID>",
  "documents": []
}

Watchlist Standard

The Watchlist Standard report 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).

You can use a Watchlist PEPs Only report to search only PEPs lists, or a Watchlist Sanctions Only report to search only sanctions and warnings lists. The Watchlist Standard report will search all types.

Records

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 the overall result will be consider.

As matches are done based on the available information, none of these properties are guaranteed to be present in the response.
FieldDescription
associatesstring
Any linked persons, for example family relatives or business partners
keywordsstring
last_updated_utcstring
The date and time the entry was last updated
entity_typestring
Should always be "person"
sourcesstring
Where the information was obtained, for example "PEPs list"
typesstring
The type of the source, for example "pep-class-1"
namestring
The name on file. Allows for custom cross-referencing of input details against output details
external_idstring
Returns an empty string
match_typesstring
The type of match, for example, "name_exact"
related_urlsstring
URL to the data source
picture_urlsstring
URL to the picture of the individual found in the match
all_dobsstring
All the date of births on file. Allows for custom cross-referencing of input details against output details
report_idinteger
The ID of the report
entity_fields_dobsstring
Date of birth
entity_fields_dodstring
Date of death
entity_fields_podstring
Place of birth
entity_fields_ofacstring
Office of Foreign Assets Control (OFAC) ID
entity_fields_addressstring
Address
entity_fields_countriesstring
Countries

Where applicable, if multiple values are found from the raw response, string concatenation with a delimiter of ", " is used.

Entity fields are additional, optional fields so they may not be present in the final result.

Required applicant data

For watchlist_standard reports, first_name and last_name must be provided.

dob

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

{
  "created_at": "2019-10-03T15:42:36Z",
  "href": "/v3.2/reports/<REPORT_ID>",
  "id": "<REPORT_ID>",
  "name": "watchlist_standard",
  "properties": {
    "records": []
  },
  "result": "clear",
  "status": "complete",
  "sub_result": null,
  "breakdown": {
    "sanction": {
      "result": "clear"
    },
    "politically_exposed_person": {
      "result": "clear"
    },
    "legal_and_regulatory_warnings": {
      "result": "clear"
    }
  },
  "check_id": "<CHECK_ID>",
  "documents": []
}

Watchlist PEPs Only

The Watchlist PEPs Only report is a subset of the Watchlist Standard report. It provides a granular breakdown of politically_exposed_person breakdown matches.

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. See Watchlist Standard records for details of the possible fields.

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.

Required applicant data

For watchlist_peps_only reports, first_name and last_name must be provided.

dob

Watchlist Sanctions Only

The Watchlist Sanctions Only report is a subset of the watchlist_standard report. It provides a granular breakdown of sanction breakdown matches.

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. See Watchlist Standard records for details of the possible fields.

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.

Required applicant data

For Watchlist Sanctions Only reports, first_name and last_name must be provided.

dob

Proof of Address report

This section contains API documentation for the Proof of Address report. You can also read our product documentation, which contains a guide on the logic the Proof of Address report uses.

To request a Proof of Address report as part of a check in the API, use the report_names field (which takes an array of strings):

"report_names": ["proof_of_address"]

The Proof of Address (PoA) report is for use with UK documents only.

You must set the issuing_country field to "GBR" when uploading the document via the document upload endpoint.

If the issuing_country field is not specified or is from an unsupported country, the document will be uploaded however it will not be processed and the report will complete with the status set to cancelled and the result set to null.

Applicants are able to upload documents from anywhere in the world, but the document must have been issued by the United Kingdom and be a supported document for this report.

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

Checks where applicant_provides_data is set to true are not compatible with Proof of Address reports.

Supported document types

The following document types are supported for a PoA report:

DocumentAPI Document type
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

Proof of Address: Breakdowns

A PoA report is composed of the following 3 breakdowns:

BreakdownDescription
image_integrityobject
Asserts whether the quality of the uploaded document was sufficient to verify the address
document_classificationobject
Asserts whether the document is a supported document type
data_comparisonobject
Asserts whether the first name, last name and address provided by the applicant match those on the PoA document

Proof of Address: Properties

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

FieldDescription
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

Only the summary period or the issue date will be returned in the report properties attribute as they are mutually exclusive.

Proof of Address: Overall Result Logic

We've moved this content.

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

{
  "created_at":"2021-04-27T14:51:35Z",
  "documents":[],
  "href":"/v3.2/reports/<REPORT_ID>",
  "id":"<REPORT_ID>",
  "name":"proof_of_address",
  "properties":{
     "document_type":"council_tax",
     "issuer":"city of london",
     "issue_date":"2020-01-01",
     "first_names":"John",
     "last_names":"Smith",
     "address":"123 sample street london xyz 1ab"
  },
  "result":"clear",
  "status":"complete",
  "sub_result":null,
  "breakdown":{
     "image_integrity":{
        "result":"clear",
        "breakdown":{
           "image_quality":{
              "result":"clear",
              "properties":{}
           }
        }
     },
     "document_classification":{
        "result":"clear",
        "breakdown":{
           "supported_document":{
              "result":"clear",
              "properties":{}
           }
        }
     },
     "data_comparison":{
        "result":"clear",
        "breakdown":{
           "first_name":{
              "result":"clear",
              "properties":{}
           },
           "last_name":{
              "result":"clear",
              "properties":{}
           },
           "address":{
              "result":"clear",
              "properties":{}
           }
        }
     }
  },
  "check_id":"<CHECK_ID>"
}

Right to Work report

This section contains API documentation for the Right to Work report. You can also 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.

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

To request a Right to Work report as part of a check in the API, use the report_names field (which takes an array of strings):

"report_names": ["right_to_work"]

A Right to Work report can be completed by either uploading copies of documents that would be accepted by the UK Home Office or by providing a GOV.UK right to work share code.

Make sure that necessary documents are uploaded or an applicant has been created with a share code in the id_numbers object before the check is created, unless you're requesting an applicant_provides_data check. You can read about document requirements.

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.

Right to Work: Results

The result field indicates the overall report result. Possible values for Right to Work reports are clear, consider and null:

Report resultDescription
clearThe applicant has the right to work
considerThe applicant has restricted right to work or no right to work
nullToo many reopens* and no right to work decision

* This will occur when an applicant has had their check reopened too many times for the same reason.

The Right to Work report object will return different breakdown values depending on whether a document or share code was provided.

Right to Work: Document

Breakdowns

When a document is provided the Right to Work report result is determined by the right_to_work breakdown, which can have either a clear or consider result.

The right_to_work breakdown is informed by the applicant_has_the_right_to_work sub-breakdown which can have one of 3 results:

  • clear (no known restrictions on right to work)
  • consider (restrictions on right to work e.g. working hours)
  • unidentified (no right to work)

The report result is also informed by breakdowns which signal fraud or image quality issues in the associated document.

BreakdownDescription
right_to_workobject
Asserts whether the applicant has the right to work.
(sub-breakdown) applicant_has_right_to_workobject
Asserts whether the applicant has the right to work, has restricted right to work or no right to work.
data_validationobject
Asserts whether algorithmically validatable elements are correct.
police_recordobject
Asserts whether the document had been identified as lost, stolen or otherwise compromised.
data_consistencyobject
Asserts whether data represented in multiple places on the document is consistent.
visual_authenticityobject
Asserts whether visual, non-textual, elements are correct given the type of document.
image_integrityobject
Asserts if the document is of sufficient quality to verify.
age_validationobject
Asserts if the age calculated from the documents date of birth is greater or equal to the minimum accepted age.
compromised_documentobject
Asserts whether the image of the document has been found in our internal database of compromised documents.
data_comparisonobject
Asserts whether data on the document is consistent with data provided when creating an applicant through the API.
HTTP/1.1 201 Created
Content-Type: application/json

{
   "created_at":"2021-04-28T12:24:05Z",
   "documents":[],
   "href":"/v3.2/reports/<REPORT_ID>",
   "id":"<REPORT_ID>",
   "name":"right_to_work",
   "properties":{
      "first_name":"John",
      "last_name":"Smith",
      "gender":"Male",
      "nationality":"GBR",
      "issuing_country":"GBR",
      "document_numbers":[
         {
            "type":"document_number",
            "value":"123456789"
         }
      ],
      "document_type":"passport",
      "document_version":"2010",
      "date_of_birth":"1990-01-01",
      "issuing_date":"2010-01-01",
      "date_of_expiry":"2030-01-01",
      "mrz_line1":"<MRZ_DATA>",
      "mrz_line2":"<MRZ_DATA>",
      "place_of_birth":"",
      "issuing_authority":""
   },
   "result":"clear",
   "status":"complete",
   "sub_result":null,
   "breakdown":{
      "right_to_work":{
         "result":"clear",
         "breakdown":{
            "applicant_has_the_right_to_work":{
               "result":"clear",
               "properties":{}
            }
         }
      },
      "data_comparison":{
         "result":"clear",
         "breakdown":{
            "date_of_expiry":{
               "result":"clear",
               "properties":{}
            },
            "issuing_country":{
               "result":"clear",
               "properties":{}
            },
            "date_of_birth":{
               "result":"clear",
               "properties":{}
            },
            "last_name":{
               "result":"clear",
               "properties":{}
            },
            "first_name":{
               "result":"clear",
               "properties":{}
            },
            "document_type":{
               "result":"clear",
               "properties":{}
            },
            "document_numbers":{
               "result":"clear",
               "properties":{}
            },
            "gender":{
               "result":"clear",
               "properties":{}
            }
         }
      },
      "data_consistency":{
         "result":"clear",
         "breakdown":{
            "date_of_expiry":{
               "result":"clear",
               "properties":{}
            },
            "document_type":{
               "result":"clear",
               "properties":{}
            },
            "nationality":{
               "result":"clear",
               "properties":{}
            },
            "issuing_country":{
               "result":"clear",
               "properties":{}
            },
            "document_numbers":{
               "result":"clear",
               "properties":{}
            },
            "gender":{
               "result":"clear",
               "properties":{}
            },
            "date_of_birth":{
               "result":"clear",
               "properties":{}
            },
            "last_name":{
               "result":"clear",
               "properties":{}
            },
            "first_name":{
               "result":"clear",
               "properties":{}
            }
         }
      },
      "data_validation":{
         "result":"clear",
         "breakdown":{
            "document_expiration":{
               "result":"clear",
               "properties":{}
            },
            "gender":{
               "result":"clear",
               "properties":{}
            },
            "document_numbers":{
               "result":"clear",
               "properties":{
                  "document_number":"clear"
               }
            },
            "expiry_date":{
               "result":"clear",
               "properties":{}
            },
            "date_of_birth":{
               "result":"clear",
               "properties":{}
            },
            "mrz":{
               "result":"clear",
               "properties":{}
            }
         }
      },
      "compromised_document":{
         "result":"clear"
      },
      "image_integrity":{
         "result":"clear",
         "breakdown":{
            "conclusive_document_quality":{
               "result":"clear",
               "properties":{}
            },
            "colour_picture":{
               "result":"clear",
               "properties":{}
            },
            "supported_document":{
               "result":"clear",
               "properties":{}
            },
            "image_quality":{
               "result":"clear",
               "properties":{}
            }
         }
      },
      "age_validation":{
         "result":"clear"
      },
      "visual_authenticity":{
         "result":"clear",
         "breakdown":{
            "other":{
               "result":"clear",
               "properties":{}
            },
            "fonts":{
               "result":"clear",
               "properties":{}
            },
            "face_detection":{
               "result":"clear",
               "properties":{}
            },
            "template":{
               "result":"clear",
               "properties":{}
            },
            "digital_tampering":{
               "result":"clear",
               "properties":{}
            },
            "picture_face_integrity":{
               "result":"clear",
               "properties":{}
            },
            "original_document_present":{
               "result":"clear",
               "properties":{}
            },
            "security_features":{
               "result":"clear",
               "properties":{}
            }
         }
      },
      "police_record":{
         "result":"clear"
      }
   },
   "check_id":"<CHECK_ID>"
}

Right to Work: Share code

Breakdowns

When a share code is provided the Right to Work report result is determined by the share_code_validation breakdown as well as the right_to_work breakdown.

The document_id sub-breakdown contains the document ID to retrieve the GOV.UK evidence document of the applicant's right to work using the retrieve document endpoint.

BreakdownDescription
share_code_validationobject
Asserts whether the applicant has a valid right to work share code.
(sub-breakdown)
document_id
object
Contains the document ID number in the properties bag. This can be used to retrieve an image of the GOV.UK results page.
(sub-breakdown) applicant_has_valid_share_codeobject
Asserts whether the provided share code is valid.
(sub-breakdown) name_matchedobject
Asserts whether the applicant's given name matches the name on the share code results document.
right_to_workobject
Asserts whether the applicant has the right to work.
(sub-breakdown) applicant_has_right_to_workobject
Asserts whether the applicant has the right to work, has restricted right to work or no right to work.
HTTP/1.1 201 Created
Content-Type: application/json
{
    "created_at": "2021-04-20T13:56:55Z",
    "documents": [],
    "href": "/v3.2/reports/<REPORT_ID>",
    "id": "<REPORT_ID>",
    "name": "right_to_work",
    "properties": {},
    "result": "clear",
    "status": "complete",
    "sub_result": null,
    "breakdown": {
        "share_code_validation": {
            "result": "clear",
            "breakdown": {
                "document_id": {
                    "result": "clear",
                    "properties": {
                        "document_id": "<DOCUMENT_ID>"
                    }
                },
                "name_matched": {
                    "result": "clear",
                    "properties": {}
                },
                "applicant_has_valid_share_code": {
                    "result": "clear",
                    "properties": {}
                }
            }
        },
        "right_to_work": {
            "result": "clear",
            "breakdown": {
                "applicant_has_the_right_to_work": {
                    "result": "clear",
                    "properties": {}
                }
            }
        }
    },
    "check_id": "<CHECK_ID>"
}

Driver's License Data Verification report

This section contains API documentation for the Driver's License Data Verification (DLDV) report. You can also read our product documentation.

The DLDV report is for United States documents only.

To request a DLDV report as part of a check in the API, use the report_names field (which takes an array of strings):

"report_names": ["us_driving_licence"]

To upload document data, use the us_driving_licence field (which is an object containing all accepted fields for the DLDV report):

JSON
Copy
"us_driving_licence":{
  "id_number": "<DRIVER_LICENCE_ID>",             // required
  "issue_state": "<TWO_LETTER_STATE_CODE>",       // required
  ...                                             // all other optional fields
}

See optional document data for a table of the accepted optional fields in the us_driving_licence object for a DLDV report.

If you use this report, Onfido will use a third-party subprocessor to verify driving license data against the American Association of Motor Vehicle Administrators (AAMVA) facilitated Department of Motor Vehicles (DMV) driver's license database.

Required applicant data

For DLDV reports, first_name and last_name must be provided.

Required document data

For DLDV reports, the following document data must be provided in the report request in the us_driving_licence field:

FieldFormat
id_numberString
issue_stateString
(2-character state code)

Optional document data

The following optional fields are also accepted in the us_driving_licence object:

FieldFormatPossible values
address_line_1String
address_line_2String
cityString
date_of_birthDate
YYYY-MM-DD
document_categoryEnum"driver license", "driver permit", "id card"
expiration_dateDate
YYYY-MM-DD
eye_color_codeEnum"BLK", "BLU", "BRO", "DIC", "GRY", "GRN", "HAZ", "MAR", "PNK"
first_nameString
genderString
height_measure_feetInteger
height_measure_inchesInteger
issue_dateDate
YYYY-MM-DD
last_nameString
middle_nameString
name_suffixString
postal_codeString
stateString
(2-character state code)
weight_measureInteger
(in pounds)

Supported document types

  • US driver's license
  • US learner's permit or provisonal license
  • ID card
A DLDV report does not require a document upload. Data is entered manually in the report request.

DLDV: Results

The result field indicates the overall report result. Any optional fields submitted in the report request will be accounted for in the final result.

Possible values for DLDV reports are clear, consider and unidentified:

Report resultDescription
clearAll fields exact match
considerName fields have been flagged as a mismatch through fuzzy matching* or any optional fields don't match
unidentifiedID number or name field doesn't match

* Onfido's third-party subprocessor uses fuzzy matching on the name fields during DLDV checks. This is because information can be provided in many different ways and errors in data submission or collection can be quite high. Fuzzy matching allows capturing data variations.

DLDV: Breakdowns

Breakdowns can have a clear or consider result. Breakdowns will only have a clear result when all included sub-breakdowns are clear.

Breakdowndescriptionsub-breakdowns
documentobject
Asserts whether the document data provided matches a real driving license in the DMV driver's license database.
category
expiration_date
issue_date
document_number
addressobject
Asserts whether the address data provided matches a real driving license in the DMV driver's license database.
city
line_1
line_2
state_code
zip4
zip5
personalobject
Asserts whether the personal data provided matches a real driving license in the DMV driver's license database.
name_suffix
height
weight
sex_code
eye_color
date_of_birth
first_name
last_name
middle_name
first_name_fuzzy
middle_name_fuzzy
last_name_fuzzy
middle_initial
HTTP/1.1 201 Created
Content-Type: application/json

{
    "created_at": "2021-03-26T19:51:37Z",
    "documents": [],
    "href": "/v3.2/reports/<REPORT_ID>",
    "id": "<REPORT_ID>",
    "name": "us_driving_licence",
    "properties": {},
    "result": "clear",
    "status": "complete",
    "sub_result": null,
    "breakdown": {
        "document": {
            "result": "clear",
            "breakdown": {
                "category": {
                    "result": "clear",
                    "properties": {}
                },
                "expiration_date": {
                    "result": "clear",
                    "properties": {}
                },
                "issue_date": {
                    "result": "clear",
                    "properties": {}
                },
                "document_number": {
                    "result": "clear",
                    "properties": {}
                }
            }
        },
        "address": {
            "result": "clear",
            "breakdown": {
                "city": {
                    "result": "clear",
                    "properties": {}
                },
                "line_1": {
                    "result": "clear",
                    "properties": {}
                },
                "line_2": {
                    "result": "clear",
                    "properties": {}
                },
                "state_code": {
                    "result": "clear",
                    "properties": {}
                },
                "zip4": {
                    "result": "clear",
                    "properties": {}
                },
                "zip5": {
                    "result": "clear",
                    "properties": {}
                }
            }
        },
        "personal": {
            "result": "clear",
            "breakdown": {
                "first_name": {
                    "result": "clear",
                    "properties": {}
                },
                "name_suffix": {
                    "result": "clear",
                    "properties": {}
                },
                "height": {
                    "result": "clear",
                    "properties": {}
                },
                "weight": {
                    "result": "clear",
                    "properties": {}
                },
                "sex_code": {
                    "result": "clear",
                    "properties": {}
                },
                "eye_color": {
                    "result": "clear",
                    "properties": {}
                },
                "date_of_birth": {
                    "result": "clear",
                    "properties": {}
                },
                "last_name": {
                    "result": "clear",
                    "properties": {}
                },
                "middle_name": {
                    "result": "clear",
                    "properties": {}
                },
                "first_name_fuzzy": {
                    "result": "clear",
                    "properties": {}
                },
                "middle_name_fuzzy": {
                    "result": "clear",
                    "properties": {}
                },
                "last_name_fuzzy": {
                    "result": "clear",
                    "properties": {}
                },
                "middle_initial": {
                    "result": "clear",
                    "properties": {}
                }
            }
        }
    },
    "check_id": "<CHECK_ID>"
}

Other Endpoints

Ping

GET
/ping

Runs a health check on the Onfido API.

If the regional base URL you're using 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.eu.onfido.com can receive requests)
HTTP
Copy
GET /ping HTTP/1.1
Host: api.eu.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.
environmentsarray
Lists the environments that the webhook will receive events from.
HTTP/1.1 200 OK
Content-Type: application/json

{
  "webhooks": [
    {
      "id": "<WEBHOOK_ID>",
      "url": "https://demo.com",
      "enabled": false,
      "href": "/v3.2/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. When applicant_provides_data is true, 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.

Webhook event versioning

Refer to our API versioning guide for details on webhook event versioning.

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-10-28T15:00:39Z",
      "href": "https://api.onfido.com/v3/reports/<REPORT_ID>"
    }
  }
}

Verifying webhook signatures

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.

If possible, we recommend that you verify request signatures with our supported client libraries in your integration.

The following Onfido client libraries have support built in:

  • Java

  • Node

  • Python

Using Onfido client libraries

You must initialise the verifier instance with your webhook’s secret token. For each webhook event, the verifier instance needs:

  • the signature of the webhook (from the X-SHA2-Signature header)

  • the body of the event request (must be in raw format, not decoded from JSON)

Manually

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

HTTP
Copy
X-SHA2-Signature: <HMAC_VALUE>

Register webhook

POST
/v3.2/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

ParameterDescription
urlrequired
The url that will listen to notifications (must be HTTPS).
enabledoptional
Determine if the webhook should be active.
If omitted, will be set to true by default.
environmentsoptional
The environments from which the webhook will receive events.
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
POST /v3.2/webhooks/ HTTP/1.1
Host: api.eu.onfido.com
Authorization: Token token=<YOUR_API_TOKEN>
Content-Type: application/json

{
  "url": "https://<URL>",
  "enabled": true,
  "events": [
    "report.completed",
    "check.completed"
  ]
}

List webhooks

GET
/v3.2/webhooks/

Lists all webhooks you've created.

Returns data in the form: {"webhooks": [<LIST_OF_WEBHOOK_OBJECTS>]}.

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

Retrieve webhook

GET
/v3.2/webhooks/{webhook_id}

Retrieves a single webhook. Returns a webhook object.

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

Edit webhook

PUT
/v3.2/webhooks/{webhook_id}

Edits a webhook. Returns the updated webhook object.

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

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

Delete webhook

DELETE
/v3.2/webhooks/{webhook_id}

Deletes a webhook. If successful, returns a 204 No Content response.

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

Address Picker

GET
/v3.2/addresses/pick?postcode={postcode}

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

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

The Onfido Address Picker will always use a third-party subprocessor for address cleansing. In this way, it 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 /v3.2/addresses/pick?postcode=SW46EH HTTP/1.1
Host: api.eu.onfido.com
Authorization: Token token=<YOUR_API_TOKEN>

Generate SDK token

POST
/v3.2/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 can only be used in our input-capture SDKs. They are restricted to an individual applicant, and expire after 90 minutes.

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

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

The composition and length of SDK tokens is variable and can change over time.

Request body parameters

ParameterDescription
applicant_idrequired
Specifies the applicant for the SDK instance.
application_idoptional, should not be used if referrer provided
The application ID (or "application bundle ID") - used with the iOS and Android SDKs.
referreroptional, should not be used if application_id 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).
This replaces the default id.onfido.com and requires additional setup to map back to the Onfido hosted cross-device address.

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

The application_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.

If you want to disable the application ID check, you can pass the wildcard *. Alternatively, don't pass either of the application_id and referrer parameters.

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.

If you want to disable the referer header check, you can pass the wildcard *. Alternatively, don't pass either of the application_id and referrer parameters.

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. This feature is available to all customers and uses the URL id.onfido.com as the default. The cross_device_url argument is used to white-label the default Onfido cross-device URL to one of your choosing with a maximum character length of 24 including https://. While the cross-device flow is available to all customers, white-labeling the URL using this argument is a premium 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.

Example SMS before and after using this feature:

Before:

Continue your identity verification by tapping https://id.onfido.com/<UNIQUE-PATH>

After:

Continue your identity verification by tapping <YOUR-CROSS-DEVICE-URL>/<UNIQUE-PATH>

Generate a new SDK token with a referrer
HTTP
Copy
POST /v3.2/sdk_token HTTP/1.1
Host: api.eu.onfido.com
Authorization: Token token=<YOUR_API_TOKEN>
Content-Type: application/json

{
  "applicant_id": "<APPLICANT_ID>",
  "referrer:": "https://*.example.com/example_page/*",
  "cross_device_url": "https://example.com"
}

Face Authenticate

This section contains API documentation for the Face Authenticate product. You can also read our product documentation.

Face Authenticate enables you to re-verify an end user who already has an established trusted identity with Onfido.

Trusted faces

Each applicant you run Face Authenticate against must have had their initial trusted identity established via trusted faces.

Trusted faces allows you to upload a facial image to be associated with a specific applicant in your Onfido account database. The image is then used to compare against repeat identity verifications for that applicant via Face Authenticate.

You can upload an image submitted by an applicant during a Facial Similarity report or any image of the applicant that you trust.

Trusted faces are validated at the point of upload to check that they contain exactly one face.

Trusted face object

AttributeDescription
applicant_idstring
The unique identifier for the applicant.
created_atdatetime
The date and time when this trusted face was created.
updated_atdatetime
The date and time when this trusted face was last updated.
download_hrefstring
The URI that can be used to download the trusted face.
HTTP/1.1 201 Created
Content-Type: application/json

{
    "applicant_id": "<APPLICANT_ID>",
    "created_at": "2021-09-01T22:21:07Z",
    "updated_at": "2021-09-01T22:21:07Z",
    "download_href": "/applicants/<APPLICANT_ID>/face/download"
}

Create trusted face from file

POST
/v3.2/applicants/{applicant_id}/face

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 trusted face for a given applicant using a jpg or png file. Returns a trusted face object.

Onfido will not check the validity of this image, so you should only upload an image that you trust is accurate.

We provide a sample photo to test this endpoint.

Request body parameters

ParameterDescription
filerequired
The file to be uploaded.
Create a trusted face from a file
HTTP
Copy
POST /v3.2/applicants/<APPLICANT_ID>/face HTTP/1.1
Host: api.eu.onfido.com
Authorization: Token token=<YOUR_API_TOKEN>
Content-Type: multipart/form-data

Create trusted face from live photo or live video

POST
/v3.2/applicants/{applicant_id}/face

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 trusted face for a given applicant using the id of a live photo or live video that was previously submitted by the applicant for a Facial Similarity report. Returns a trusted face object.

Request body parameters

ParameterDescription
live_photo_idoptional, should not be used if live_video_id provided
The unique identifier of the live photo.
live_video_idoptional, should not be used if live_photo_id provided
The unique identifier of the live video.
Create a trusted face from a live photo
HTTP
Copy
POST /v3.2/applicants/<APPLICANT_ID>/face HTTP/1.1
Host: api.eu.onfido.com
Authorization: Token token=<YOUR_API_TOKEN>
Content-Type: application/json

{
    "live_photo_id": "<LIVE_PHOTO_ID>"
}

Retrieve trusted face

GET
/v3.2/applicants/{applicant_id}/face

Retrieves an applicant's trusted face. Returns a trusted face object.

Retrieve a trusted face
HTTP
Copy
GET /v3.2/applicants/<APPLICANT_ID>/face HTTP/1.1
Host: api.eu.onfido.com
Authorization: Token token=<YOUR_API_TOKEN>

Download trusted face

GET
/v3.2/applicants/{applicant_id}/face/download

Downloads an applicant's trusted face. If successful, the response will be the binary data representing the image.

Download a trusted face
HTTP
Copy
GET /v3.2/applicants/<APPLICANT_ID>/face/download HTTP/1.1
Host: api.eu.onfido.com
Authorization: Token token=<YOUR_API_TOKEN>

Delete trusted face

DELETE
/v3.2/applicants/{applicant_id}/face

Deletes an applicant's trusted face. If successful, returns a 204 No Content response.

Any authentication attempts using Face Authenticate will fail from this point onwards. The same applies if you have rolling deletion turned on.

Delete a trusted face
HTTP
Copy
DELETE /v3.2/applicants/<APPLICANT_ID>/face HTTP/1.1
Host: api.eu.onfido.com
Authorization: Token token=<YOUR_API_TOKEN>

Authentication

Face Authenticate is only available via Onfido's input-capture or Authentication SDKs, not via the API directly.

As a result, Onfido does not provide Authentication attempt or session endpoints in this documentation. Contact your account manager for more information.

Verify Authentication tokens

GET
/v3.2/auth/keys

Verifies the JWT token returned in the Authentication result.

Verify Authentication token
HTTP
Copy
GET /v3.2/auth/keys HTTP/1.1
Host: api.eu.onfido.com
Content-Type: application/json

Response

Returns a JWKS (JSON Web Key Set) with public keys to verify the JWT token returned in the Authentication result.

AttributeDescription
algstring
The specific cryptographic algorithm used with the key.
ktystring
The family of cryptographic algorithms used with the key.
usestring
How the key was meant to be used.
nstring
The modulus for the RSA public key.
estring
The exponent for the RSA public key.
kidstring
The unique identifier for the key.
HTTP/1.1 200 OK
Content-Type: application/json

{
  "keys": [
    {
      "alg": "RS256",
      "kty": "RSA",
      "use": "sig",
      "n": "yeNlzlub94YgerT030codqEztjfU_S6X4DbDA_iVKkjAWtYfPHDzz_sPCT1Axz6isZ",
      "e": "AQAB",
      "kid": "NjVBRjY5MDlCMUIwNzU4RTA2QzZFMDQ4QzQ2MDAyQjVDNjk1RTM2Qg"
    }
  ]
}

List Authentication attempts

GET
/v3.2/auth/attempts

Lists all the Authentication attempts performed by a given applicant.

Query string parameters

ParameterRequirementDescription
applicant_idrequiredstring
The UUID of the applicant to get the authentication attempts for.
afteroptionalstring (Datetime in ISO-8601)
A timestamp used to get attempts after a certain date and time.
beforeoptionalstring (Datetime in ISO-8601)
A timestamp used to get attempts before a certain date and time.

List Authentication attempts
HTTP
Copy
GET /v3.2/auth/attempts HTTP/1.1
Host: api.eu.onfido.com
Authorization: Token token=<YOUR_API_TOKEN>
Content-Type: application/json

https://api.eu.onfido.com/v3.2/auth/attempts?applicant_id="<APPLICANT_ID>"

Response

Returns data as an array of Authentication attempts. The array contains a maximum of 20 Authentication attempts. Additional attempts will be paginated and can be accessed via the link header.

AttributeDescription
idstring
The UUID of the Authentication attempt.
applicant_idstring
The UUID of the applicant that made the attempt.
timestampstring (Datetime in ISO-8601)
The date and time at which the attempt was made.
successBoolean
The result of the Authentication attempt.
errorstring
The reason why an Authentication attempt failed.
Returned as null when success is true. Otherwise returned as a string containing the reason for the error.
sdk_sourcestring
SDK type used in the Authentication attempt.
sdk_versionstring
SDK version used in the Authentication attempt.
sdk_metadataJSON object
SDK metadata of the device used in the Authentication process.
image_hrefBinary image
The href to download the audit image used for the attempt.

Error reasons

We will return a reason whenever an Authentication attempt fails.

The following reasons can be returned in the error field:

  • unsuccessful_authentication_match - The authentication matching has failed (i.e. face features did not match the applicant's enrolment image)

  • missing_applicant_data - We're missing some information associated with the applicant (e.g. applicant has no trusted face)

  • missing_product_activation - The Authentication product isn't activated for the given account

  • service_unavailable - Something went wrong on our side when processing the authentication attempt

  • unexpected_error - We faced an unexpected error. Please contact support for further investigation

The link header contains pagination information. For example:

Link: <https://api.eu.onfido.com/v3.2/auth/attempts?page=OpaqueString>; rel="next"

next is the only rel value. This indicates the link is for the next page of results.

X-Total-Count header

The x-total-count header contains the total resource count.

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

{
  "attempts": [
    {
      "id": "<AUTHENTICATION_ATTEMPT_UUID>",
      "applicant_id": "<APPLICANT_ID>",
      "timestamp": "2020-09-04T09:37:37.588802Z",
      "success": true,
      "error": null,
      "sdk_version": "7.2.0",
      "sdk_source": "onfido-android-sdk",
      "sdk_metadata": {
        "system": {
          "product": "XPTO-123X",
          "model": "XPTO-123X",
          "manufacturer": "XPTO",
          "hardware": "a1234c0d01",
          "fingerprint": "XPTO/XPTO-123X/XPTO-123X:9/P123.000000.000/1234567890:user/release-keys",
          "brand": "XPTO"
        }
      },
      "image_href": "/auth/attempts/<AUTHENTICATION_ATTEMPT_UUID>/image"
    },
    {
      "id": "<AUTHENTICATION_ATTEMPT_UUID>",
      "applicant_id": "<APPLICANT_ID>",
      "timestamp": "2020-09-04T09:37:37.588802Z",
      "success": false,
      "error": "missing_applicant_data",
      "sdk_version": "7.2.0",
      "sdk_source": "onfido-android-sdk",
      "sdk_metadata": {
        "system": {
          "product": "XPTO-123X",
          "model": "XPTO-123X",
          "manufacturer": "XPTO",
          "hardware": "a1234c0d01",
          "fingerprint": "XPTO/XPTO-123X/XPTO-123X:9/P123.000000.000/1234567890:user/release-keys",
          "brand": "XPTO"
        }
      },
      "image_href": "/auth/attempts/<AUTHENTICATION_ATTEMPT_UUID>/image"
    }
  ]
}

Retrieve audit image

GET
/v3.2/auth/attempts/{attempt_id}/image

Retrieves the audit image used for the given Authentication attempt.

Returns the binary data for the audit image that was saved with the Authentication attempt and a content-type header with the image's MIME type.

If the request is not successful, you will receive one of the following errors:

Error typeMessage
invalid_attempt_idThe provided attempt_id isn't a valid UUID.
attempt_not_foundCouldn't find attempt with id=<attempt_id>.
image_not_foundCouldn't find image for attempt with id=<attempt_id>.
image_type_errorThe audit image is of unsupported type.
unexpected_errorWe're sorry, but something went wrong.
Retrieve audit image
HTTP
Copy
GET /v3.2/auth/attempts/<ATTEMPT_ID>/image HTTP/1.1
Host: api.eu.onfido.com
Authorization: Token token=<YOUR_API_TOKEN>
Content-Type: application/json

https://api.eu.onfido.com/v3.2/auth/attempts/<ATTEMPT_ID>/image

Autofill BETA

POST
/v3.2/extractions

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

ParameterDescription
document_idrequired
The unique identifier of the uploaded document to run extraction on
Return information extracted from a document
HTTP
Copy
POST /v3.2/extractions HTTP/1.1
Host: api.eu.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:

FieldDescription
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. Only returned for a subset of documents.
subtypeThe document subtype (full, not_full, provisional). Only extracted on USA and UK Driving Licences
versionThe document issuing version. Only returned for a subset of documents.

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 to be present in the response.

FieldDescription
document_numberThe official document number.
first_nameFirst name.
last_nameLast name.
full_nameFull name.
spouse_nameSpouse name (French documents only).
widow_nameWidow name (French documents only).
alias_nameAlias name (French documents only).
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.
expiry_dateDate of expiry in YYYY-MM-DD format.
nationalityNationality in 3-letter ISO code.
mrz_line1Line 1 of the MRZ code.
mrz_line_1Line 1 of the MRZ code.
mrz_line2Line 2 of the MRZ code.
mrz_line_2Line 2 of the MRZ code.
mrz_line3Line 3 of the MRZ code.
mrz_line_3Line 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.
issuing_authorityIssuing authority.
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.
HTTP/1.1 201 Created
Content-Type: application/json

{
  "document_id": "<DOCUMENT_ID>",
  "document_classification": {
    "document_type": "driving_licence",
    "issuing_country": "USA",
    "issuing_state": "CA",
    "subtype": "full",
    "version": "2018"
  },
  "extracted_data": {
    "first_name": "JANE",
    "last_name": "DOE",
    "full_name": "JANE DOE",
    "date_of_birth": "1977-08-31",
    "document_number": "I1234568",
    "gender": "Female",
    "issuing_date": "2009-08-31",
    "date_of_expiry": "2014-08-31",
    "expiry_date": "2014-08-31",
    "address_line_1": "2570 24TH STREET",
    "address_line_2": "ANYTOWN, CA 95818",
    "document_type": "driving_licence",
    "issuing_country": "USA",
    "issuing_state": "CA",
}

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