Onfido LogoOnfido Logo

Developers

Overview

Get started (API v3.6)

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

You'll find migration guides in the API section.

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
1Authorization: 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 Smart 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. Please consider enabling GitHub's Secret Scanning and Push Protection feature when hosting your code on GitHub. This will help detect and safeguard Onfido API Tokens that could inadvertently be exposed in your repositories.

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 Smart 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 no longer be supported from October 24th 2022. You will not be able to use Mobile tokens with any version of the Onfido SDKs from this date. Please upgrade your integration to use SDK tokens. We recommend you do this as soon as possible to also allow time to update your application.

If you are on version 4.11.0 or below for Android, or 12.2.0 or below for iOS, you must upgrade to the latest SDK version in order to use SDK tokens.

If you need to generate Mobile tokens please contact Onfido's Customer Support.

Sandbox testing

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

Onfido has a sandbox environment for testing integrations before going live.

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

All of the API endpoints available in the live environment can be requested and tested in the sandbox. Sandbox results have the same response structures as live requests. You can also be notified of resource status changes via your registered webhooks.

The sandbox enables you to test:

  • your system's network connectivity with the Onfido API
  • all 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

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 the sandbox and live environments are:

  • sandbox request data is not processed by Onfido services or third parties, meaning that sandbox responses are faster than live responses
  • sandbox results are pre-determined
  • sandbox applicants are isolated from the live environment*
  • you won't be charged for sandbox test requests

* applicant notification emails still get sent out to sandbox applicants

Sample document and photo files

You can use the following sample files with the upload document endpoint for running test verification reports:

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

These files also work for testing the Onfido Smart Capture SDKs.

Simulating verification reports in the sandbox

To test your integration in the sandbox API, pre-determined responses can be generated for the following report types:

Pre-determined 'consider' results

Pre-determined responses can be generated by modifying the first_name and last_name parameters of the applicant object.

Using the Create Applicant API endpoint with a sandbox API token, set the last_name parameter to "Consider". Any verification report run against this applicant will return a consider response. For any other applicant last name, the response will be clear.

Next, create a workflow run for an active workflow using your sandbox token and the applicant_id for the applicant created using a modified last_name.

Lastly, copy the Smart Capture URL from the link object returned in the Workflow Run API payload, and paste it into your browser to complete the verification flow. Report results can be found in the status attribute returned by the Retrieve Workflow Run endpoint.

Create an applicant with last name of Consider
1POST /v3.6/applicants/ HTTP/1.1
2Host: api.eu.onfido.com
3Authorization: Token token=<YOUR_API_TOKEN>
4Content-Type: application/json
5
6{
7 "first_name": "Jane",
8 "last_name": "Consider"
9}

Simulating Document reports in the sandbox

The sandbox API supports additional functionality for testing Document reports. Pre-determined responses can be triggered 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 pre-determined 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 Document report breakdown and sub-breakdown combinations, create an applicant and set the first_name parameter to the "breakdown - sub-breakdown" combination you intend to trigger.

The following combinations are supported:

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

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.

You can also include a document type by specifying last_name as a supported sandbox document type during applicant creation (refer to the next section).

Trigger an Image Integrity - Supported Document breakdown combination for a Document report
1POST /v3.6/applicants/ HTTP/1.1
2Host: api.eu.onfido.com
3Authorization: Token token=<YOUR_API_TOKEN>
4Content-Type: application/json
5
6{
7 "first_name": "Image Integrity - Supported Document",
8 "last_name": "Smith"
9}

Document types

You can trigger responses for particular document types for sandbox Document reports, which include the specific properties for the associated document type.

To test different document types, create an applicant and set the last_name parameter to the document type you intend to test.

The sandbox supports the following document type 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 (refer to the previous section).

Trigger a Document report with US drivers license for California state
1POST /v3.6/applicants/ HTTP/1.1
2Host: api.eu.onfido.com
3Authorization: Token token=<YOUR_API_TOKEN>
4Content-Type: application/json
5
6{
7 "first_name": "Jane",
8 "last_name": "CA DL 2018"
9}

Sub-results

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

To do this, create an applicant and set the last_name parameter to one of the following strings:

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

When testing sub-results, you cannot specify a document type.

After creating an applicant to test the specific functionalities of a Document report described above (breakdowns and sub-breakdowns, document types or sub-results), you can use the applicant_id to create a workflow run to generate a pre-determined response as described above.

Trigger a rejected sub-result for a Document report
1POST /v3.6/applicants/ HTTP/1.1
2Host: api.eu.onfido.com
3Authorization: Token token=<YOUR_API_TOKEN>
4Content-Type: application/json
5
6{
7 "first_name": "Jane",
8 "last_name": "rejected"
9}

Simulating Facial Similarity reports in the sandbox

The sandbox API supports additional functionality for testing breakdowns and sub-breakdowns for Facial Similarity Photo, Photo Fully Auto, Video and Motion 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 pre-determined 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 Facial Similarity report breakdown and sub-breakdown combinations, create an applicant and set the first_name parameter to the "breakdown - sub-breakdown" combination you intend to trigger.

The following combinations are supported:

  • "Visual Authenticity - Spoofing Detection"
  • "Face Comparison - Face Match"
  • "Image Integrity - Source Integrity"
  • "Image Integrity - Face Detected"

After creating an applicant, you can use the applicant_id to create a workflow run to generate a pre-determined response as described above.

Trigger an Visual Authenticity - Spoofing Detection breakdown combination for a Facial Similarity report
1POST /v3.6/applicants/ HTTP/1.1
2Host: api.eu.onfido.com
3Authorization: Token token=<YOUR_API_TOKEN>
4Content-Type: application/json
5
6{
7 "first_name": "Visual Authenticity - Spoofing Detection",
8 "last_name": "Smith"
9}

Applicant IDs returned in the response don't map to actual sandbox applicants, they are example uuids to represent the applicant ID field. As a result, there is no associated applicant data.

Pre-determined responses for Repeat Attempts

The sandbox API supports additional functionality for testing breakdowns and sub-breakdowns for Repeat Attempts.

To help you integrate with this service, you can generate pre-defined Repeat Attempts responses. Depending on the scenario you are trying to test, you can use one of four possible keywords as the report_uuid in the request URL:

  • match
  • mismatch
  • error
  • empty
Trigger a Repeat Attempts match
1$ curl -X POST https://api.eu.onfido.com/v3.6/repeat_attempts/match \
2 -H 'Authorization: Token token=<YOUR_API_TOKEN>' \

Below is a pre-determined response example for a Repeat Attempts match:

json
1{
2 "report_id": "00000000-0000-0000-0000-000000000000",
3 "repeat_attempts": [
4 {
5 "report_id": "00000000-0000-0000-0000-000000000001",
6 "applicant_id": "00000000-0000-0000-0000-000000000003",
7 "date_of_birth": "match",
8 "names": "match",
9 "result": "clear",
10 "created_at": "2022-01-06T14:46:43Z",
11 "completed_at": "2022-01-06T15:46:43Z"
12 },
13 {
14 "report_id": "00000000-0000-0000-0000-000000000002",
15 "applicant_id": "00000000-0000-0000-0000-000000000003",
16 "date_of_birth": "match",
17 "names": "match",
18 "result": "clear",
19 "created_at": "2022-02-18T03:09:34Z",
20 "completed_at": "2022-02-18T03:10:34Z"
21 }
22 ],
23 "attempts_count": 3,
24 "attempts_clear_rate": 1,
25 "unique_mismatches_count": 0
26}

Sandbox testing with Profile Data Capture tasks

Studio workflows that start with a Profile Data Capture task must be handled differently when sandbox testing. As all of the fields in a Profile Data Capture task have a limit of 32 characters, the number of report scenarios that can be simulated is restricted.

After building and activating a valid workflow starting with a Profile Data Capture task, click "Share Smart Capture Link" on the workflow versions page in your Dashboard, copy the Sandbox link and paste it into your browser and complete the journey.

The breakdown and sub-breakdown combinations that can be tested for Document reports using workflows starting with a Profile Data Capture task by modifying the first_name parameter of the applicant include:

  • "Image Integrity - Image Quality"
  • "Visual Authenticity - Fonts"
  • "Data Consistency - Document Type"

The breakdown and sub-breakdown combinations that can be tested for Facial Similarity reports using workflows starting with a Profile Data Capture task by modifying the first_name parameter of the applicant include:

  • "Face Comparison - Face Match"
  • "Image Integrity - Face Detected"

Sandbox testing for API generated reports

For those not integrating using Onfido Studio, and instead generating verification reports using Onfido’s checks and reports API endpoints, sandbox testing works slightly differently.

After creating an applicant with a sandbox token and modified first_name and last_name parameters to test the various scenarios outlined above, you can use the applicant_id to create a check for the desired report.

The pre-determined sandbox results can be retrieved by making a Retrieve report call to the Onfido API.

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) when making a Create check API call.

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
1POST /v3.6/checks/ HTTP/1.1
2Host: api.eu.onfido.com
3Authorization: Token token=<YOUR_API_TOKEN>
4Content-Type: application/json
5
6{
7 "applicant_id": "<APPLICANT_ID>",
8 "report_names": [
9 "watchlist_standard",
10 "identity_enhanced"
11 ],
12 "consider": [
13 "watchlist_standard"
14 ]
15}

Postman collection

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

Run in Postman

The API version 3.6 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 in our Getting Started section 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 Onfido's Customer Support if you write your own library and want 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 second for all clients. Unless contractually agreed otherwise, the maximum rate is 400 requests per minute (up to 7 requests per second with a burst of 14 requests).

For sandbox requests, the rate limit is 120 requests per minute (up to 2 requests per second with a burst of 4 requests).

Onfido uses the token bucket algorithm to handle usage.

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

Rate limit reached error object
1HTTP/1.1 429 Too Many Requests
2Content-Type: application/json
3
4{
5 "error": {
6 "type": "rate_limit",
7 "message": "Rate limit exceeded. Please try again later."
8 }
9}

Regions

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

Initialization with region EU
1onfido = Onfido::API.new(
2 api_key: ENV['ONFIDO_API_KEY'],
3 region: :eu
4)

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
1onfido = Onfido::API.new(
2 api_key: ENV['ONFIDO_API_KEY'],
3 region: :us
4)

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

Initialization with region CA
1onfido = Onfido::API.new(
2 api_key: ENV['ONFIDO_API_KEY'],
3 region: :ca
4)
RegionNotesAPI base URLAPI token format
EUReplaces api.onfido.com for EU region in v3.1, v3.2, v3.3, v3.4, v3.5 and v3.6https://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.
CAhttps://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
2023-01-24General release of API version 3.6. Please see our release notes.

Upcoming maintenance

There's currently no scheduled maintenance.

Errors

All errors are returned with the same structure:

json
1{
2 "error": {
3 "type": <TYPE>,
4 "message": <MESSAGE>,
5 "fields": <FIELDS - NOT ALWAYS PRESENT>
6 }
7}

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.
Example validation error object
1HTTP/1.1 422 Unprocessable Entity
2Content-Type: application/json
3
4{
5 "error": {
6 "type": "validation_error",
7 "message": "",
8 "fields": {
9 "email": [
10 "invalid format"
11 ]
12 "name": [
13 "can't be blank"
14 ]
15 }
16 }
17}

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 Smart 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.
403 disabled_endpointThe API endpoint is disabled for your account. Please 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 missing_applicant_locationMake sure you've provided the applicant's location before starting a check
422 missing_applicant_provided_consentsMake sure you've provided the required consents
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 deprecated_reportsThe requested reports have been deprecated.
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.
422 disabled_reportsThere are reports disabled in your account. Please contact client-support@onfido.com.
422 too_many_checksYou have exceeded the limit of 1000 checks for the given 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.

Applicants with Sanctioned Documents

If an applicant uploads a document which is issued by a country subject to comprehensive US sanctions (list of countries here), any reports run with that applicant will return a withdrawn status unless otherwise specified in the report documentation. Current exceptions to this are the Document and Facial Similarity reports, which will still run but return a result indicating the presence of a sanctioned document.

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.
locationlocation object
The location/country of residence of the applicant.
phone_numberstring
The applicant's phone number with country code.

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, driving_licence, share_code, voter_id, passport and other (e.g. AUS Foreign Passport).
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.

Location object

The location object is nested inside the applicant object.

AttributeDescription
ip_addressstring
The IP address of the applicant.
country_of_residencestring
The 3 character ISO country code of the country where the applicant resides.

If country_of_residence is not provided in the request, it will be inferred from the IP address which may result in an incorrect value.

If you submitted location during document upload, it will not be returned here.

Note: location refers to the applicant's country of residence, not their nationality or place of birth.

Forbidden characters

For addresses the following characters are forbidden:

!$%^*=<>

For names the following characters are forbidden:

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

Example applicant object
1HTTP/1.1 201 Created
2Content-Type: application/json
3
4{
5 "id": "<APPLICANT_ID>",
6 "created_at": "2019-10-09T16:52:42Z",
7 "sandbox": true,
8 "first_name": "Jane",
9 "last_name": "Doe",
10 "email": null,
11 "dob": "1990-01-01",
12 "delete_at": null,
13 "href": "/v3.6/applicants/<APPLICANT_ID>",
14 "id_numbers": [],
15 "phone_number": "+44 7911 123456",
16 "address": {
17 "flat_number": null,
18 "building_number": null,
19 "building_name": null,
20 "street": "Second Street",
21 "sub_street": null,
22 "town": "London",
23 "state": null,
24 "postcode": "S2 2DF",
25 "country": "GBR",
26 "line1": null,
27 "line2": null,
28 "line3": null
29 },
30 "location": {
31 "ip_address": "127.0.0.1",
32 "country_of_residence": "GBR"
33 }
34}

Create applicant

POST
/v3.6/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. You should remove any duplicate whitespaces before creating an applicant, otherwise this may result in a data comparison failure.

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.
phone_numberoptional
The applicant's phone number with country code.
locationoptional
An object that contains the location/country of residence of the applicant.
consentsoptional
An array of objects indicating whether consent has been given by the applicant.

location

You must provide location for every applicant. If you do not, all checks with a Facial Similarity report will fail with a validation error.

You must provide location information for each end user as this determines the necessary consent required in order to process a verification.

You can specify either or both the IP address and the country of residence (3 character ISO country code) of the applicant in the location object.

bash
1...
2"location": {
3 "ip_address": "127.0.0.1",
4 "country_of_residence": "GBR"
5 }
6...

You can also provide location information during document upload.

If you submit location information in multiple requests, the document upload location will take precedence.

If you use the Onfido SDK, location is provided directly by the SDK. You do not need to manually submit the location parameter in this case.

consents

Where required, you must collect end user consent before creating a check with Onfido. If you do not, Onfido is unable to process an applicant's data and complete a verification.

Exact consent requirements are linked to the location of the end user and the report type. You must specify an applicant's location in the location parameter when creating an applicant or uploading a document.

  • privacy_notices_read

End users located in the United States, must read the Privacy Notices and Terms of Service before giving consent for Onfido.

granted should be set to true after gaining the necessary consent from the applicant. If it's set to false, or the parameter is not provided, all check creation requests will fail with a validation error.

For more information on the requirements and implementation options for collecting US end user consent, please see our Onfido privacy notices and consent guide.

  • ssn_verification

End users must give consent to process their Social Security Number (SSN) before you can submit an Identity Enhanced report.

granted should be set to true after gaining the necessary consent from the applicant. If it's set to false, or the parameter is not provided, SSN reports will fail with a validation error.

  • phone_number_verification

End users must give consent to process their phone number before you can submit a Phone Verification report.

granted should be set to true after gaining the necessary consent from the applicant. If it's set to false, or the parameter is not provided, Phone Verification reports will fail with a validation error.

bash
1...
2"consents": [
3 {
4 "name": "privacy_notices_read",
5 "granted": true
6 },
7 {
8 "name": "ssn_verification",
9 "granted": true
10 },
11 {
12 "name": "phone_number_verification",
13 "granted": true
14 }
15 ]
16...

You can also provide consents when updating an applicant.

If you use the Onfido SDK, consent is collected directly by the SDK. The SDK contains a mandatory consent screen which the end user must accept in order to proceed. You do not need to manually provide the consents parameter in this case.

Create an applicant
1POST /v3.6/applicants/ HTTP/1.1
2Host: api.eu.onfido.com
3Authorization: Token token=<YOUR_API_TOKEN>
4Content-Type: application/json
5
6{
7 "first_name": "Jane",
8 "last_name": "Doe",
9 "dob": "1990-01-31",
10 "address": {
11 "building_number": "100",
12 "street": "Main Street",
13 "town": "London",
14 "postcode": "SW4 6EH",
15 "country": "GBR"
16 }
17}

Retrieve applicant

GET
/v3.6/applicants/{applicant_id}

Retrieves a single applicant. Returns an applicant object.

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

Update applicant

PUT
/v3.6/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
1PUT /v3.6/applicants/<APPLICANT_ID> HTTP/1.1
2Host: api.eu.onfido.com
3Authorization: Token token=<YOUR_API_TOKEN>
4Content-Type: application/json
5
6{
7 "first_name": "New",
8 "last_name": "Name"
9}

Delete applicant

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

Restore applicant

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

List applicants

GET
/v3.6/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 (500 at maximum). 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.5/applicants?page=3059](https://api.eu.onfido.com/v3.5/applicants?page=3059); rel="last", [https://api.eu.onfido.com/v3.5/applicants?page=2](https://api.eu.onfido.com/v3.5/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 youve created
1GET /v3.6/applicants?page=1&per_page=5 HTTP/1.1
2Host: api.eu.onfido.com
3Authorization: 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.
Example document object
1HTTP/1.1 201 Created
2Content-Type: application/json
3
4{
5 "id": "<DOCUMENT_ID>",
6 "created_at": "2019-02-11T13:49:20Z",
7 "file_name": "sample_driving_licence.png",
8 "file_type": "png",
9 "file_size": 490408,
10 "type": "driving_licence",
11 "side": "front",
12 "issuing_country": null,
13 "applicant_id": "<APPLICANT_ID>",
14 "href": "/v3.6/documents/<DOCUMENT_ID>",
15 "download_href": "/v3.6/documents/<DOCUMENT_ID>/download"
16}

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.6/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.
locationoptional
An object that contains the location/country of residence of the applicant.
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.

location

You must provide location for every applicant. If you do not, all checks will fail with a validation error.

You must provide location information for each end user as this determines the necessary consent required in order to process a verification.

You can specify either or both the IP address and the country of residence (3 character ISO country code) of the applicant in the location object.

bash
1...
2-F 'location[ip_address]=127.0.0.1' \
3-F 'location[country_of_residence]=GBR'
4...

You can also provide location information during applicant creation.

If you submit location information in multiple requests, the document upload location will take precedence.

If you submit location information during document upload, this will not be returned in the applicant object.

If you use the Onfido SDK, location is provided directly by the SDK. You do not need to manually submit the location parameter in this case.

Image quality

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
1POST /v3.6/documents/ HTTP/1.1
2Host: api.eu.onfido.com
3Authorization: Token token=<YOUR_API_TOKEN>
4Content-Type: multipart/form-data

Retrieve document

GET
/v3.6/documents/{document_id}

Retrieves a single document. Returns a document object.

1GET /v3.6/documents/<DOCUMENT_ID> HTTP/1.1
2Host: api.eu.onfido.com
3Authorization: Token token=<YOUR_API_TOKEN>

List documents

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

Download document

GET
{'/v3.6/documents/{document_id}/download'}

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

Download a document associated with an applicant
1GET /v3.6/documents/<DOCUMENT_ID>/download HTTP/1.1
2Host: api.eu.onfido.com
3Authorization: Token token=<YOUR_API_TOKEN>

Download NFC face

GET
{'/v3.6/documents/{document_id}/nfc_face'}

Downloads digital photos extracted from specific documents belonging to an applicant. If successful, the response will be the binary data representing the image.

Download the face extracted from an NFC document associated with an applicant
1GET /v3.6/documents/<DOCUMENT_ID>/nfc_face HTTP/1.1
2Host: api.eu.onfido.com
3Authorization: Token token=<YOUR_API_TOKEN>

Download document video

GET
{'/v3.6/documents/{document_id}/video/download'}

Downloads a document video. If successful, the response will be the binary data representing the video.

Download a document video
1GET /v3.6/documents/<DOCUMENT_ID>/video/download HTTP/1.1
2Host: api.eu.onfido.com
3Authorization: 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.
Example live photo object
1HTTP/1.1 201 Created
2Content-Type: application/json
3
4{
5 "id": "<LIVE_PHOTO_ID>",
6 "created_at": "2019-10-09T16:59:06Z",
7 "file_name": "<FILE_NAME>.png",
8 "file_type": "image/png",
9 "file_size": 536630,
10 "href": "/v3.6/live_photos/<LIVE_PHOTO_ID>",
11 "download_href": "/v3.6/live_photos/<LIVE_PHOTO_ID>/download"
12}

Upload live photo

POST
/v3.6/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, jpeg 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
1POST /v3.6/live_photos/ HTTP/1.1
2Host: api.eu.onfido.com
3Authorization: Token token=<YOUR_API_TOKEN>
4Content-Type: multipart/form-data

Retrieve live photo

GET
{'/v3.6/live_photos/{live_photo_id}'}

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

Retrieve a single live photos object
1GET /v3.6/live_photos/<LIVE_PHOTO_ID> HTTP/1.1
2Host: api.eu.onfido.com
3Authorization: Token token=<YOUR_API_TOKEN>

List live photos

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

Download live photo

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

Live videos

Live videos are footage of the applicant's face, recorded and uploaded by the Onfido Smart 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.
Example live video object
1HTTP/1.1 201 Created
2Content-Type: application/json
3
4{
5 "id": "<LIVE_VIDEO_ID>",
6 "created_at": "2018-05-14T16:44:53Z",
7 "href": "/v3.6/live_videos/<LIVE_VIDEO_ID>",
8 "download_href": "/v3.6/live_videos/<LIVE_VIDEO_ID>/download",
9 "file_name": "<FILE_NAME>.mp4",
10 "file_type": "video/mp4",
11 "file_size": 1431121,
12 "challenge": [
13 {
14 "type": "recite",
15 "query": [
16 1,
17 2,
18 3
19 ]
20 },
21 {
22 "type": "movement",
23 "query": "turnRight"
24 }
25 ]
26}

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 Smart Capture SDKs (iOS, Android or Web).

Retrieve live video

GET
/v3.6/live_videos/{live_video_id}

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

Retrieve a single live videos object
1GET /v3.6/live_videos/<LIVE_VIDEO_ID> HTTP/1.1
2Host: api.eu.onfido.com
3Authorization: Token token=<YOUR_API_TOKEN>

List live videos

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

Download live video

GET
/v3.6/live_videos/{live_video_id}/download

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

Download the data representing a live video
1GET /v3.6/live_videos/<LIVE_VIDEO_ID>/download HTTP/1.1
2Host: api.eu.onfido.com
3Authorization: Token token=<YOUR_API_TOKEN>

Download live video frame

GET
/v3.6/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.

This will be the frame extracted from the video where the end user is facing the camera. If no face can be detected, it will fallback to the first frame of the video.

Download the data representing a live video frame
1GET /v3.6/live_videos/<LIVE_VIDEO_ID>/frame HTTP/1.1
2Host: api.eu.onfido.com
3Authorization: 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.

Unsuccessful frame extraction response: failure
1HTTP/1.1 422 Unprocessable Entity
2Content-Type: application/json
3
4{
5 "error": {
6 "type": "frame_extraction_failed",
7 "message": "<Reason>"
8 }
9}

Frame extraction unavailable

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

Unsuccessful frame extraction response: temporarily unavailable
1HTTP/1.1 503 Service Unavailable
2Content-Type: application/json
3
4{
5 "error": {
6 "type": "frame_extraction_unavailable",
7 "message": "Frame extraction is temporarily unavailable"
8 }
9}

Workflow Runs

Workflows are the container for how the end user will be verified using interactive and non-interactive tasks as configured using the Studio via the Onfido Dashboard. Workflow Runs are individual instances of the Workflow, and each Workflow Run requires data in order for it to execute.

The required Workflow Run data will be based on how the Workflow is configured in Onfido Studio. Data can either be provided through the Applicant Object and/or through the Custom Input Data Object.

Workflow Run Versions

Workflows are version controlled, meaning everytime a Workflow is edited and saved a new version is created. The active version of the Workflow will be used during the creation of a Workflow Run. Workflow Runs can only be created against the active version of the Workflow. The active version of a workflow can be designated in Studio via the Onfido Dashboard.

Workflow Run Status

Workflow Runs are transitioned through statuses as the Applicant progresses through the tasks. These statuses are visible on the Dashboard and available via the Retrieve Workflow Run endpoint.

Workflow StatusDescription
awaiting_inputWhen the Workflow is waiting for an Applicant to complete a Smart Capture SDK interactive task.
Note: If your Workflow has parallel tasks, awaiting_input will take precedence over processing.
processingWhen the Workflow is processing non-interactive tasks.
abandonedWhen an interactive task times out, the Workflow will be abandoned. Time outs can be configured per task in the Studio via Onfido Dashboard.
errorThe Workflow ended due to a technical issue during run time.
approvedThe Workflow Run reached an end task of ‘Approve Applicant’ based on the Workflow configuration.
reviewThe Workflow Run reached an end task of ‘Review Applicant’ based on the Workflow configuration.
declinedThe Workflow Run reached an end task of ‘Decline Applicant’ based on the Workflow configuration.

Workflow Run object

AttributeDescription
idstring (UUID)
The unique identifier for the Workflow Run.
applicant_idstring (UUID)
The unique identifier for the Applicant.
workflow_idstring (UUID)
The unique identifier for the Workflow.
workflow_version_idint
The identifier for the Workflow Version.
dashboard_urlstring
The URL for viewing the workflow run results on your Onfido Dashboard.
statusstring (enum)
The status of the Workflow Run. Possible values are: processing, awaiting_input, approved, declined, review, abandoned and error.
tagsarray of strings
A list of tags associated with the Workflow Run.
outputoutput object
Output object contains all of the properties configured on the workflow version.
reasonsarray (string)
The reasons the Workflow Run outcome was reached. Configurable when creating the Workflow Version.
errorerror object
Error object. Only set when the Workflow Run status is error.
linklink object
Link object.
created_atdatetime (ISO-8601)
The date and time when the Workflow Run was created.
updated_atdatetime (ISO-8601)
The date and time when the Workflow Run was last updated.

Output object

Workflow output data is a configurable set of properties which allows you to add any specific data attribute contained within a Workflow. Workflow Output information must be first created as a property in Studio using the Workflow input and output configuration tab. Once the properties are created then these need to be mapped on the end tasks. This gives full flexibility to add as little or as much detailed information to the Retrieve Workflow Run endpoint.

This is the recommended method to integrate with our API to get information into your systems.

Reasons

Workflow reasons are set during Workflow creation in Studio. Each end task can have one or more reasons configured by the user. This provides the flexibility to capture more information about why an end user reached a specific end state.

For example, if a workflow contains multiple approval end tasks, the reasons field can be used to clearly identify which path the end user completed.

Error object

Error object that details why a Workflow Run is in Error status.

AttributeDescription
type**string **
The type of the error.
message**string **
A textual description of the error.

Object for the configuration of the Workflow Run link.

AttributeDescription
url**string **
Link to access the Workflow Run without the need to integrate with Onfido's SDKs.
completed_redirect_url**string **
When the interactive section of the Workflow Run has completed successfully, the user will be redirected to this URL instead of seeing the default Onfido "thank you" page.
expired_redirect_url**string **
When the Link has expired, the user will be immediately redirected to this URL instead of seeing the default Onfido error message.
expires_atstring (ISO-8601)
Date and time when the link will expire. Additional details.
languagestring (enum)
The code for the language when the Workflow Run is acessed using the link.
Example Workflow Run object
1HTTP/1.1 201 Created
2Content-Type: application/json
3
4{
5 "id": "<WORKFLOW_RUN_ID>",
6 "applicant_id": "<APPLICANT_ID>",
7 "workflow_id": "<WORKFLOW_ID>",
8 "workflow_version_id": 11,
9 "status": "approved",
10 "dashboard_url":"https://dashboard.onfido.com/results/<WORKFLOW_RUN_ID>"
11 "output": {"prop1": "val_1", "prop2": 10},
12 "reasons": ["reason_1", "reason_2"],
13 "tags": [],
14 "error": null,
15 "created_at": "2022-06-28T15:39:42Z",
16 "updated_at": "2022-07-28T15:40:42Z",
17 "link": {
18 "completed_redirect_url": "https://example.onfido.com",
19 "expired_redirect_url": "https://example.onfido.com",
20 "expires_at": "2022-10-17T14:40:50Z",
21 "language": "en_US",
22 "url": "https://eu.onfido.app/l/<WORKFLOW_RUN_ID>"
23 },
24}

Create Workflow Run

POST
/v3.6/workflow_runs/

Creates and starts a Workflow Run. Returns a Workflow Run object.
A Workflow must exist and be activated before you can create a Workflow Run. You can create and activate your Workflow in your Studio via Onfido Dashboard. An Applicant ID is mandatory for creating a Workflow Run.
Any data that you want to provide to be used in the Workflow Run can be passed in two ways at its creation:

You must request a Workflow Run before you initialise the SDK.

Request body parameters

ParameterDescription
workflow_idrequired string (UUID)
The unique identifier for the Workflow.
applicant_idrequired string (UUID)
The unique identifier for the Applicant.
tagsoptional
Array of tags being assigned to the Workflow Run.
custom_dataoptional custom data object
Object with Custom Input Data to be used in the Workflow Run.
linkoptional link object
Link object to configure the Workflow Run link.

Applicant Data

The Workflow Run requires an Applicant ID, meaning that the Workflow is able to access information stored in the Applicant.

Before being able to use that data within the Workflow Run, you must specify which Applicant fields you intend to use by configuring the Input Data via Studio. The additional Applicant fields you decide to use become mandatory and the Workflow Run create endpoint will validate if they are present before creating the Workflow Run. You can manage the Applicant using the create and update endpoints.

Custom Input Data

If you have business-specific data that you want to use during your workflow, you can configure Custom Input Data using the Studio via the Onfido Dashboard.

If Custom Input Data is configured, then it becomes mandatory when creating a Workflow Run.

Object for the configuration of the Workflow Run link.

AttributeDescription
completed_redirect_urloptional string
When the interactive section of the Workflow Run has completed successfully, the user will be redirected to this URL instead of seeing the default Onfido "thank you" page.
expired_redirect_urloptional string
When the Link has expired, the user will be immediately redirected to this URL instead of seeing the default Onfido error message.
expires_atoptional string (ISO-8601)
Date and time when the link will expire. Additional details.
language**optional ** string (enum)
The code for the language when the Workflow Run is accessed using the link. Defaults to en_US if not specified.

Supported languages

You can customize the language attribute of the link object for when the Workflow Run is accessed using the link by including the corresponding country code (fr for French, for example).

You can find a complete list of Onfido's 44 supported languages and their relevant codes in our SDK customisation guide.

When the link expires, the Applicant won't be able to use it anymore to access the Workflow Run journey. If no expiration date and time is set, the link will be acessible until the Workflow Run reaches an end state (abandoned, error, approved, review and declined).

Create Workflow Run
1POST /v3.6/workflow_runs HTTP/1.1
2Host: api.eu.onfido.com
3Authorization: Token token=<YOUR_API_TOKEN>
4Content-Type: application/json
5
6{
7 "workflow_id": "<WORKFLOW_ID>",
8 "applicant_id": "<APPLICANT_ID"
9}

List Workflow Runs

GET
/v3.6/workflow_runs

Retrieves the Workflow Runs of the client. Returns a list of Workflow Run objects. The page size is 20 objects.

Query String parameters

page (optional): The number of the page to be retrieved. If not specified, defaults to 1.
status (optional): a list of comma separated status values to filter the results.
tags (optional): a list of comma separated tags to filter the results.
created_at_gt (optional): a ISO-8601 date to filter results with a created date greater than (after) the one provided.
created_at_lt (optional): a ISO-8601 date to filter results with a created date less than (before) the one provided.
sort (optional): a string with the value desc or asc that allows to sort the returned list by the completed datetime either descending or ascending, respectively. If not specified, defaults to desc.

List Workflow Runs
1GET /v3.6/workflow_runs HTTP/1.1
2Host: api.eu.onfido.com
3Authorization: Token token=<YOUR_API_TOKEN>

Retrieve Workflow Run

GET
/v3.6/workflow_runs/{workflow_run_id}

Retrieves a Workflow Run. Returns a Workflow Run object.

Path parameters

workflow_run_id (required): the unique identifier of the Workflow Run you want to retrieve.

Retrieve Workflow Run
1GET /v3.6/workflow_runs/<WORKFLOW_RUN_ID> HTTP/1.1
2Host: api.eu.onfido.com
3Authorization: Token token=<YOUR_API_TOKEN>

Retrieve Workflow Run Evidence Summary File

GET
/v3.6/workflow_runs/{workflow_run_id}/evidence_summary_file

Retrieves the evidence summary file for the designated Workflow Run.

After a successful call, a 302 Found HTTP status is returned with a pre-signed URL to download the file in the Location header.

The evidence summary file is available a few seconds after the Workflow Run has been completed. Please also ensure that file generation is enabled for your account. See the ETSI Certified IDV product guide for more information.

Note: If you invoke this endpoint for Sandbox workflow runs, a mock evidence summary file will be returned.

Path parameters

workflow_run_id (required): the unique identifier of the Workflow Run for which you want to retrieve the evidence summary file.

Note: The Evidence Summary File may contain sensitive personal identifiable information (PII). The pre-signed URLs allow downloading the Evidence Summary File and should be handled carefully.

Retrieve Workflow Run Evidence Summary File
1GET /v3.6/workflow_runs/<WORKFLOW_RUN_ID>/evidence_summary_file HTTP/1.1
2Host: api.eu.onfido.com
3Authorization: Token token=<YOUR_API_TOKEN>

Tasks

Tasks are the individual steps that make up a Workflow Run. Tasks may require Task input data in order to execute, and will return Task output data on completion. Task input data can be managed by selecting a Task and configuring it in the input tab in Studio. The Task endpoints are designed to enable auditability and transparency of Workflow Runs by providing Task input and output.

Tasks are versioned using unique Task Definitions so that each time enhancements, new features or bugs are released, the functioning of these Tasks remains unchanged, preserving the integrity of the previous version of the Workflow. Task inputs and outputs may change between Task versions.

The Task input and output information is accessible directly in Studio and should be used to configure an applicant's verification journey using the condition tasks. For example, Tasks output data can be used to decide the next Tasks to perform, or the end state of the Applicant verification journey directly within Studio.

Despite this data being available and accessible through these endpoints, it also comes with some drawbacks. If changes are made to the Workflow, or individual Tasks are updated (new features, bug fixing, for example), the schemas may change, which could break previous integrations.

As such, Task endpoints are not recommended to be used as an integration method to retrieve data, please use the Output object in Workflow Run.

Task object

AttributeDescription
idstring
The identifier for the Task.
task_def_idstring
The identifier for the Task Definition.
task_def_versionstring
The version for the Task Definition.
workflow_run_idstring (UUID)
The identifier for the Workflow Run to which the task belongs.
inputobject
Input object with the fields used by the Task to execute.
outputobject
Output object with the fields produced by the Task execution.
created_atdatetime (ISO-8601)
The date and time when the Task was created.
updated_atdatetime (ISO-8601)
The date and time when the Task was last updated.
Example Task object
1HTTP/1.1 201 Created
2Content-Type: application/json
3
4{
5 "id": "<TASK_ID>",
6 "task_def_id": "<TASK_DEF_ID>",
7 "task_def_version": "<TASK_DEF_VERSION>",
8 "workflow_run_id": "<WORKFLOW_RUN_ID>",
9 "input": {"document_ids":["dd1a606c-787f-4203-8e71-7d4c9adb090d"]},
10 "output": {"extracted_data": {"first_name": "Jane", "last_name": "Doe"}},
11 "created_at": "2022-06-28T15:39:42Z",
12 "updated_at": "2022-07-28T15:40:42Z",
13}

List Tasks

GET
/v3.6/workflow_runs/{workflow_run_id}/tasks

Retrieves the Tasks of a Workflow Run. Returns a subset of the Task object.

The response contains only Tasks that were already started or completed, ordered by the created_at field, in ascending order.

Path parameters

workflow_run_id (required): the unique identifier of the Workflow Run to which the Tasks belong.

Example response

json
1[
2 {
3 "id": "<TASK_ID>",
4 "task_def_id": "<TASK_DEF_ID>",
5 "workflow_run_id": "<WORKFLOW_RUN_ID>",
6 "created_at": "2022-06-28T15:39:42Z",
7 "updated_at": "2022-07-28T15:39:52Z",
8 },
9 {
10 "id": "<TASK_ID>",
11 "task_def_id": "<TASK_DEF_ID>",
12 "workflow_run_id": "<WORKFLOW_RUN_ID>",
13 "created_at": "2022-06-28T15:40:42Z",
14 "updated_at": "2022-07-28T15:40:52Z",
15 }
16 ...
17]
List Tasks
1GET /v3.6/workflow_runs/<WORKFLOW_RUN_ID>/tasks HTTP/1.1
2Host: api.eu.onfido.com
3Authorization: Token token=<YOUR_API_TOKEN>

Retrieve Task

GET
/v3.6/workflow_runs/{workflow_run_id}/tasks/{task_id}

Retrieves a Task. Returns a Task object.

Path parameters

workflow_run_id (required): the unique identifier of the Workflow Run to which the Task belongs.
task_id (required): the identifier of the Task you want to retrieve.

Note: The output property of the returned task object can be null, under the following circumstances:

  • the task is still ongoing
  • the task completes but does not require any output
  • the task failed, or the workflow run was cancelled before it completed
Retrieve Task
1GET /v3.6/workflow_runs/<WORKFLOW_RUN_ID>/tasks/<TASK_ID> HTTP/1.1
2Host: api.eu.onfido.com
3Authorization: Token token=<YOUR_API_TOKEN>

Complete Task

POST
/v3.6/workflow_runs/{workflow_run_id}/tasks/{task_id}/complete

Completes a Send / Receive Data Task.

Path parameters

workflow_run_id (required): the unique identifier of the Workflow Run to which the Task belongs.
task_id (required): the identifier of the Task you want to complete.

Request body parameters

ParameterDescription
datarequired object
The Task completion payload. More details below.

Send / Receive Data Tasks

Send / Receive Data Tasks are a special type of Task that allow you to create custom actions that can be executed anywhere in a workflow. You can send data out of the system mid workflow and pass data back in to be used in more logic tasks.

You can configure a Send / Receive Data Task in the Workflow Builder, while defining your Workflow. When configuring a Send / Receive Data Task, you should define the input and output data it expects. The logic necessary to process the inputs and produce the outputs is up to the service being called.

The recommended way of integrating a Send / Receive Data Task is configuring a workflow_task.started Webhook, so you can be notified when the task is ready to execute. The payload of this Webhook contains all the inputs you have defined for your Task.

Once notified by our Webhook, your system can asynchronously run any custom action you want to produce the desired outputs. Once ready, you should invoke the Complete Task endpoint, providing as data parameter an object with the outputs you have defined. Our system will validate the provided data against the output schema you have defined when configuring the Send / Receive Data Task and return an HTTP 422 error if they don't match.

If the submission of the data is successful, the Send / Receive Data Task will be completed and the Workflow will proceed. All data received back into the Workflow Run will be able to be used in our condition logic tasks.

You can configure as many Send / Receive Data Tasks as you want in your Workflow.

Complete Task
1POST /v3.6/workflow_runs/<WORKFLOW_RUN_ID>/tasks/<TASK_ID>/complete HTTP/1.1
2Host: api.eu.onfido.com
3Authorization: Token token=<YOUR_API_TOKEN>
4Content-Type: application/json
5
6{
7 "data":{
8 "field_1": "value_1",
9 "field_2": "value_2"
10 }
11}

Motion captures

Motion captures are representations of an applicant's face, recorded and uploaded by the Onfido Smart Capture SDKs (iOS, Android or Web), at the same time as the document image is captured—also by the SDKs. These captures are used for Facial Similarity Motion reports.

Motion capture object

AttributeDescription
idstring
The unique identifier of the motion capture.
created_atdatetime (ISO-8601)
The date and time at which the motion capture was uploaded.
hrefstring
The URI of this resource.
download_hrefstring
The URI that can be used to download a motion capture.
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.
Example motion capture object
1HTTP/1.1 201 Created
2Content-Type: application/json
3
4{
5 "id": "<MOTION_CAPTURE_ID>",
6 "created_at": "2022-11-12T17:12:44Z",
7 "href": "/v3.6/motion_captures/<MOTION_CAPTURE_ID>",
8 "download_href": "/v3.6/motion_captures/<MOTION_CAPTURE_ID>/download",
9 "file_name": "<FILE_NAME>.mp4",
10 "file_type": "video/mp4",
11 "file_size": 1431121
12}

Upload motion capture

Motion captures 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 motion capture endpoint.

To upload motion captures for Facial Similarity Motion reports, integrate with one of our Smart Capture SDKs (iOS, Android or Web).

Retrieve motion capture

GET
https://api.onfido.com/v3.6/motion_captures/{motion_capture_id}

Retrieves a single motion capture. Returns the corresponding motion capture object.

Retrieve a single motion capture object
1GET /v3.6/motion_captures/<MOTION_CAPTURE_ID> HTTP/1.1
2Host: api.onfido.com
3Authorization: Token token=<YOUR_API_TOKEN>

List motion captures

GET
https://api.onfido.com/v3.6/motion_captures?applicant_id={applicant_id}

Lists all the motion captures that belong to an applicant.

Returns data in the form: {"motion_captures": [<LIST_OF_MOTION_CAPTURE_OBJECTS>]}.

Query string parameters

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

List all motion captures for a specific applicant
1GET /v3.6/motion_captures?applicant_id=<APPLICANT_ID> HTTP/1.1
2Host: api.onfido.com
3Authorization: Token token=<YOUR_API_TOKEN>

Download motion capture

GET
https://api.onfido.com/v3.6/motion_captures/{motion_capture_id}/download

Downloads a motion capture. Returns the binary data representing the motion capture.

Download the data representing a motion capture
1GET /v3.6/motion_captures/<MOTION_CAPTURE_ID>/download HTTP/1.1
2Host: api.onfido.com
3Authorization: Token token=<YOUR_API_TOKEN>

Download motion capture frame

GET
https://api.onfido.com/v3.6/motion_captures/{motion_capture_id}/frame

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

Download the data representing a motion capture frame
1GET /v3.6/motion_captures/<MOTION_CAPTURE_ID>/frame HTTP/1.1
2Host: api.onfido.com
3Authorization: Token token=<YOUR_API_TOKEN>

Unsuccessful frame extraction

Frame extraction failed

If a frame cannot be extracted from the motion capture, a frame_extraction_failed response will be returned.

Unsuccessful frame extraction response: failure
1HTTP/1.1 422 Unprocessable Entity
2Content-Type: application/json
3
4{
5 "error": {
6 "type": "frame_extraction_failed",
7 "message": "<Reason>"
8 }
9}

Frame extraction unavailable

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

Unsuccessful frame extraction response: temporarily unavailable
1HTTP/1.1 503 Service Unavailable
2Content-Type: application/json
3
4{
5 "error": {
6 "type": "frame_extraction_unavailable",
7 "message": "Frame extraction is temporarily unavailable"
8 }
9}

Monitors

Monitors are used for Ongoing Monitoring of an applicant and must be used together with Watchlist Reports. They listen for changes to Watchlist reports and when an update is detected, a new Check and corresponding Watchlist Report are created. Learn more about this feature here.

If you are interested in using this feature, it must first be enabled for your account. Please reach out to your CSM or email our Client Support team.

Monitor object

AttributeDescription
idstring
The unique identifier for the monitor.
created_atdatetime
The date and time at which the monitor was created.
deleted_atdatetime
The date and time at which the monitor was deleted. If the monitor is still active, this field will be null.
applicant_idstring
The ID for the applicant associated with the monitor.
report_namestring
The name of the report type the monitor creates. Can be either "watchlist_standard" or "watchlist_aml".
tagsarray of strings
A list of tags associated with this monitor. These tags will be applied to each check this monitor creates.
sandboxboolean
Indicates whether the object was created in the sandbox or not.
Example monitor object
1HTTP/1.1 201 Created
2Content-Type: application/json
3
4{
5 "id": “<MONITOR_ID>”,
6 "applicant_id": "<APPLICANT_ID>",
7 "report_name": "watchlist_standard",
8 "created_at": "2022-09-01T15:01:36.921Z",
9 "deleted_at": null,
10 "sandbox": false,
11 "tags": []
12}

Create monitor

POST
/v3.6/watchlist_monitors/

Creates a new monitor for the applicant.

Once created, the monitor will create an initial Watchlist report under the given applicant.

Only one active monitor can be created per applicant.

Request body parameters

ParameterDescription
applicant_idrequired
The ID for the applicant associated with the monitor.
report_namerequired
The name of the report type the monitor creates. Can be either "watchlist_standard" or "watchlist_aml".
tagsoptional
A list of tags associated with this monitor. These tags will be applied to each check this monitor creates.
Create a monitor
1POST /v3.6/watchlist_monitors/ HTTP/1.1
2Host: api.eu.onfido.com
3Authorization: Token token=<YOUR_API_TOKEN>
4Content-Type: application/json
5
6{
7 "applicant_id": "<APPLICANT_ID>",
8 "report_name": "watchlist_aml"
9}

Retrieve monitor

GET
/v3.6/watchlist_monitors/{monitor_id}

Retrieves a single monitor. Returns a monitor object.

Retrieve a single monitor
1GET /v3.6/watchlist_monitors/<MONITOR_ID> HTTP/1.1
2Host: api.eu.onfido.com
3Authorization: Token token=<YOUR_API_TOKEN>

List monitors

GET
/v3.6/watchlist_monitors?applicant_id={applicant_id}

Returns all available monitors for an applicant. Returns data in the form: {"monitors": [<LIST_OF_MONITOR_OBJECTS>]}.

Query string parameters

ParameterDescription
applicant_idoptional
The ID of the applicant whose monitors you want to list. If omitted, all monitors for the account will be listed.
include_deletedoptional
If this option is included, deleted (inactive) monitors will also be included in the list.
List all monitors associated with an applicant
1GET /v3.6/watchlist_monitors?applicant_id=<APPLICANT_ID> HTTP/1.1
2Host: api.eu.onfido.com
3Authorization: Token token=<YOUR_API_TOKEN>

Delete monitor

DELETE
/v3.6/watchlist_monitors/{monitor_id}

Deactivates the given monitor. No further updates will be given on this monitor, and all search information for this monitor will be deleted. Reports that have already been generated by the monitor will still exist.

Once a monitor is deleted, it cannot be re-activated.

If a monitor on an applicant was deleted in error, a new monitor will need to be created.

Delete a monitor
1DELETE /v3.6/watchlist_monitors/<MONITOR_ID> HTTP/1.1
2Host: api.eu.onfido.com
3Authorization: Token token=<YOUR_API_TOKEN>

List matches (BETA)

GET
/v3.6/watchlist_monitors/<MONITOR_ID>/matches

Gets a list of match IDs on this monitor, as well as their enabled/disabled status.

Match IDs are also visible in the report properties of monitored watchlist reports.

This will NOT return details about each match. (Such as name, media links, match type, etc.) This will only return the IDs and enabled/disabled status.

Match details are only viewable on reports generated by the monitor.

bash
1HTTP/1.1 200 Success
2Content-Type: application/json
3
4{
5 "matches": [
6 {
7 "id": <MATCH_ID>,
8 "enabled": true
9 },
10 {
11 "id": <MATCH_ID>,
12 "enabled": false
13 },
14 ...
15 ]
16}
List match IDs associated with a monitor
1GET /v3.6/watchlist_monitors/<MONITOR_ID>/matches HTTP/1.1
2Host: api.eu.onfido.com
3Authorization: Token token=<YOUR_API_TOKEN>

Set match status (BETA)

PATCH
/v3.6/watchlist_monitors/<MONITOR_ID>/matches

Update the enabled status of the given matches.

Matches that are disabled will no longer contribute to overall results in future reports generated by this monitor.

Additionally, any updates to disabled matches will no longer trigger a new report to be generated.

Request body parameters

ParameterDescription
enableoptional
Array of match IDs to set to enable: true.
disableoptional
Array of match IDs to set to enable: false.

If no match IDs are provided, a 204 No Content response is returned.

If the same ID is provided to both the “enable” and “disable” lists, a 422 validation_error is returned. The “fields” messages in this case will be the list of IDs that are duplicated.

If any of the IDs in either the “enable” or “disable” lists are invalid (or pertain to matches that are not on the given monitor), a 422 validation_error is returned. The “fields” messages in this case will be the list of IDs that are invalid.

Disable matches for a monitor
1PATCH /v3.6/watchlist_monitors/<MONITOR_ID>/matches HTTP/1.1
2Host: api.eu.onfido.com
3Authorization: Token token=<YOUR_API_TOKEN>
4Content-Type: application/json
5
6{
7 "disable": ["<MATCH_ID>", "<MATCH_ID>"]
8}

Force new report creation (BETA)

POST
/v3.6/watchlist_monitors/<MONITOR_ID>/new_report

Triggers a new check with an updated report to be generated by the monitor, as if the monitor had received an update.

The report generated will not have any new information (as it is pulling from the same information as the previous report), but if matches have been newly enabled or disabled, the overall results may be different. For example, if all matches have been disabled, this will generate a “clear” report.

This endpoint has no request body.

If a new report is successfully generated, it will return a 201 Created response with no response body.

A link to the newly generated report will be listed in the “Location” header of the response.

bash
1HTTP/1.1 201 Created
2Content-Type: application/json
3Location: "/api/v3.5/checks/<CHECK_ID>"
Force an updated report to be created on a monitor
1POST /v3.6/watchlist_monitors/<MONITOR_ID>/new_report HTTP/1.1
2Host: api.eu.onfido.com
3Authorization: Token token=<YOUR_API_TOKEN>

ID photos

ID photos are government ID images of the applicant's face, typically provided by a trustworthy party (e.g., Government digital agency). These ID photos are used for all Facial Similarity reports.

ID photo object

AttributeDescription
idstring
The unique identifier of the ID photo.
created_atdatetime
The date and time at which the ID photo was uploaded.
hrefstring
The URI of this resource.
download_hrefstring
The URI that can be used to download the ID 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.
Example ID photo object
1HTTP/1.1 201 Created
2Content-Type: application/json
3
4{
5 "id": "<ID_PHOTO_ID>",
6 "created_at": "2019-10-09T16:59:06Z",
7 "file_name": "<FILE_NAME>.png",
8 "file_type": "image/png",
9 "file_size": 536630,
10 "href": "/v3.6/id_photos/<ID_PHOTO_ID>",
11 "download_href": "/v3.6/id_photos/<ID_PHOTO_ID>/download"
12}

Upload ID photo

POST
/v3.6/id_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 ID photo as part of a multipart request. Returns a ID photo object.

We provide a sample photo to test this endpoint.

Valid file formats for ID photos are jpg, jpeg and png. The file size must be between 32KB and 10MB.

Request body parameters

ParameterDescription
filerequired
The file to be uploaded.
applicant_idrequired
The applicant_id to associate the ID photo with.
Upload sample_photo.png
1POST /v3.6/id_photos/ HTTP/1.1
2Host: api.eu.onfido.com
3Authorization: Token token=<YOUR_API_TOKEN>
4Content-Type: multipart/form-data

Retrieve ID photo

GET
{'/v3.6/id_photos/{id_photo_id}'}

Retrieves a single ID photo. Returns a ID photo object.

Retrieve a single ID photos object
1GET /v3.6/id_photos/<ID_PHOTO_ID> HTTP/1.1
2Host: api.eu.onfido.com
3Authorization: Token token=<YOUR_API_TOKEN>

List ID photos

GET
{'/v3.6/id_photos/?applicant_id={applicant_id}'}

Lists the ID photos that belong to an applicant. Returns data in the form: {"id_photos": [<LIST_OF_ID_PHOTO_OBJECTS>]}.

Query string parameters

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

List all ID photo (objects) for a specific applicant
1GET /v3.6/id_photos?applicant_id=<APPLICANT_ID> HTTP/1.1
2Host: api.eu.onfido.com
3Authorization: Token token=<YOUR_API_TOKEN>

Download ID photo

GET
/v3.6/id_photos/{id_photo_id}/download

Downloads an ID photo. If successful, the response will be the binary data representing the image.

Download an ID photo
1GET /v3.6/id_photos/<ID_PHOTO_ID>/download HTTP/1.1
2Host: api.eu.onfido.com
3Authorization: Token token=<YOUR_API_TOKEN>

Qualified Electronic Signature

Retrieve Workflow Run Signed Document

POST
/v3.6/qualified_electronic_signature/documents?workflow_run_id={workflow_run_id}&file_id={file_id}

Retrieves the signed document or application form depending on the file_id provided.

After a successful call, a 302 Found HTTP status is returned with a pre-signed URL to download the file in the Location header.

Note: If you invoke this endpoint for Sandbox workflow runs, a mock signed document will be returned.

Query string parameters

workflow_run_id (required): the unique identifier of the Workflow Run for which you want to retrieve the signed document.

file_id (required): the unique identifier of the file which you want to retrieve.

Note: To retrieve file_id, you can obtain Qualified Electronic Signatures task details using the Retrieve Task endpoint:

/v3.6/workflow_runs/{workflow_run_id}/tasks/{task_id}

Retrieve a signed QES document
1GET /v3.6/qualified_electronic_signature/documents?workflow_run_id=<WORKFLOW_RUN_ID>&file_id=<FILE_ID> HTTP/1.1
2Host: api.eu.onfido.com
3Authorization: Token token=<YOUR_API_TOKEN>

Timeline Files

A Timeline File is an audit trail of the end-to-end IDV process performed on an Applicant through a Workflow Run, provided in PDF format.

It includes all the Workflow Tasks performed in chronological order, alongside some additional information. You can find more details about the Timeline File in the Studio product guide.

The Timeline File for a Workflow Run is generated on demand by invoking the Create Timeline File endpoint.

Since the generation of the Timeline File can take between a few seconds and a few minutes (depending on the number of Tasks the Workflow Run has), the process is executed asynchronously.

As such, as soon as file generation begins, the Create Timeline File endpoint will immediately return a 202 Accepted HTTP response.

The recommended way to be notified when the generation finishes and the Timeline File is available is to subscribe to the workflow_timeline_file.created webhook event. The payload of this webhook contains a pre-signed URL to download the file directly from Onfido's storage.

Alternatively, you may poll the Retrieve Timeline File endpoint until the file is made available. To do so, you use the Timeline File unique identifier returned by the Create Timeline File endpoint.

While the file is under generation, the Retrieve Timeline File endpoint will return a 404 Not Found HTTP response because the resource is not yet created. When the file becomes available, the endpoint returns a 302 Found HTTP status with a pre-signed URL to download the file in the Location header.

Note: For security reasons, the pre-signed URLs provided in both the Webhook and the Retrieve Timeline File endpoint have an expiration interval of 7 days. If you fail to download the file within this timeframe, you may call the Retrieve Timeline File again and a refreshed pre-signed URL will be returned in the Location header.

As an alternative to using Onfido's API, the Timeline File can also be downloaded from the Onfido Dashboard, on the Workflow Run results page.

The Timeline File is not signed, and must not be mistaken for the Evidence File. If you are looking to implement an ETSI certified Workflow solution, please read the documentation about the Evidence File in our product guide.

Note: The Timeline File may contain sensitive personal identifiable information (PII). The pre-signed URLs allow downloading the Timeline File and should be handled carefully.

Create Timeline File for Workflow Run

POST
/v3.6/workflow_runs/{workflow_run_id}/timeline_file

Triggers the generation of the Timeline File for the designated Workflow Run.

The Timeline File can only be generated if the Workflow Run is in a terminal status:

  • Abandoned
  • Error
  • Approved
  • Review
  • Declined

Given that the generation of the Timeline File takes some time, the process is executed asynchronously in the background. As such, this endpoint will return a 202 Accepted HTTP response as soon as the file generation begins. The response includes the unique identifier of the file that will be generated.

The recommended way to be notified of the completion of the file generation is by subscribing to the workflow_timeline_file.created webhook event.

Alternatively, you may poll the Retrieve Timeline File endpoint.

Path parameters

workflow_run_id (required): the unique identifier of the Workflow Run for which you want to start the generation of the Timeline File.

Create Timeline File for Workflow Run
1POST /v3.6/workflow_runs/<WORKFLOW_RUN_ID>/timeline_file HTTP/1.1
2Host: api.eu.onfido.com
3Authorization: Token token=<YOUR_API_TOKEN>

Retrieve Timeline File for Workflow Run

GET
/v3.6/workflow_runs/{workflow_run_id}/timeline_file/{timeline_file_id}

Retrieves the Timeline File for the designated Workflow Run.

After a successful call, a 302 Found HTTP status is returned with a pre-signed URL to download the Timeline File in the Location header.

The Timeline File should be available some time after its generation was triggered by calling the Create Timeline File endpoint. However, the generation time varies depending on the size of the Workflow Run, with Workflows Runs having more tasks and media captured taking more time to generate the file.

Path parameters

workflow_run_id (required): the unique identifier of the Workflow Run for which you want to retrieve a Timeline File.

timeline_file_id (required): the unique identifier of the Timeline File.

Note: The Timeline File may contain sensitive personal identifiable information (PII). The pre-signed URLs allow downloading the Timeline File and should be handled carefully.

Retrieve Timeline File for Workflow Run
1GET /v3.6/workflow_runs/<WORKFLOW_RUN_ID>/timeline_file/<TIMELINE_FILE_ID> HTTP/1.1
2Host: api.eu.onfido.com
3Authorization: Token token=<YOUR_API_TOKEN>

Report Types

Document report

This API documentation offers detailed information about the structure of a Document report, including an example of the report's result and its breakdowns.

For a more general introduction to the Document report, you can read our product documentation.

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

There are 6 different types of Document reports:

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

Document with Address Information, Document Video 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.

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

Supported Documents

In your Onfido Dashboard, you can configure which documents you want to accept in your verification workflow, filtering according to issuing country and document type.

When an applicant submits a restricted document (i.e. a document not included in your supported documents), the Supported document breakdown of the Document Report will flag as consider, producing a sub-result of reject.

Near Field Communication (NFC)

If available, the Document report uses 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.

NFC is only available via the Onfido mobile SDKs. Please read our NFC for Document report guide for details on how to integrate and use NFC for Document reports.

You can view the full list of supported documents for NFC.

Repeat attempts

You can also use our repeat attempts endpoint to request a list of repeat attempt matches for Document reports. A repeat attempt is any previous Document report that was submitted using a document that matches other previously onboarded documents in your Onfido database. This can indicate instances of repeat fraud where users submit multiple requests using the same document but with different personal data.

Required applicant data

For Document reports, first_name and last_name must be provided but can be sample 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 is also a resource for understanding the Document report response object structure.

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:

Establishes whether the data provided by the applicant matches the data extracted from the document. This breakdown is only returned if Comparison Checks are enabled for your account. Otherwise, the breakdown and its sub-breakdowns are returned as null and will not affect the final report result. To enable Comparison Checks, please contact Client Support.

We compare the following fields:

  • first_name
  • last_name
  • date_of_birth
  • gender

first_name and last_name can be configured to use a fuzzy or exact mechanism for the comparison. We take into account all available names for comparison, including spouse, widow or alias names.

date_of_birth and gender will always be compared using an exact mechanism.

Fuzzy comparison

Fuzzy comparison allows for greater flexibility during comparison, catering for discrepancies which may occur, for example, when an applicant uses their middle or spouse name, or there's been an extraction error.

Note:

  • When an applicant hasn’t provided data the sub-breakdown result is null for the missing field
  • When an applicant has provided names but names have not been extracted from the document, the sub-breakdown result is consider
  • When an applicant has provided date of birth and/or gender, but these fields have not been extracted from the document, the sub-breakdown result is null

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. Onfido uses UTC as a fixed reference point for the current date and time when the dates are compared.
  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 18 years. Configurable to set a different minimum age value. Onfido uses UTC as a fixed reference point for the current date and time when the applicant's age is calculated.

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 documents that have been reported as stolen or fraudulent to the UK Metropolitan Police.

This breakdown is only returned if Police Record Checks are enabled for your account. Otherwise, the breakdown and its sub-breakdowns are returned as null and will not affect the final report result. To enable Police Record Checks, please contact Client Support.

compromised_document:

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

  • document_database:

    Asserts whether the document is publicly available as compromised.

  • repeat_attempts:

    Asserts whether the document has been reused in a suspicious way.

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

  • image_integrity : supported_document

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 - This refers to when something other than obscuration of data points and security features makes the document insufficient to be assessed (i.e. poor image resolution, poor lighting, distortions due to capturing devices, misalignment due to cracks, visual alterations due to cases/laminates, some stickers etc.)

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

Supported Document reasons:

onfido_supported_document - When the Onfido product doesn't support the requested document

custom_supported_document - When the client's configured custom rules don't support the requested document

sanctioned_issuing_country - When a document is issued by a country subject to comprehensive US sanctions (you can find the list of countries here). The breakdown will return consider and a sub-result of rejected for the document report, as well as a property indicating that the document is not a supported document due to sanctions

Example Document report object
1HTTP/1.1 201 Created
2Content-Type: application/json
3
4{
5 "breakdown": {
6 "age_validation": {
7 "breakdown": {
8 "minimum_accepted_age": {
9 "properties": {},
10 "result": "clear"
11 }
12 },
13 "result": "clear"
14 },
15 "compromised_document": {
16 "breakdown": {
17 "document_database": {
18 "properties": {},
19 "result": "clear"
20 },
21 "repeat_attempts": {
22 "properties": {},
23 "result": "clear"
24 }
25 },
26 "result": "clear"
27 },
28 "data_comparison": {
29 "breakdown": {
30 "date_of_birth": {
31 "properties": {},
32 "result": "clear"
33 },
34 "date_of_expiry": {
35 "properties": {},
36 "result": null
37 },
38 "document_numbers": {
39 "properties": {},
40 "result": null
41 },
42 "document_type": {
43 "properties": {},
44 "result": null
45 },
46 "first_name": {
47 "properties": {},
48 "result": "clear"
49 },
50 "gender": {
51 "properties": {},
52 "result": null
53 },
54 "issuing_country": {
55 "properties": {},
56 "result": null
57 },
58 "last_name": {
59 "properties": {},
60 "result": "clear"
61 }
62 },
63 "result": "clear"
64 },
65 "data_consistency": {
66 "breakdown": {
67 "date_of_birth": {
68 "properties": {},
69 "result": "clear"
70 },
71 "date_of_expiry": {
72 "properties": {},
73 "result": "clear"
74 },
75 "document_numbers": {
76 "properties": {},
77 "result": "clear"
78 },
79 "document_type": {
80 "properties": {},
81 "result": "clear"
82 },
83 "first_name": {
84 "properties": {},
85 "result": "clear"
86 },
87 "gender": {
88 "properties": {},
89 "result": "clear"
90 },
91 "issuing_country": {
92 "properties": {},
93 "result": "clear"
94 },
95 "last_name": {
96 "properties": {},
97 "result": "clear"
98 },
99 "multiple_data_sources_present": {
100 "properties": {},
101 "result": "clear"
102 },
103 "nationality": {
104 "properties": {},
105 "result": "clear"
106 }
107 },
108 "result": "clear"
109 },
110 "data_validation": {
111 "breakdown": {
112 "date_of_birth": {
113 "properties": {},
114 "result": "clear"
115 },
116 "document_expiration": {
117 "properties": {},
118 "result": "clear"
119 },
120 "document_numbers": {
121 "properties": {},
122 "result": "clear"
123 },
124 "expiry_date": {
125 "properties": {},
126 "result": "clear"
127 },
128 "gender": {
129 "properties": {},
130 "result": "clear"
131 },
132 "mrz": {
133 "properties": {},
134 "result": "clear"
135 },
136 "barcode": {
137 "properties": {},
138 "result": "clear"
139 }
140 },
141 "result": "clear"
142 },
143 "image_integrity": {
144 "breakdown": {
145 "colour_picture": {
146 "properties": {},
147 "result": "clear"
148 },
149 "conclusive_document_quality": {
150 "properties": {},
151 "result": "clear"
152 },
153 "image_quality": {
154 "properties": {},
155 "result": "clear"
156 },
157 "supported_document": {
158 "properties": {},
159 "result": "clear"
160 }
161 },
162 "result": "clear"
163 },
164 "police_record": {
165 "result": "clear"
166 },
167 "visual_authenticity": {
168 "breakdown": {
169 "digital_tampering": {
170 "properties": {},
171 "result": "clear"
172 },
173 "face_detection": {
174 "properties": {},
175 "result": "clear"
176 },
177 "fonts": {
178 "properties": {},
179 "result": "clear"
180 },
181 "original_document_present": {
182 "properties": {},
183 "result": "clear"
184 },
185 "other": {
186 "properties": {},
187 "result": "clear"
188 },
189 "picture_face_integrity": {
190 "properties": {},
191 "result": "clear"
192 },
193 "security_features": {
194 "properties": {},
195 "result": "clear"
196 },
197 "template": {
198 "properties": {},
199 "result": "clear"
200 }
201 },
202 "result": "clear"
203 },
204 "issuing_authority": {
205 "breakdown": {
206 "nfc_active_authentication": {
207 "properties": {},
208 "result": null
209 },
210 "nfc_passive_authentication": {
211 "properties": {},
212 "result": null
213 }
214 },
215 "result": null
216 }
217 },
218 "check_id": "<CHECK_ID>",
219 "created_at": "2021-03-22T17:13:12Z",
220 "documents": [
221 {
222 "id": "<DOCUMENT_ID>"
223 }
224 ],
225 "href": "/v3.6/reports/<REPORT_ID>",
226 "id": "<REPORT_ID>",
227 "name": "document",
228 "properties": {
229 "date_of_birth": "1990-01-01",
230 "date_of_expiry": "2030-01-01",
231 "document_numbers": [
232 {
233 "type": "document_number",
234 "value": "999999999"
235 }
236 ],
237 "document_type": "passport",
238 "first_name": "Jane",
239 "gender": "",
240 "issuing_country": "GBR",
241 "last_name": "Doe",
242 "nationality": ""
243 },
244 "result": "clear",
245 "status": "complete",
246 "sub_result": "clear"
247}

Document video report

For a general introduction to the Document Video Report, you can read our product documentation.

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

"report_names": ["document_video"]

Document video report: Breakdown reasoning

The image_integrity breakdown of the Document Video Report response includes a video_document_presence sub-breakdown, which has the results clear and unidentified.

video_document_presence also has a property, called invalid_signature. If the media signature of a recorded video is not valid, the property will return consider, and the sub-breakdown will return unidentified. In this case, the Document Video Report will be rejected.

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

json
1"image_integrity": {
2 "breakdown": {
3 "video_document_presence": {
4 "properties": {},
5 "result": "clear"
6 }
7 },
8 "result": "clear"
9 },

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
1...
2 "address_lines": {
3 "city": "EDINBURGH",
4 "country": "United Kingdom (UK)",
5 "postal_code": "EH1 9GP",
6 "state": "",
7 "street_address": "122 BURNS CRESCENT",
8 "country_code": "GBR"
9 },
10 "address": "<ADDRESS_STRING>",
11...

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

Document Video Report 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 Video 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_video_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 Video 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
1...
2 "address_lines": {
3 "city": "EDINBURGH",
4 "country": "United Kingdom (UK)",
5 "postal_code": "EH1 9GP",
6 "state": "",
7 "street_address": "122 BURNS CRESCENT",
8 "country_code": "GBR"
9 },
10 "address": "<ADDRESS_STRING>",
11...

Contact your account manager for more information about the features in the Document Video 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
1...
2"driving_licence_information": [
3 {
4 "category": "A",
5 "codes": "79.03,79.04",
6 "expiry_date": "<YYYY-MM-DD>",
7 "obtainment_date": "<YYYY-MM-DD>"
8 },
9 {
10 "category": "A1",
11 "codes": "79.03,79.04",
12 "expiry_date": "<YYYY-MM-DD>",
13 "obtainment_date": "<YYYY-MM-DD>"
14 },
15 {
16 "category": "AM",
17 "codes": "",
18 "expiry_date": "<YYYY-MM-DD>",
19 "obtainment_date": "<YYYY-MM-DD>"
20 },
21 {
22 "category": "B",
23 "codes": "",
24 "expiry_date": "<YYYY-MM-DD>",
25 "obtainment_date": "<YYYY-MM-DD>"
26 }
27 ],
28...

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.

Document with Driver Verification

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

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

"report_names": ["document_with_driver_verification"]

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

To specify which uploaded document to run the Document with Driver Verification 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 table is an example showing what properties are added to the Document report response object:

PropertyDescriptionValue type
"drivers_licence"True when determined to be a non-restricted driving licence (applicant older than 18 years, and no restricted categories detected in the licence title)Boolean
"restricted_licence"True for limited/restricted driving licences, including learner's permitsBoolean
"raw_licence_category"Underlying, non-normalised, licence category (e.g. "Junior operators license")String or Empty
"raw_vehicle_classes"Comma-separated vehicle classes that the user is qualified forString or Empty
"vehicle_class_details"Detailed classes/categories informationArray of objects or Empty
"vehicle_class_details[].categoryVehicle class/categoryString
"vehicle_class_details[].codesSpecial conditions driver must meetString or Empty
"vehicle_class_details[].obtainment_dateCategory obtainment dateString
"vehicle_class_details[].expiry_dateCategory expiry dateString or Empty
"manual_transmission_restriction"True if the user is not qualified to drive a manual transmissionBoolean or Empty
"passenger_vehicle"Normalised data for passenger carsObject or Empty
"passenger_vehicle.permision_to_drive"Whether they are qualified for a passenger car, such as a “B” class in the UKString or Empty
"passenger_vehicle.obtainment_date"Date the class qualification was obtainedString or Empty
"passenger_vehicle.expiry_date"Date the class qualification expires, which may be different to doc expiryString or Empty

Example:

json
1...
2
3"drivers_licence": true,
4"restricted_licence": false,
5"raw_licence_category": "DRIVER LICENSE",
6"raw_vehicle_classes": "AM,B",
7"vehicle_class_details": [{
8 "category": "AM",
9 "obtainment_date": "2020-05-12",
10 "expiry_date": "2030-05-12"
11 },
12 {
13 "category": "B",
14 "obtainment_date": "2020-05-12",
15 "expiry_date": "2030-05-12"
16 }
17]
18
19...

Contact your account manager for more information about the features in the Document with Driver Verification report.

Facial Similarity reports

This API documentation offers detailed information about the structure of a Facial Similarity report, including an example of the report's result and its breakdowns.

For a more general introduction to the Facial Similarity report, you can read our product documentation.

After you've familiarised yourself with the information here, you can read our guide on [suggested client guide/facial-similarity-reports/#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 4 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"]
Motion"report_names": ["facial_similarity_motion"]

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

"document_ids": ["<DOCUMENT_ID>"]

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

Where the document has two sides, we will search both sides of the document for a face. Where the document has been scanned using NFC, we will use the face extracted from the document's NFC chip.

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

A breakdown or sub-breakdown will have the result null when it has not been completed. This occurs when it is not available, or has failed to process the media due to a timeout or an internal error. In this case, the report will go to manual review.

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
  • payload_integrity - when evidence is found that the payload was tampered with
  • sanctioned_document_country - when a document is issued by a country subject to comprehensive US sanctions (you can find the list of countries here). The report (either in conjunction with or separate from a document report) will return a consider result, accompanied by a reasons property clarifying that it is not supported due to sanctions
  • 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.

Example Facial Similarity Photo report object
1HTTP/1.1 201 Created
2Content-Type: application/json
3
4{
5 "created_at": "2019-12-11T09:39:05Z",
6 "href": "/v3.6/reports/<REPORT_ID>",
7 "id": "<REPORT_ID>",
8 "name": "facial_similarity_photo",
9 "properties": {},
10 "result": "clear",
11 "status": "complete",
12 "sub_result": null,
13 "breakdown": {
14 "face_comparison": {
15 "result": "clear",
16 "breakdown": {
17 "face_match": {
18 "result": "clear",
19 "properties": {
20 "score": 0.6512,
21 "document_id": "<DOCUMENT_ID>"
22 }
23 }
24 }
25 },
26 "image_integrity": {
27 "result": "clear",
28 "breakdown": {
29 "face_detected": {
30 "result": "clear",
31 "properties": {}
32 },
33 "source_integrity": {
34 "result": "clear",
35 "properties": {}
36 }
37 }
38 },
39 "visual_authenticity": {
40 "result": "clear",
41 "breakdown": {
42 "spoofing_detection": {
43 "result": "clear",
44 "properties": {
45 "score": 0.9512
46 }
47 }
48 }
49 }
50 },
51 "check_id": "<CHECK_ID>",
52 "documents": []
53}

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
  • payload_integrity - when evidence is found that the payload was tampered with
  • sanctioned_document_country - when a document is issued by a country subject to comprehensive US sanctions (you can find the list of countries here). The report (either in conjunction with or separate from a document report) will return a consider result, accompanied by a reasons property clarifying that it is not supported due to sanctions
  • 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.

Example Photo Fully Auto report object
1HTTP/1.1 201 Created
2Content-Type: application/json
3
4{
5 "created_at": "2020-01-01T14:16:21Z",
6 "href": "/v3.6/reports/<REPORT_ID>",
7 "id": "<REPORT_ID>",
8 "name": "facial_similarity_photo_fully_auto",
9 "result": "clear",
10 "status": "complete",
11 "sub_result": null,
12 "breakdown": {
13 "visual_authenticity": {
14 "result": "clear",
15 "breakdown": {
16 "spoofing_detection": {
17 "result": "clear",
18 "properties": {
19 "score": 0.9901
20 }
21 }
22 }
23 },
24 "image_integrity": {
25 "result": "clear",
26 "breakdown": {
27 "face_detected": {
28 "result": "clear",
29 "properties": {}
30 },
31 "source_integrity": {
32 "result": "clear",
33 "properties": {}
34 }
35 }
36 },
37 "face_comparison": {
38 "result": "consider",
39 "breakdown": {
40 "face_match": {
41 "result": "consider",
42 "properties": {
43 "score": 0.2097,
44 "document_id": "<DOCUMENT_ID>"
45 }
46 }
47 }
48 }
49 },
50 "check_id": "<CHECK_ID>"
51}

Facial Similarity Video

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

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"
Chinese"cn"
Turkish"tr"
Malay"ms"

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:

  • iOS SDK - pass the onfido_locale parameter
  • Android SDK - pass the onfido_locale parameter
  • Web SDK - pass the locale parameter

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
  • payload_integrity - when evidence is found that the payload was tampered with
  • sanctioned_document_country - when a document is issued by a country subject to comprehensive US sanctions (you can find the list of countries here). The report (either in conjunction with or separate from a document report) will return a consider result, accompanied by a reasons property clarifying that it is not supported due to sanctions
  • 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.

Example Facial Similarity Video report object
1HTTP/1.1 201 Created
2Content-Type: application/json
3
4{
5 "created_at": "2019-12-11T10:06:38Z",
6 "href": "/v3.6/reports/<REPORT_ID>",
7 "id": "<REPORT_ID>",
8 "name": "facial_similarity_video",
9 "properties": {},
10 "result": "clear",
11 "status": "complete",
12 "sub_result": null,
13 "breakdown": {
14 "face_comparison": {
15 "result": "clear",
16 "breakdown": {
17 "face_match": {
18 "result": "clear",
19 "properties": {
20 "score": 0.6512,
21 "document_id": "<DOCUMENT_ID>"
22 }
23 }
24 }
25 },
26 "image_integrity": {
27 "result": "clear",
28 "breakdown": {
29 "face_detected": {
30 "result": "clear",
31 "properties": {}
32 },
33 "source_integrity": {
34 "result": "clear",
35 "properties": {}
36 }
37 }
38 },
39 "visual_authenticity": {
40 "result": "clear",
41 "breakdown": {
42 "liveness_detected": {
43 "result": "clear",
44 "properties": {}
45 },
46 "spoofing_detection": {
47 "result": "clear",
48 "properties": {
49 "score": 0.9512
50 }
51 }
52 }
53 }
54 },
55 "check_id": "<CHECK_ID>",
56 "documents": []
57}

Facial Similarity Motion

In the Facial Similarity Motion report, motion captures are collected and uploaded by one of the Onfido SDKs (iOS, Android or Web).

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

In addition to confirming the two faces match, Facial Similarity Motion assesses liveness by asking users to complete a head turn in both directions. This process is reflected in visual_authenticity, which is composed of the sub-breakdowns spoofing_detection and liveness_detected. See Facial Similarity Motion Object and Facial Similarity Motion Breakdowns.

Facial Similarity Motion reports always complete automatically.

Facial Similarity Motion: Object

The following table describes the unique fields returned in this version of the Onfido API for a completed Facial Similarity Motion 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 Motion: Source Integrity)

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

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

Facial Similarity Motion: Breakdowns

BreakdownDescription
face_comparisonobject
Asserts whether the face in the document matches the face in the motion capture.
(sub-breakdown) face_matchobject
Contains a score value and document_id unique identifier for the matched document under the properties bag (see Facial Similarity Motion: 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 face of good enough quality has been found in both the document image and in the motion capture.
(sub-breakdown) source_integrityobject
Asserts whether the motion capture is trustworthy - e.g. not from a fake webcam.
visual_authenticityobject
Asserts whether the person in the motion capture is real (not a spoof) and live.
(sub-breakdown) spoofing_detectionobject
Asserts whether the motion capture is not a spoof (such as videos of digital screens).
(sub-breakdown) liveness_detectedobject
Asserts whether the head movements were correctly executed.

Facial Similarity Motion: 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 Motion, 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
  • payload_integrity - when evidence is found that the payload was tampered with
  • sanctioned_document_country - when a document is issued by a country subject to comprehensive US sanctions (you can find the list of countries here). The report (either in conjunction with or separate from a document report) will return a consider result, accompanied by a reasons property clarifying that it is not supported due to sanctions
  • reasons - additional comma separated details, such as the name of the fake webcam

Facial Similarity Motion: 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.

The score only measures how similar the faces are, and does not make an assessment of the nature of the motion capture. 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 Motion: 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 performed the head turn. For example, a user who performs no action but is a real person should receive a score close to 1.

Example Facial Similarity Motion report object
1HTTP/1.1 201 Created
2Content-Type: application/json
3
4{
5 "check_id": "<CHECK_ID>",
6 "created_at": "2022-12-11T15:14:58Z",
7 "documents": [
8 {
9 "id": "<DOCUMENT_ID>"
10 }
11 ],
12 "href": "/v3.6/reports/<REPORT_ID>",
13 "id": "<REPORT_ID>",
14 "name": "facial_similarity_motion",
15 "properties": {},
16 "result": "clear",
17 "status": "complete",
18 "sub_result": null,
19 "breakdown": {
20 "face_comparison": {
21 "result": "clear",
22 "breakdown": {
23 "face_match": {
24 "result": "clear",
25 "properties": {
26 "score": 0.6512,
27 "document_id": "<DOCUMENT_ID>"
28 }
29 }
30 }
31 },
32 "image_integrity": {
33 "result": "clear",
34 "breakdown": {
35 "face_detected": {
36 "result": "clear",
37 "properties": {}
38 },
39 "source_integrity": {
40 "result": "clear",
41 "properties": {}
42 }
43 }
44 },
45 "visual_authenticity": {
46 "result": "clear",
47 "breakdown": {
48 "liveness_detected": {
49 "result": "clear",
50 "properties": {}
51 },
52 "spoofing_detection": {
53 "result": "clear",
54 "properties": {
55 "score": 0.9512
56 }
57 }
58 }
59 }
60 }
61}

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 API documentation offers detailed information about the structure of a Known Faces report, including an example of the report's result and its breakdowns.

For a more general introduction to the Known Faces report, you can read our product documentation.

The Known Faces report requires that we keep 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, live video or motion capture.

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

json
1"properties":{
2 "reason": "Report withdrawn due to missing media (photo, video or motion capture) required for processing."
3}

It is highly recommended the Known Faces report always be run in conjunction with a Facial Similarity report. Only faces processed through Facial Similarity are kept on the database. Thus, although it can be requested on its own, a Known Faces report can only match against applicants who have previously gone through a Facial Similarity report.

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 sample 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 null1"clear", "consider" , null
image_integrityString"clear", "consider"
  1. null is returned when image_integrity is "consider". This is because, when no face is detected in the input media, there is nothing to match against previously seen faces.

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. Only matches where the suspected field is true will be considered.
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: Properties

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, live_videos), as well as the corresponding UUID for that media type. For example, the live photo or live video ID.

Only matches where the suspected field is true should be considered as possible fraud. This is determined by fuzzy matching the report's applicant name and matched applicants' names. This can have a value of false only if the fuzzy name matching feature for Known Faces reports is enabled in your account.

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

json
1"matches": [
2 {
3 "applicant_id": "NTH_MATCHED_APPLICANT_ID",
4 "score": 0.9915,
5 "media_id": "LIVE_PHOTO_ID",
6 "media_type": "live_photos",
7 "suspected": true
8 }
9]

If matches are found and any of them is suspected, the result will be consider. Conversely, if none of the matches are suspected, the result will be clear.

Example Known Faces report object
1HTTP/1.1 201 Created
2Content-Type: application/json
3
4{
5 "created_at": "2020-06-19T09:44:14Z",
6 "documents": [],
7 "href": "/v3.6/reports/<REPORT_ID>",
8 "id": "<REPORT_ID>",
9 "name": "known_faces",
10 "properties": {
11 "matches": [
12 {
13 "applicant_id": "<1ST_MATCHED_APPLICANT_ID>",
14 "score": 1,
15 "media_id": "<1ST_MEDIA_ID>",
16 "media_type": "live_photos",
17 "suspected": false
18 },
19 {
20 "applicant_id": "<2ND_MATCHED_APPLICANT_ID>",
21 "score": 1,
22 "media_id": "<2ND_MEDIA_ID>",
23 "media_type": "live_videos",
24 "suspected": true
25 },
26 {
27 "applicant_id": "<3RD_MATCHED_APPLICANT_ID>",
28 "score": 0.8903,
29 "media_id": "<3RD_MEDIA_ID>",
30 "media_type": "live_photos",
31 "suspected": false
32 },
33 {
34 "applicant_id": "<4TH_MATCHED_APPLICANT_ID>",
35 "score": 0.8903,
36 "media_id": "<4TH_MEDIA_ID>",
37 "media_type": "live_photos",
38 "suspected": false
39 },
40 {
41 "applicant_id": "<5TH_MATCHED_APPLICANT_ID>",
42 "score": 0.8903,
43 "media_id": "<5TH_MEDIA_ID>",
44 "media_type": "motion",
45 "suspected": false
46 }
47 ]
48 },
49 "result": "consider",
50 "status": "complete",
51 "sub_result": null,
52 "breakdown": {
53 "previously_seen_faces": {
54 "result": "consider"
55 },
56 "image_integrity": {
57 "result": "clear"
58 }
59 },
60 "check_id": "<CHECK_ID>"
61}

Identity Enhanced report

This API documentation offers detailed information about the structure of a Identity Enhanced report, including an example of the report's result and its breakdowns.

For a more general introduction to the Identity Enhanced report, you can read our product documentation.

For verification 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:

The applicant address object is nested inside the applicant object. You must provide full address information in the request. The address field will not return a match if only address.postcode is provided.

Alternatively, you can provide addresses in the form line1, line2 and line3. If you provide address data in this form, Onfido uses a third-party subprocessor for address cleansing.

For more details, you can review the full list of supported countries with required and recommended data.

If you don't provide date of birth or address information in the request, a consider response with no breakdown information is returned. This is an invalid response and should be interpreted as a failed report.

Supported countries for Identity Enhanced

You can review the full list of supported countries for Identity Enhanced reports.

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

Identity Enhanced: Report object

The report object varies depending on the applicant's address country field.

United Kingdom

Example report object where the applicant's address is in the United Kingdom.

Sources (credit_agencies, voting_register, telephone_database) are displayed as breakdowns with their own result value.

Example UK Identity Enhanced report object
1HTTP/1.1 201 Created
2Content-Type: application/json
3
4{
5 "created_at": "2019-10-03T15:54:20Z",
6 "href": "/v3.6/reports/<REPORT_ID>",
7 "id": "<REPORT_ID>",
8 "name": "identity_enhanced",
9 "properties": {
10 "matched_address": 19099121,
11 "matched_addresses": [
12 {
13 "id": 19099121,
14 "match_types": [
15 "credit_agencies",
16 "voting_register"
17 ]
18 }
19 ]
20 },
21 "result": "clear",
22 "status": "complete",
23 "sub_result": null,
24 "breakdown": {
25 "sources": {
26 "result": "clear",
27 "breakdown": {
28 "total_sources": {
29 "result": "clear",
30 "properties": {
31 "total_number_of_sources": "3"
32 }
33 }
34 }
35 },
36 "address": {
37 "result": "clear",
38 "breakdown": {
39 "credit_agencies": {
40 "result": "clear",
41 "properties": {
42 "number_of_matches": "1"
43 }
44 },
45 "telephone_database":