Overview
Get started (API v3.1)
Welcome to our new API v3.1 documentation. If you're migrating and are
currently using api.onfido.com
, please make sure you use api.eu.onfido.com
with API v3.1.
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.
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.
-
In your Onfido Dashboard, create a new API token
-
Wherever you use your old API token, replace it with the new one
-
Confirm your old token isn't in use
-
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.
The type of token you use will determine whether you use the sandbox or live environment.
You can make all the same API requests in the sandbox API as in the live one. Sandbox results have the same result response structures as live requests. You will also be notified of check and report status changes via your registered webhooks.
You can use the sandbox API to simulate API requests and to check:
- your system's network connectivity with the Onfido API
- your webhooks are working correctly
- you're posting all required data in the correct format to the Onfido API
- you're handling Onfido API responses correctly
To use the sandbox, you'll need to generate a sandbox API token in your Onfido Dashboard.
By default, sandbox API tokens start with api_sandbox.
and live API tokens
start with api_live.
. This might vary if you're using a different
region environment.
For sandbox requests, the rate limit is 30 requests per minute.
Sandbox and live differences
The key differences between sandbox and live checks are:
- sandbox check data is not processed by Onfido services or third parties—this means that sandbox responses are faster than live responses
- sandbox check results are pre-determined
- sandbox applicants are isolated from the live environment*
- you won't be charged for checks in sandbox
* applicant notification emails still get sent out to sandbox applicants
Sample document, photo
You can use the upload document endpoint with the following files as part of running test checks:
The sandbox API will always return pre-determined responses, regardless of what files are uploaded.
These files also work for testing the Onfido Smart Capture SDKs.
Pre-determined responses
To help you test your integration in the sandbox API, you can trigger pre-determined report responses.
Pre-determined responses work for the following report types:
- Identity Enhanced
- Document
- Watchlist AML
- Watchlist Standard
- Watchlist Enhanced
- Watchlist PEPs Only
- Watchlist Sanctions Only
- Facial Similarity Photo
- Facial Similarity Photo Fully Auto
- Facial Similarity Video
- Facial Similarity Motion
- Repeat Attempts
- Driver's License Data Verification
- Proof of Address
Pre-determined 'consider' results
To test only 'consider' report responses:
- Create an applicant which has the last name "Consider"
- Create a check with this applicant
All reports specified in check creation will return a consider
report result. If you use any other applicant last name, the result will be clear
.
Different reports have different minimum requirements for applicant data (even in the sandbox).
1POST /v3.1/applicants/ HTTP/1.12Host: api.eu.onfido.com3Authorization: Token token=<YOUR_API_TOKEN>4Content-Type: application/json56{7 "first_name": "Jane",8 "last_name": "Consider"9}
Pre-determined 'consider' and 'clear' results
To test multiple different sandbox report responses simultaneously, you can pass specific report
types to the consider
parameter (in an array).
Only the reports specified in the consider
array will
return a consider
report result. All other reports in the check will return a clear
result.
1POST /v3.1/checks/ HTTP/1.12Host: api.eu.onfido.com3Authorization: Token token=<YOUR_API_TOKEN>4Content-Type: application/json56{7 "applicant_id": "<APPLICANT_ID>",8 "report_names": [9 "watchlist_standard",10 "identity_enhanced"11 ],12 "consider": [13 "watchlist_standard"14 ]15}
Pre-determined responses for Document reports
The sandbox API supports additional functionality for testing Document reports. You can trigger pre-determined Document report responses for specific:
For Document reports, first_name
and last_name
must be provided when creating an applicant (even in the Sandbox).
Breakdowns and sub-breakdowns
You can trigger responses for particular breakdowns and sub-breakdowns for sandbox Document reports. These responses show possible breakdown and sub-breakdown combinations that can be flagged for a consider
report result.
To test breakdown - sub-breakdown combinations:
- Create an applicant which has the
first_name
as the "breakdown - sub-breakdown" combination you intend to trigger.
Sandbox supports the following options:
"Image Integrity - Supported Document"
"Image Integrity - Image Quality"
"Visual Authenticity - Fonts"
"Visual Authenticity - Security Features"
"Visual Authenticity - Face Detection"
"Data Validation - Document Numbers"
"Data Consistency - Document Type"
You can also include a document type by specifying last_name
as a supported
sandbox document type during applicant creation.
- Create a check with this applicant.
Passing a first_name
option to generate a Document report pre-determined response will override any conflicting option passed to the applicant's last_name
.
1POST /v3.1/applicants/ HTTP/1.12Host: api.eu.onfido.com3Authorization: Token token=<YOUR_API_TOKEN>4Content-Type: application/json56{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. These responses show a Document report response including the specific properties
for the associated document type.
To test different document types:
- Create an applicant which has the
last_name
as the document type you intend to test.
Sandbox supports the following options:
Sandbox option | Sandbox 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" and "FRA ID 1994 front only rejected" | 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.
- Create a check with this applicant.
1POST /v3.1/applicants/ HTTP/1.12Host: api.eu.onfido.com3Authorization: Token token=<YOUR_API_TOKEN>4Content-Type: application/json56{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. These responses show possible individual breakdown results which can lead to different sub-results.
To do this:
- Create an applicant which has the
last_name
as one of the following strings:
"clear"
"rejected"
"suspected"
"caution"
- Create a check with this applicant.
You can't also specify a document type when testing sub-results.
1POST /v3.1/applicants/ HTTP/1.12Host: api.eu.onfido.com3Authorization: Token token=<YOUR_API_TOKEN>4Content-Type: application/json56{7 "first_name": "Jane",8 "last_name": "rejected"9}
Pre-determined responses for Facial Similarity reports
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 responses for particular breakdowns and sub-breakdowns for sandbox Facial Similarity reports. These responses show possible breakdown and sub-breakdown combinations that can be flagged for a consider
report result.
To test breakdown - sub-breakdown combinations:
- Create an applicant which has the
first_name
as the "breakdown - sub-breakdown" combination you intend to trigger.
Sandbox supports the following options:
"Visual Authenticity - Spoofing Detection"
"Face Comparison - Face Match"
"Image Integrity - Source Integrity"
"Image Integrity - Face Detected"
- Create a check with this applicant.
1POST /v3.1/applicants/ HTTP/1.12Host: api.eu.onfido.com3Authorization: Token token=<YOUR_API_TOKEN>4Content-Type: application/json56{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
1$ curl -X POST https://api.eu.onfido.com/v3.1/repeat_attempts/match \2 -H 'Authorization: Token token=<YOUR_API_TOKEN>' \
Below is a pre-determined response example for a Repeat Attempts match:
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": 026}
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.
Language | Library | Notes |
---|---|---|
Ruby | onfido-ruby | |
Java | onfido-java | |
Node.js | onfido-node | Also supports TypeScript. |
Python | onfido-python | |
PHP | api-php-client | Made 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.
1HTTP/1.1 429 Too Many Requests2Content-Type: application/json34{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.1. If you were previously using api.onfido.com
, you should use api.eu.onfido.com
with v3.1.
1onfido = Onfido::API.new(2 api_key: ENV['ONFIDO_API_KEY'],3 region: :eu4)
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.
1onfido = Onfido::API.new(2 api_key: ENV['ONFIDO_API_KEY'],3 region: :us4)
Regions have unique base URLs and API token formats for both live and sandbox environments.
1onfido = Onfido::API.new(2 api_key: ENV['ONFIDO_API_KEY'],3 region: :ca4)
Region | Notes | API base URL | API token format |
---|---|---|---|
EU | Replaces api.onfido.com for EU region in v3.1 | https://api.eu.onfido.com/ | Tokens are prepended with api_live. and api_sandbox. |
US | https://api.us.onfido.com/ | Tokens are prepended with api_live_us. and api_sandbox_us. | |
CA | https://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
Date | Description |
---|---|
Added documentation for Watchlist AML report. | |
Added documentation for Trusted Faces. | |
Added documentation for Face Authenticate. | |
Added documentation on the Driver's License Data Verification report. | |
Added documentation for new Sandbox functionality. | |
Added share code content to Right to Work report (product now deprecated and no longer available). | |
General release of API version 3.1. Please see our release notes | |
privacy_notices_read_consent_given added to check object in v3.1 |
Upcoming maintenance
There's currently no scheduled maintenance.
Errors
All errors are returned with the same structure:
1{2 "error": {3 "type": <TYPE>,4 "message": <MESSAGE>,5 "fields": <FIELDS - NOT ALWAYS PRESENT>6 }7}
Example error object
Attribute | Description |
---|---|
type | string The type of error returned. |
message | string A human-readable message giving more details about the error. |
fields | object The invalid fields and their associated errors. Only applies to validation errors. |
1HTTP/1.1 422 Unprocessable Entity2Content-Type: application/json34{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
Status | Action |
---|---|
400 bad_request | Make sure your request is formatted correctly. |
400 incorrect_base_url | Please use api.eu.onfido.com for API v3.1 onwards if you were previously using api.onfido.com. |
401 authorization_error | Make 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_error | Contact an administrator about user permissions. |
401 bad_referrer | Check the referrer used to generate the SDK token. |
401 expired_token | Request a new SDK token. |
403 account_disabled | Please contact client-support@onfido.com. |
403 trial_limits_reached | Please contact client-support@onfido.com. |
404 resource_not_found | Make sure you've formatted the URI correctly. |
410 gone | The resource has been deleted or is scheduled for deletion. |
422 validation_error | Check the fields property for a specific error message. |
422 missing_billing_info | Make sure you've provided your billing information before starting a check. |
422 missing_documents | Make sure you've uploaded the required documents before starting a check. |
422 invalid_reports_names | Make sure you've entered the report name(s) in the correct format (string). |
422 missing_id_numbers | Make sure you've supplied all required ID numbers. |
422 report_names_blank | Make sure you've specified report_names in your request. |
422 report_names_format | report_names must be an array of strings, not an array of objects. |
422 deprecated_reports | The requested reports have been deprecated. |
422 check_type_deprecated | type is not used in this version of the API. Please read about the applicant_provides_data feature. |
422 document_ids_without_document_report | You 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_document | For applicant_provides_data checks, Facial Similarity reports must be paired with a Document report. |
422 facial_similarity_video_not_supported | The Facial Similarity Video report is not supported for checks where applicant_provides_data is true . |
422 failed_check_requirements | Check that all required information has been provided and correctly specified. |
422 incomplete_checks | There are other ongoing checks associated with this applicant. |
422 disabled_reports | There are reports disabled in your account. Please contact client-support@onfido.com. |
422 too_many_checks | You have exceeded the limit of 1000 checks for the given applicant. |
429 rate_limit | The rate limit has been reached. Please try again later. |
500 internal_server_error | The server encountered an error. If this persists, please contact client-support@onfido.com. |
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
Attribute | Description |
---|---|
id | string The unique identifier for the applicant. |
created_at | datetime The date and time when this applicant was created. |
delete_at | datetime The date and time when this applicant is scheduled to be deleted, or null if the applicant is not scheduled to be deleted. |
href | string The URI of this resource. |
first_name | string The applicant's first name. |
last_name | string The applicant's surname. |
string The applicant's email address. | |
dob | date The applicant's date of birth in YYYY-MM-DD format. |
id_numbers | array of id number objects A collection of identification numbers belonging to this applicant. |
address | address object The address of the applicant. |
sandbox | Boolean Indicates whether the object was created in the sandbox or not. |
ID number object
The ID number array of objects is nested inside the applicant object.
Attribute | Description |
---|---|
type | string Type of ID number. Valid values are ssn , social_insurance (e.g. UK National Insurance), tax_id , identity_card and driving_licence . |
value | string Value of ID number. 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_code | string Two letter code of issuing state (state-issued driving licences only). |
Address object
The applicant address object is nested inside the applicant object.
Attribute | Description |
---|---|
flat_number | string The flat number. |
building_number | string The building number. |
building_name | string The building name. |
street | string The street of the applicant's address. There is a 32-character limit on this field for UK addresses. |
sub_street | string The sub-street. |
town | string The town. |
state | string The address state. US states must use the USPS abbreviation (see also ISO 3166-2:US), for example AK , CA , or TX . |
postcode | string The postcode (ZIP code) of the applicant's address. For UK postcodes, specify the value in the following format: SW4 6EH . |
country | string The 3 character ISO country code of this address. For example, GBR is the country code for the United Kingdom. |
line1 | string Line 1 of the address. |
line2 | string Line 2 of the address. |
line3 | string Line 3 of the address. |
postcode
and country
are required fields if an address is provided for an
applicant. For US addresses, state
is also a required field.
Most addresses will contain information such as flat_number
. Make sure they
are supplied as separate fields, and do not try and fit them all into the
street
field. Doing so is likely to affect check performance.
Alternatively, you can provide addresses in the form line1
, line2
and
line3
if you're creating a check with an Identity
Enhanced report. If you provide address data in
this form, Onfido uses a third-party subprocessor for address cleansing.
Forbidden characters
For addresses the following characters are forbidden:
!$%^*=<>
For names the following characters are forbidden:
^!#$%*=<>;{}"
1HTTP/1.1 201 Created2Content-Type: application/json34{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.1/applicants/<APPLICANT_ID>",14 "id_numbers": [],15 "address": {16 "flat_number": null,17 "building_number": null,18 "building_name": null,19 "street": "Second Street",20 "sub_street": null,21 "town": "London",22 "state": null,23 "postcode": "S2 2DF",24 "country": "GBR",25 "line1": null,26 "line2": null,27 "line3": null28 }29}
Create applicant
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
Parameter | Description |
---|---|
first_name | required The applicant's forename. |
last_name | required The applicant's surname. |
required only if creating a check where applicant_provides_data is true The applicant's email address. | |
dob | optional The applicant's date of birth in YYYY-MM-DD format. |
id_numbers | optional A collection of identification numbers belonging to this applicant. |
address | optional The address of the applicant. |
1POST /v3.1/applicants/ HTTP/1.12Host: api.eu.onfido.com3Authorization: Token token=<YOUR_API_TOKEN>4Content-Type: application/json56{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
Retrieves a single applicant. Returns an applicant object.
1GET /v3.1/applicants/<APPLICANT_ID> HTTP/1.12Host: api.eu.onfido.com3Authorization: Token token=<YOUR_API_TOKEN>
Update applicant
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
1PUT /v3.1/applicants/<APPLICANT_ID> HTTP/1.12Host: api.eu.onfido.com3Authorization: Token token=<YOUR_API_TOKEN>4Content-Type: application/json56{7 "first_name": "New",8 "last_name": "Name"9}
Delete applicant
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.
1DELETE /v3.1/applicants/<APPLICANT_ID> HTTP/1.12Host: api.eu.onfido.com3Authorization: Token token=<YOUR_API_TOKEN>
Restore applicant
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.
1POST /v3.1/applicants/<APPLICANT_ID>/restore HTTP/1.12Host: api.eu.onfido.com3Authorization: Token token=<YOUR_API_TOKEN>
List 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.
Link header
The Link
header contains pagination information. For example:
Link: [https://api.eu.onfido.com/v3.1/applicants?page=3059](https://api.eu.onfido.com/v3.1/applicants?page=3059); rel="last", [https://api.eu.onfido.com/v3.1/applicants?page=2](https://api.eu.onfido.com/v3.1/applicants?page=2); rel="next"
Possible rel
values are:
Name | Link relation (description) |
---|---|
next | Next page of results. |
last | Last page of results. |
first | First page of results. |
prev | Previous page of results. |
The custom X-Total-Count
header gives the total resource count.
1GET /v3.1/applicants?page=1&per_page=5 HTTP/1.12Host: api.eu.onfido.com3Authorization: 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
Attribute | Description |
---|---|
id | string The unique identifier of the document. |
created_at | datetime The date and time at which the document was uploaded. |
href | string The URI of this resource. |
download_href | string The URI that can be used to download the document. |
file_name | string The name of the uploaded file. |
file_type | string The file type of the uploaded file. |
file_size | integer The size of the file in bytes. |
type | string The type of document. |
side | string The side of the document, if applicable. The possible values are front and back . |
issuing_country | string The issuing country of the document, in 3-letter ISO code, specified when uploading it. |
applicant_id | string The id of the applicant to whom the document belongs. |
1HTTP/1.1 201 Created2Content-Type: application/json34{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.1/documents/<DOCUMENT_ID>",15 "download_href": "/v3.1/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
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
Parameter | Description |
---|---|
applicant_id | required The ID of the applicant who owns the document. |
file | required The file to be uploaded. |
type | required The type of document. For example, passport . |
side | optional (required for documents which have multiple sides) Either the front or back of the document. |
issuing_country | optional (required for Proof of Address reports) The issuing country of the document in 3-letter ISO code. |
validate_image_quality | optional A Boolean. Defaults to false . When true the submitted image will undergo an image quality validation which may take up to 5 seconds. |
Image quality
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.
Field | Message |
---|---|
detect_blur | blur detected in image |
detect_cutoff | cutoff document detected in image |
document_detection | no document in image |
Sample images to trigger various error responses can be provided.
1POST /v3.1/documents/ HTTP/1.12Host: api.eu.onfido.com3Authorization: Token token=<YOUR_API_TOKEN>4Content-Type: multipart/form-data
Retrieve document
Retrieves a single document. Returns a document object.
1GET /v3.1/documents/<DOCUMENT_ID> HTTP/1.12Host: api.eu.onfido.com3Authorization: Token token=<YOUR_API_TOKEN>
List documents
Lists all documents belonging to an applicant. Returns data in the form:
{"documents": [<LIST_OF_DOCUMENT_OBJECTS>]}
.
Query string parameters
applicant_id
(required): the ID of the applicant ID whose documents you want to list.
1GET /v3.1/documents?applicant_id=<APPLICANT_ID> HTTP/1.12Host: api.eu.onfido.com3Authorization: Token token=<YOUR_API_TOKEN>
Download document
Downloads specific documents belong to an applicant. If successful, the response will be the binary data representing the image.
1GET /v3.1/documents/<DOCUMENT_ID>/download HTTP/1.12Host: api.eu.onfido.com3Authorization: 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
Attribute | Description |
---|---|
id | string The unique identifier of the live photo. |
created_at | datetime The date and time at which the live photo was uploaded. |
href | string The URI of this resource. |
download_href | string The URI that can be used to download the live photo. |
file_name | string The name of the uploaded file. |
file_type | string The file type of the uploaded file. |
file_size | integer The size of the file in bytes. |
1HTTP/1.1 201 Created2Content-Type: application/json34{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.1/live_photos/<LIVE_PHOTO_ID>",11 "download_href": "/v3.1/live_photos/<LIVE_PHOTO_ID>/download"12}
Upload live photo
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
Parameter | Description |
---|---|
file | required The file to be uploaded. |
applicant_id | required The applicant_id to associate the live photo with. |
advanced_validation | optional A Boolean which defaults to true Validates that the live photo contains exactly one face. |
1POST /v3.1/live_photos/ HTTP/1.12Host: api.eu.onfido.com3Authorization: Token token=<YOUR_API_TOKEN>4Content-Type: multipart/form-data
Retrieve live photo
Retrieves a single live photo. Returns a live photo object.
1GET /v3.1/live_photos/<LIVE_PHOTO_ID> HTTP/1.12Host: api.eu.onfido.com3Authorization: Token token=<YOUR_API_TOKEN>
List live photos
Lists the live photos that belong to an applicant. Returns data in the form:
{"live_photos": [<LIST_OF_LIVE_PHOTO_OBJECTS>]}
.
Query string parameters
applicant_id
(required): the ID of the applicant whose live photos you want to list.
1GET /v3.1/live_photos/live_photos?applicant_id=<APPLICANT_ID> HTTP/1.12Host: api.eu.onfido.com3Authorization: Token token=<YOUR_API_TOKEN>
Download live photo
Downloads a live photo. If successful, the response will be the binary data representing the image.
1GET /v3.1/live_photos/<LIVE_PHOTO_ID>/download HTTP/1.12Host: api.eu.onfido.com3Authorization: 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.
Attribute | Description |
---|---|
id | string The unique identifier of the live video. |
created_at | datetime The date and time at which the live video was uploaded. |
href | string The URI of this resource. |
download_href | string The URI that can be used to download the live video. |
file_name | string The name of the uploaded file. |
file_type | string The file type of the uploaded file. |
file_size | integer The size of the file in bytes. |
challenge | array of objects Challenge the end user was asked to perform during the video recording. |
1HTTP/1.1 201 Created2Content-Type: application/json34{5 "id": "<LIVE_VIDEO_ID>",6 "created_at": "2018-05-14T16:44:53Z",7 "href": "/v3.1/live_videos/<LIVE_VIDEO_ID>",8 "download_href": "/v3.1/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 319 ]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
Retrieves a single live video. Returns the corresponding live video object.
1GET /v3.1/live_videos/<LIVE_VIDEO_ID> HTTP/1.12Host: api.eu.onfido.com3Authorization: Token token=<YOUR_API_TOKEN>
List live videos
Lists all the live videos that belong to an applicant.
Returns data in the form: {"live_videos": [<LIST_OF_LIVE_VIDEO_OBJECTS>]}
.
Query string parameters
applicant_id
(required): the ID of the applicant whose live videos you want to list.
1GET /v3.1/live_videos?applicant_id=<APPLICANT_ID> HTTP/1.12Host: api.eu.onfido.com3Authorization: Token token=<YOUR_API_TOKEN>
Download live video
Downloads a live video. Returns the binary data representing the video.
1GET /v3.1/live_videos/<LIVE_VIDEO_ID>/download HTTP/1.12Host: api.eu.onfido.com3Authorization: Token token=<YOUR_API_TOKEN>
Download live video 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.
1GET /v3.1/live_videos/<LIVE_VIDEO_ID>/frame HTTP/1.12Host: api.eu.onfido.com3Authorization: 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.
1HTTP/1.1 422 Unprocessable Entity2Content-Type: application/json34{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.
1HTTP/1.1 503 Service Unavailable2Content-Type: application/json34{5 "error": {6 "type": "frame_extraction_unavailable",7 "message": "Frame extraction is temporarily unavailable"8 }9}
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
Attribute | Description |
---|---|
id | string The unique identifier of the motion capture. |
created_at | datetime (ISO-8601) The date and time at which the motion capture was uploaded. |
href | string The URI of this resource. |
download_href | string The URI that can be used to download a motion capture. |
file_name | string The name of the uploaded file. |
file_type | string The file type of the uploaded file. |
file_size | integer The size of the file in bytes. |
1HTTP/1.1 201 Created2Content-Type: application/json34{5 "id": "<MOTION_CAPTURE_ID>",6 "created_at": "2022-11-12T17:12:44Z",7 "href": "/v3.1/motion_captures/<MOTION_CAPTURE_ID>",8 "download_href": "/v3.1/motion_captures/<MOTION_CAPTURE_ID>/download",9 "file_name": "<FILE_NAME>.mp4",10 "file_type": "video/mp4",11 "file_size": 143112112}
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
Retrieves a single motion capture. Returns the corresponding motion capture object.
1GET /v3.1/motion_captures/<MOTION_CAPTURE_ID> HTTP/1.12Host: api.onfido.com3Authorization: Token token=<YOUR_API_TOKEN>
List motion captures
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.
1GET /v3.1/motion_captures?applicant_id=<APPLICANT_ID> HTTP/1.12Host: api.onfido.com3Authorization: Token token=<YOUR_API_TOKEN>
Download motion capture
Downloads a motion capture. Returns the binary data representing the motion capture.
1GET /v3.1/motion_captures/<MOTION_CAPTURE_ID>/download HTTP/1.12Host: api.onfido.com3Authorization: Token token=<YOUR_API_TOKEN>
Download motion capture frame
Instead of the whole motion capture data, a single frame can be downloaded using this endpoint. Returns the binary data representing the frame.
1GET /v3.1/motion_captures/<MOTION_CAPTURE_ID>/frame HTTP/1.12Host: api.onfido.com3Authorization: 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.
1HTTP/1.1 422 Unprocessable Entity2Content-Type: application/json34{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.
1HTTP/1.1 503 Service Unavailable2Content-Type: application/json34{5 "error": {6 "type": "frame_extraction_unavailable",7 "message": "Frame extraction is temporarily unavailable"8 }9}
Report Types
Document report
For a 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:
-
Document (almost all use cases require this "primary" type)
-
Document with Driving Licence Information (This report will soon be deprecated. We recommend that you use the
document_with_driver_verification
report instead)
Request body in API | Notes |
---|---|
"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"] | Will soon be deprecated |
"report_names": ["document_with_driver_verification"] | In beta |
Document with Address Information, Document Video with Address Information and Document with Driver Verification Document are in beta, while Document with Driving Licence Information will soon be deprecated. 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 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, use the document_ids
field. This takes an array
of up to 2 strings (2 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 through OCR is returned in the properties
attribute.
The Document report combines software and an expert team to maximise fraud detection. The majority of documents will be processed instantly. However, when document analysis falls back to expert review, the report status will be delivered asynchronously via webhook notifications.
Expert review is required when we encounter images that use sophisticated counterfeiting techniques, or the image is of poor quality (blurred, low resolution, obscured, cropped, or held at an unreadable angle).
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
.
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 result | Description |
---|---|
clear | If all underlying verifications pass, the overall result will be clear . |
consider | If the report has returned information that needs to be evaluated, the overall result will be consider . |
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-result | Description |
---|---|
clear | If all underlying verifications pass, the overall sub result will be clear . There are no indications the document is fraudulent. |
caution | We can't successfully complete all verifications, but this doesn’t necessarily point to a suspected document (for example, expired document). |
suspected | Document shows signs of suspect fraud. |
rejected | We can't process the document image, or the document isn't supported by Onfido for processing. Another reason is if the age of the applicant is too low (the standard threshold is 16 years old but you can write to your Onfido contact to have this changed). |
Document report: Breakdowns
Breakdowns can have the values clear
and consider
.
A breakdown will have the result consider
when at least one sub-breakdown
contains a consider
or unidentified
result. For example, a consider
result
for the mrz
sub-breakdown will produce a consider
result for the
data_validation
breakdown. This will then also set the report sub_result
value to suspected
.
Some breakdowns contain sub-breakdowns. For example, the image_integrity
breakdown comprises the sub-breakdowns supported_document
, image_quality
,
colour_picture
and conclusive_document_quality
.
The possible values for sub-breakdowns are clear
, consider
, null
and
unidentified
.
Breakdown order priority
Breakdown sub-results have the following order of priority:
rejected
->suspected
->caution
->clear
For example, a caution
sub-result will only ever be asserted when the following
conditions are met:
- no individual breakdown has caused a
rejected
orsuspected
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.
See our Document report breakdown tree for an illustration of this logic:
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
and mrz
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
1expiry_date
2mrz
- 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.
- 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 ofconsider
will mean that even if sub breakdowns ofvisual_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
orunidentified
. -
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 torejected
.
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 ofsuspected
. -
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
:
-
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_present
1document_type
gender
date_of_expiry
nationality
issuing_country
document_numbers
date_of_birth
last_name
first_name
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 thedata_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 asnull
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 of compromised documents.
Document report: Breakdown reasoning
We will return a reason whenever a report flags for one of the following breakdowns:
-
visual_authenticity
:original_document_present
-
image_integrity
:conclusive_document_quality
-
image_integrity
:image_quality
This works by returning the contributing reason and corresponding fail result (a consider
result) in the breakdown properties.
There can be more than one reason per breakdown, as they aren’t mutually exclusive.
All other signals and potential reasons will be omitted.
The following diagram illustrates this logic:
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
1HTTP/1.1 201 Created2Content-Type: application/json34{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 "result": "clear"17 },18 "data_comparison": {19 "breakdown": {20 "date_of_birth": {21 "properties": {},22 "result": "clear"23 },24 "date_of_expiry": {25 "properties": {},26 "result": "null"27 },28 "document_numbers": {29 "properties": {},30 "result": "null"31 },32 "document_type": {33 "properties": {},34 "result": "null"35 },36 "first_name": {37 "properties": {},38 "result": "clear"39 },40 "gender": {41 "properties": {},42 "result": "null"43 },44 "issuing_country": {45 "properties": {},46 "result": "null"47 },48 "last_name": {49 "properties": {},50 "result": "clear"51 }52 },53 "result": "clear"54 },55 "data_consistency": {56 "breakdown": {57 "date_of_birth": {58 "properties": {},59 "result": "clear"60 },61 "date_of_expiry": {62 "properties": {},63 "result": "clear"64 },65 "document_numbers": {66 "properties": {},67 "result": "clear"68 },69 "document_type": {70 "properties": {},71 "result": "clear"72 },73 "first_name": {74 "properties": {},75 "result": "clear"76 },77 "gender": {78 "properties": {},79 "result": "clear"80 },81 "issuing_country": {82 "properties": {},83 "result": "clear"84 },85 "last_name": {86 "properties": {},87 "result": "clear"88 },89 "multiple_data_sources_present": {90 "properties": {},91 "result": "clear"92 },93 "nationality": {94 "properties": {},95 "result": "clear"96 }97 },98 "result": "clear"99 },100 "data_validation": {101 "breakdown": {102 "date_of_birth": {103 "properties": {},104 "result": "clear"105 },106 "document_expiration": {107 "properties": {},108 "result": "clear"109 },110 "document_numbers": {111 "properties": {},112 "result": "clear"113 },114 "expiry_date": {115 "properties": {},116 "result": "clear"117 },118 "gender": {119 "properties": {},120 "result": "clear"121 },122 "mrz": {123 "properties": {},124 "result": "clear"125 }126 },127 "result": "clear"128 },129 "image_integrity": {130 "breakdown": {131 "colour_picture": {132 "properties": {},133 "result": "clear"134 },135 "conclusive_document_quality": {136 "properties": {},137 "result": "clear"138 },139 "image_quality": {140 "properties": {},141 "result": "clear"142 },143 "supported_document": {144 "properties": {},145 "result": "clear"146 }147 },148 "result": "clear"149 },150 "police_record": {151 "result": "clear"152 },153 "visual_authenticity": {154 "breakdown": {155 "digital_tampering": {156 "properties": {},157 "result": "clear"158 },159 "face_detection": {160 "properties": {},161 "result": "clear"162 },163 "fonts": {164 "properties": {},165 "result": "clear"166 },167 "original_document_present": {168 "properties": {},169 "result": "clear"170 },171 "other": {172 "properties": {},173 "result": "clear"174 },175 "picture_face_integrity": {176 "properties": {},177 "result": "clear"178 },179 "security_features": {180 "properties": {},181 "result": "clear"182 },183 "template": {184 "properties": {},185 "result": "clear"186 }187 },188 "result": "clear"189 }190 },191 "check_id": "<CHECK_ID>",192 "created_at": "2021-03-22T17:13:12Z",193 "documents": [194 {195 "id": "<DOCUMENT_ID>"196 }197 ],198 "href": "/v3.1/reports/<REPORT_ID>",199 "id": "<REPORT_ID>",200 "name": "document",201 "properties": {202 "date_of_birth": "1990-01-01",203 "date_of_expiry": "2030-01-01",204 "document_numbers": [205 {206 "type": "document_number",207 "value": "999999999"208 }209 ],210 "document_type": "passport",211 "first_name": "Jane",212 "gender": "",213 "issuing_country": "GBR",214 "last_name": "Doe",215 "nationality": ""216 },217 "result": "clear",218 "status": "complete",219 "sub_result": "clear"220}
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"]
Note: When creating checks with the API, document_ids
is a required parameter for Document Video Report.
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:
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:
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:
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 will soon be deprecated. We recommend that you use the Document with Driver Verification report instead.
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:
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:
Property | Description | Value 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 permits | Boolean |
"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 for | String or Empty |
"vehicle_class_details" | Detailed classes/categories information | Array of objects or Empty |
"vehicle_class_details[].category | Vehicle class/category | String |
"vehicle_class_details[].codes | Special conditions driver must meet | String or Empty |
"vehicle_class_details[].obtainment_date | Category obtainment date | String |
"vehicle_class_details[].expiry_date | Category expiry date | String or Empty |
"manual_transmission_restriction" | True if the user is not qualified to drive a manual transmission | Boolean or Empty |
"passenger_vehicle" | Normalised data for passenger cars | Object or Empty |
"passenger_vehicle.permision_to_drive" | Whether they are qualified for a passenger car, such as a “B” class in the UK | String or Empty |
"passenger_vehicle.obtainment_date" | Date the class qualification was obtained | String or Empty |
"passenger_vehicle.expiry_date" | Date the class qualification expires, which may be different to doc expiry | String or Empty |
Example:
1...23"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]1819...
Contact your account manager for more information about the features in the Document with Driver Verification report.
Facial Similarity reports
This section contains API documentation for the Facial Similarity reports. You can also read our product documentation.
After you've familiarised yourself with the information here, you 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 name | Request 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 provided during check creation in the document_ids
field.
"document_ids": ["<DOCUMENT_ID>"]
By default, the most recently uploaded document specified will be used. Where the document has two sides, we will search both sides of the document for a face.
If unspecified, the most recently uploaded document will be used.
When 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:
Attribute | Format | Possible values |
---|---|---|
result | String | "clear" , "consider" |
image_integrity | String or null | "clear" , "consider" , null |
(sub-breakdown) face_detected | String or null | "clear" , "consider" , null |
(sub-breakdown) source_integrity 1 | String or null | "clear" , "consider" , null |
face_comparison | String or null | "clear" , "consider" , null |
(sub-breakdown) face_match 2 | String or null | "clear" , "consider" , null |
visual_authenticity | String or null | "clear" , "consider" , null |
(sub-breakdown) spoofing_detection 3 | String 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 under the properties
bag (see Facial Similarity Photo: Face Match Score)
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
Breakdown | Description |
---|---|
image_integrity | object Asserts whether the quality and integrity of the uploaded files were sufficient to perform a face comparison. |
(sub-breakdown) face_detected | object Asserts a single face of good enough quality has been found in both the document image and the live photo. |
(sub-breakdown) source_integrity | object Asserts whether the live photo is trustworthy - i.e. not digitally tampered, from a fake webcam, or from other dubious sources. |
face_comparison | object Asserts whether the face in the document matches the face in the live photo. |
(sub-breakdown) face_match | object Contains a score value under the properties bag (see Facial Similarity Photo: Match Score). |
visual_authenticity | object Asserts whether the person in the live photo is real (not a spoof). |
(sub-breakdown) spoofing_detection | object 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 softwarefake_webcam
- when evidence is found that a fake webcam was usedtime_of_capture
- when evidence is found that the live photo was taken more than 24 hours before live photo uploademulator
- when evidence is found that an Android emulator was usedsanctioned_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 aconsider
result, accompanied by areasons
property clarifying that it is not supported due to sanctionsreasons
- additional comma separated details such as the exact digital tampering software used, or the name of the fake webcam
Facial Similarity Photo: Face Match Score
The face_match
breakdown contains a properties
object with a score
value. This score is a floating point number between 0 and 1 that expresses
how similar the two faces are, where 1 is a perfect match.
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.
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.
1HTTP/1.1 201 Created2Content-Type: application/json34{5 "created_at": "2019-12-11T09:39:05Z",6 "href": "/v3.1/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.651221 }22 }23 }24 },25 "image_integrity": {26 "result": "clear",27 "breakdown": {28 "face_detected": {29 "result": "clear",30 "properties": {}31 },32 "source_integrity": {33 "result": "clear",34 "properties": {}35 }36 }37 },38 "visual_authenticity": {39 "result": "clear",40 "breakdown": {41 "spoofing_detection": {42 "result": "clear",43 "properties": {44 "score": 0.951245 }46 }47 }48 }49 },50 "check_id": "<CHECK_ID>",51 "documents": []52}
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:
Attribute | Format | Possible values |
---|---|---|
result | String | "clear" , "consider" |
image_integrity | String or null | "clear" , "consider" , null |
(sub-breakdown) face_detected | String or null | "clear" , "consider" , null |
(sub-breakdown) source_integrity 1 | String or null | "clear" , "consider" , null |
face_comparison | String or null | "clear" , "consider" , null |
(sub-breakdown) face_match 2 | String or null | "clear" , "consider" , null |
visual_authenticity | String or null | "clear" , "consider" , null |
(sub-breakdown) spoofing_detection 3 | String 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 under the properties
bag (see Face Match Score 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
Breakdown | Description |
---|---|
image_integrity | object Asserts whether the quality and integrity of the uploaded files were sufficient to perform a face comparison. |
(sub-breakdown) face_detected | object Asserts a single face of good enough quality has been found in both the document image and the live photo. |
(sub-breakdown) source_integrity | object Asserts whether the live photo is trustworthy - i.e. not digitally tampered, from a fake webcam, or from other dubious sources. |
face_comparison | object Asserts whether the face in the document matches the face in the live photo. |
(sub-breakdown) face_match | object Contains a score value under the properties bag (see Face Match Score for Fully Auto). |
visual_authenticity | object Asserts whether the person in the live photo is real (not a spoof). |
(sub-breakdown) spoofing_detection | object 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 softwarefake_webcam
- when evidence is found that a fake webcam was usedtime_of_capture
- when evidence is found that the live photo was taken more than 24 hours before live photo uploademulator
- when evidence is found that an Android emulator was usedsanctioned_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 aconsider
result, accompanied by areasons
property clarifying that it is not supported due to sanctionsreasons
- additional comma separated details such as the exact digital tampering software used, or the name of the fake webcam
Photo Fully Auto: Face Match Score
The face_match
breakdown contains a properties
object with a score
value. This score is a floating point number between 0 and 1 that expresses
how similar the two faces are, where 1 is a perfect match.
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.
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.
1HTTP/1.1 201 Created2Content-Type: application/json34{5 "created_at": "2020-01-01T14:16:21Z",6 "href": "/v3.1/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.990120 }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.209744 }45 }46 }47 }48 },49 "check_id": "<CHECK_ID>"50}
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 name | Language 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:
Attribute | Format | Possible values |
---|---|---|
result | String | "clear" , "consider" |
image_integrity | String or null | "clear" , "consider" , null |
(sub-breakdown) face_detected | String or null | "clear" , "consider" , null |
(sub-breakdown) source_integrity 1 | String or null | "clear" , "consider" , null |
face_comparison | String or null | "clear" , "consider" , null |
(sub-breakdown) face_match 2 | String or null | "clear" , "consider" , null |
visual_authenticity | String or null | "clear" , "consider" , null |
(sub-breakdown) spoofing_detection 3 | String or null | "clear" , "consider" , null |
(sub-breakdown) liveness_detected | String 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 under the properties
bag (see Facial Similarity Video: Face Match Score)
3: spoofing_detection
contains a score
value under the properties
bag (see Facial Similarity Video: Spoofing Detection Score)
Facial Similarity Video: Breakdowns
Breakdown | Description |
---|---|
face_comparison | object Asserts whether the face in the document matches the face in the live video. |
(sub-breakdown) face_match | object Contains a score value (see Facial Similarity Video Match Score). |
image_integrity | object Asserts whether the quality of the uploaded files and the content contained within them were sufficient to perform a face comparison. |
(sub-breakdown) face_detected | object Asserts a single face of good enough quality has been found in both the document image and in the live video. |
(sub-breakdown) source_integrity | object Asserts whether the live video is trustworthy - e.g. not from a fake webcam. |
visual_authenticity | object Asserts whether the person in the live video is real (not a spoof) and live. |
(sub-breakdown) spoofing_detection | object Asserts whether the live video is not a spoof (such as videos of digital screens). |
(sub-breakdown) liveness_detected | object 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 usedemulator
- when evidence is found that an Android emulator was usedchallenge_reuse
- when evidence is found that the video was uploaded in an attempt to circumvent the randomness of the speaking and head turn challengessanctioned_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 aconsider
result, accompanied by areasons
property clarifying that it is not supported due to sanctionsreasons
- additional comma separated details, such as the name of the fake webcam
Facial Similarity Video: Face Match Score
The face_match
breakdown contains a properties
object with a score
value. This score is a floating point number between 0 and 1 that expresses
how similar the two faces are, where 1 is a perfect match.
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.
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.
1HTTP/1.1 201 Created2Content-Type: application/json34{5 "created_at": "2019-12-11T10:06:38Z",6 "href": "/v3.1/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.651221 }22 }23 }24 },25 "image_integrity": {26 "result": "clear",27 "breakdown": {28 "face_detected": {29 "result": "clear",30 "properties": {}31 },32 "source_integrity": {33 "result": "clear",34 "properties": {}35 }36 }37 },38 "visual_authenticity": {39 "result": "clear",40 "breakdown": {41 "liveness_detected": {42 "result": "clear",43 "properties": {}44 },45 "spoofing_detection": {46 "result": "clear",47 "properties": {48 "score": 0.951249 }50 }51 }52 }53 },54 "check_id": "<CHECK_ID>",55 "documents": []56}
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:
Attribute | Format | Possible values |
---|---|---|
result | String | "clear" , "consider" |
image_integrity | String or null | "clear" , "consider" , null |
(sub-breakdown) face_detected | String or null | "clear" , "consider" , null |
(sub-breakdown) source_integrity 1 | String or null | "clear" , "consider" , null |
face_comparison | String or null | "clear" , "consider" , null |
(sub-breakdown) face_match 2 | String or null | "clear" , "consider" , null |
visual_authenticity | String or null | "clear" , "consider" , null |
(sub-breakdown) spoofing_detection 3 | String or null | "clear" , "consider" , null |
(sub-breakdown) liveness_detected | String 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 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
Breakdown | Description |
---|---|
face_comparison | object Asserts whether the face in the document matches the face in the motion capture. |
(sub-breakdown) face_match | object Contains a score value (see Facial Similarity Motion Match Score). |
image_integrity | object Asserts whether the quality of the uploaded files and the content contained within them were sufficient to perform a face comparison. |
(sub-breakdown) face_detected | object Asserts a face of good enough quality has been found in both the document image and in the motion capture. |
(sub-breakdown) source_integrity | object Asserts whether the motion capture is trustworthy - e.g. not from a fake webcam. |
visual_authenticity | object Asserts whether the person in the motion capture is real (not a spoof) and live. |
(sub-breakdown) spoofing_detection | object Asserts whether the motion capture is not a spoof (such as videos of digital screens). |
(sub-breakdown) liveness_detected | object 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 usedemulator
- when evidence is found that an Android emulator was usedpayload_integrity
- when evidence is found that the payload was tampered withsanctioned_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 aconsider
result, accompanied by areasons
property clarifying that it is not supported due to sanctionsreasons
- 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. This score is a floating point number between 0 and 1 that expresses
how similar the two faces are, where 1 is a perfect match.
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.
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.
1HTTP/1.1 201 Created2Content-Type: application/json34{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.1/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.951256 }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 section contains API documentation for the Known Faces report. You can also 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:
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:
Attribute | Format | Possible values |
---|---|---|
result | String | "clear" , "consider" |
previously_seen_faces | String or null 1 | "clear" , "consider" , null |
image_integrity | String | "clear" , "consider" |
null
is returned whenimage_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
Breakdown | Description |
---|---|
previously_seen_faces | object Asserts whether the applicant's most recent facial media (live photo or live video) matches any other live photos or live videos already in your Onfido account database. |
image_integrity | object Asserts whether the uploaded live photo or live video and the content contained within it were of sufficient quality to perform a face comparison. |
Known Faces: Score
The Known Faces response will return any matching applicant IDs as entries
inside a matches
array under a properties
bag. Each applicant ID has a
corresponding score
and the media type (for example live_photos
or
live_videos
), and the corresponding UUID for that media type. For example,
the live photo or live video ID.
This score is a floating point number between 0 and 1 that expresses how similar the two faces are, where 1 is a perfect match.
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 }8]
If any matches are found, the response will also contain "result": "consider"
.
1HTTP/1.1 201 Created2Content-Type: application/json34{5 "created_at": "2020-06-19T09:44:14Z",6 "documents": [],7 "href": "/v3.1/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 },18 {19 "applicant_id": "<2ND_MATCHED_APPLICANT_ID>",20 "score": 1,21 "media_id": "<2ND_MEDIA_ID>",22 "media_type": "live_videos"23 },24 {25 "applicant_id": "<3RD_MATCHED_APPLICANT_ID>",26 "score": 0.8903,27 "media_id": "<3RD_MEDIA_ID>",28 "media_type": "live_photos"29 },30 {31 "applicant_id": "<4TH_MATCHED_APPLICANT_ID>",32 "score": 0.8903,33 "media_id": "<4TH_MEDIA_ID>",34 "media_type": "live_photos"35 },36 {37 "applicant_id": "<5TH_MATCHED_APPLICANT_ID>",38 "score": 0.8903,39 "media_id": "<5TH_MEDIA_ID>",40 "media_type": "motion"41 }42 ]43 },44 "result": "consider",45 "status": "complete",46 "sub_result": null,47 "breakdown": {48 "previously_seen_faces": {49 "result": "consider"50 },51 "image_integrity": {52 "result": "clear"53 }54 },55 "check_id": "<CHECK_ID>"56}
Identity Enhanced report
This section contains API documentation for the Identity Enhanced report. You can also read our product documentation, which includes a list of the sources used in the Identity Enhanced report, with corresponding definitions, and the report logic.
To request an Identity Enhanced report as part of a check in the API, use the
report_names
field (which takes an array of strings):
"report_names": ["identity_enhanced"]
For checks containing Identity Enhanced reports, the applicant's last name must have at least 2 characters.
Required applicant data
For Identity Enhanced reports, the following applicant data must be provided:
-
first_name
-
last_name
-
dob
-
address.flat_number
oraddress.building_number
oraddress.building_name
-
address.street
-
address.state
(US only) -
address.postcode
(ZIP code in US) -
address.country
(must be a 3-letter ISO code e.g. "GBR")
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.
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. The column Identity Enhanced
Report on that page lists supported
and unsupported
countries.
This is not a list of documents that Onfido supports: you can review that list separately.
Identity Enhanced: Report 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.
1HTTP/1.1 201 Created2Content-Type: application/json34{5 "created_at": "2019-10-03T15:54:20Z",6 "href": "/v3.1/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": {46 "result": "clear",47 "properties": {}48 },49 "voting_register": {50 "result": "clear",51 "properties": {}52 }53 }54 },55 "date_of_birth": {56 "result": "clear",57 "breakdown": {58 "credit_agencies": {59 "result": "clear",60 "properties": {}61 },62 "voting_register": {63 "result": "clear",64 "properties": {}65 }66 }67 },68 "mortality": {69 "result": "clear"70 }71 },72 "check_id": "<CHECK_ID>",73 "documents": []74}
United States
Example report object where the applicant's address is in the United States.
Any elements that are positively matched will be returned as clear
in the report object breakdowns, including the source or sources of the database match in the properties field. When a match cannot be found (i.e. result
is not clear
) the corresponding properties
bucket will be empty as such "properties":{}
.
The report includes Social Security Number for a US applicant as an additional match under the ssn
breakdown. This breakdown will not be returned if a SSN is not provided.
If an Identity enhanced report includes a Social Security Number breakdown, this will be returned in the ssn
object for a report that was run using the using the https://api.us.onfido.com/
base URL, and ssn1
for a report that was run using the https://api.eu.onfido.com/
base URL.
1HTTP/1.1 201 Created2Content-Type: application/json34{5 "check_id": "<CHECK_ID>",6 "created_at": "2022-05-06T08:44:54Z",7 "documents": [],8 "href": "/v3.1/reports/<REPORT_ID>",9 "id": "<REPORT_ID>",10 "name": "identity_enhanced",11 "properties": {},12 "result": "clear",13 "status": "complete",14 "sub_result": null,15 "breakdown": {16 "date_of_birth": {17 "result": "clear",18 "breakdown": {19 "date_of_birth_matched": {20 "result": "clear",21 "properties": {22 "sources": "Credit Agencies"23 }24 }25 }26 },27 "address": {28 "result": "clear",29 "breakdown": {30 "address_matched": {31 "result": "clear",32 "properties": {33 "sources": "Credit Agencies, Telephone Database"34 }35 }36 }37 },38 "ssn": {39 "result": "clear",40 "breakdown": {41 "last_4_digits_match": {42 "result": "clear",43 "properties": {}44 },45 "full_match": {46 "result": "clear",47 "properties": {}48 }49 }50 }51 }
Non UK or US
Example report object where the applicant's address is not the United Kingdom or United States.
Sources are shown as comma separated under properties
.
1HTTP/1.1 201 Created2Content-Type: application/json34{5 "check_id": "<CHECK_ID>",6 "created_at": "2022-05-06T08:44:54Z",7 "documents": [],8 "href": "/v3.1/reports/<REPORT_ID>",9 "id": "<REPORT_ID>",10 "name": "identity_enhanced",11 "properties": {},12 "result": "clear",13 "status": "complete",14 "sub_result": null,15 "breakdown": {16 "date_of_birth": {17 "result": "clear",18 "breakdown": {19 "date_of_birth_matched": {20 "result": "clear",21 "properties": {22 "sources": "Credit Agencies"23 }24 }25 }26 },27 "address": {28 "result": "clear",29 "breakdown": {30 "address_matched": {31 "result": "clear",32 "properties": {33 "sources": "Credit Agencies, Telephone Database"34 }35 }36 }37 }38 }39}
Identity Enhanced report custom logic
We've moved this content.
Watchlist reports
This section contains API documentation for the Onfido Watchlist reports. You can also read our product documentation.
There are 5 different types of Watchlist report:
Report name | Request body in API |
---|---|
Watchlist AML | "report_names": ["watchlist_aml"] |
Watchlist Enhanced | "report_names": ["watchlist_enhanced"] |
Watchlist Standard | "report_names": ["watchlist_standard"] |
Watchlist PEPs Only | "report_names": ["watchlist_peps_only"] |
Watchlist Sanctions Only | "report_names": ["watchlist_sanctions_only"] |
Watchlist AML
The Watchlist AML report provides a granular breakdown of any records found when screening global watchlists and media sources. These include:
sanction
: Government and International Organisations Sanctions Listspolitically_exposed_person
: Proprietary database of Politically Exposed Persons sourced from government lists, websites and other media sourceslegal_and_regulatory_warnings
: Law-Enforcement and Regulatory bodies Monitored Lists (including Terrorism, Money Laundering and Most Wanted lists)adverse_media
: Negative events reported by publicly and generally available media sources
Records
If no match is found against the subject, the records
field will read []
and the overall result
will be clear
.
If one or more matches are found, each match will be returned under records
and the overall result
will be consider
.
As matches are done based on the available information, none of these properties are guaranteed to be present in the response.
Field | Description |
---|---|
associates | string Any linked persons, for example family relatives or business partners |
keywords | string |
last_updated_utc | string The date and time the entry was last updated |
entity_type | string Should always be "person" |
sources | string Where the information was obtained, for example "PEPs list" |
types | string The type of the source, for example "pep-class-1" |
name | string The name on file. Allows for custom cross-referencing of input details against output details |
external_id | string Returns an empty string |
match_types | string The type of match, for example, "name_exact" |
related_urls | string URL to the data source |
picture_urls | string URL to the picture of the individual found in the match |
all_dobs | string All the date of births on file. Allows for custom cross-referencing of input details against output details |
report_id | integer The ID of the report |
entity_fields_dobs | string Date of birth |
entity_fields_dod | string Date of death |
entity_fields_pod | string Place of birth |
entity_fields_ofac | string Office of Foreign Assets Control (OFAC) ID |
entity_fields_address | string Address |
entity_fields_countries | string Countries |
Where applicable, if multiple values are found from the raw response, string concatenation with a delimiter of ", " is used.
Entity fields are additional, optional fields so they may not be present in the final result.
Required applicant data
For watchlist_aml
reports, first_name
and last_name
must be provided.
Recommended applicant data
dob
address[]postcode
(ZIP code in US)
address[]country
address[]state
(required for US addresses)
Date of birth
Submitting a date_of_birth
with the name is optional but recommended, to narrow the search of the relevant individual.
More than one date of birth might be found per match due to the nature of the data sources, such as newspaper articles, which might include someone's age but not their full date of birth.
Address
Submitting an address
with the country is optional but recommended.
The applicant address object is nested inside the applicant object.
Results are filtered by country of operation or office, under these circumstances:
- There are PEP matches only
- There are PEP matches with Adverse Media
The country filter is not applied, or in other words, results will still appear regardless of the address country, under these circumstances:
- There are adverse media matches only
- Address does not have a country
- Sanctions, Money Laundering or Terrorist related events will always appear even if the country filter is applied
If a match is found but the date_of_birth
or address
fields are null
, this means there is no date_of_birth
or address
data on file associated with that match.
1HTTP/1.1 201 Created2Content-Type: application/json34{5 "created_at": "2019-10-03T15:42:36Z",6 "href": "/v3.1/reports/<REPORT_ID>",7 "documents": [],8 "id": "<REPORT_ID>",9 "name": "watchlist_aml",10 "properties": {11 "records": []12 },13 "result": "clear",14 "status": "complete",15 "sub_result": null,16 "breakdown": {17 "sanction": {18 "result": "clear"19 },20 "politically_exposed_person": {21 "result": "clear"22 },23 "legal_and_regulatory_warnings": {24 "result": "clear"25 },26 "adverse_media": {27 "result": "clear"28 }29 },30 "check_id": "<CHECK_ID>"31}
Watchlist Enhanced
The Watchlist Enhanced report provides a granular breakdown of any records found when screening global watchlists and media sources. These include the following breakdowns:
sanction
: Government and International Organisations Sanctions Lists.politically_exposed_person
: Proprietary database of Politically Exposed Persons sourced from government lists, websites and other media sources.monitored_lists
: Law-Enforcement and Regulatory bodies Monitored Lists (including Terrorism, Money Laundering and Most Wanted lists).adverse_media
: Negative events reported by publicly and generally available media sources.
Records
If no match is found against the subject, the records
field will read []
and the overall result
will be clear
.
If one or more matches are found, each match will be returned under records
and the overall result
will be consider
. Each event will correspond to a relevant category of list, which drives one of the breakdowns.
As matches are done based on the available information, none of these properties are guaranteed to be present in the response.
Field | Description | Sub-fields |
---|---|---|
address | array of objects All addresses on file | address_line1 country postal_code state_province town locator_type |
alias | array of objects Any names that the person is also known as | alias_name alias_type |
associate | array of objects Any linked persons, for example family relatives or business partners | entity_name relationship_direction relationship_type |
attribute | array of objects Information about the person, for example hair color or nationality | attribute_type attribute_value |
date_of_birth | array of DOB objects All the date of births on file | |
event | array of objects Information about events that have occurred to the person, for example deportation or arrest | category event_date event_description source (source_date, source_format, source_name) sub_category |
full_name | string The name on file | |
position | array of strings The role, country and date of each position | |
source | array of objects Details about where the information was obtained | source_headline source_name source_url |
Required applicant data
For watchlist_enhanced
reports, first_name
and last_name
must be provided.
Recommended applicant data
dob
address[]postcode
(ZIP code in US)
address[]country
address[]state
(required for US addresses)
Date of birth
Submitting a date_of_birth
with the name is optional but recommended, to narrow the search of the relevant individual.
More than one date of birth might be found per match due to the nature of the data sources, such as newspaper articles, which might include someone's age but not their full date of birth.
Address
Address
Submitting an address
with the country is optional but recommended.
The applicant address object is nested inside the applicant object.
Results are filtered by country of operation or office, under these circumstances:
- There are PEP matches only
- There are PEP matches with Adverse Media
The country filter is not applied, or in other words, results will still appear regardless of the address country, under these circumstances:
- There are adverse media matches only
- Address does not have a country
- Sanctions, Money Laundering or Terrorist related events will always appear even if the country filter is applied
If a match is found but the date_of_birth
or address
fields are null
, this means there is no date_of_birth
or address
data on file associated with that match.
1HTTP/1.1 201 Created2Content-Type: application/json34{5 "created_at": "2019-10-03T15:37:03Z",6 "href": "/v3.1/reports/<REPORT_ID>",7 "id": "<REPORT_ID>",8 "name": "watchlist_enhanced",9 "properties": {10 "records": []11 },12 "result": "clear",13 "status": "complete",14 "sub_result": null,15 "breakdown": {16 "politically_exposed_person": {17 "result": "clear"18 },19 "sanction": {20 "result": "clear"21 },22 "adverse_media": {23 "result": "clear"24 },25 "monitored_lists": {26 "result": "clear"27 }28 },29 "check_id": "<CHECK_ID>",30 "documents": []31}
Watchlist Standard
The Watchlist Standard report provides a granular breakdown of any records found when screening global watchlists. These include:
sanction
: Government and International Organisations Sanctions Lists.politically_exposed_person
: Proprietary database of Politically Exposed Persons sourced from government lists, websites and other media sources.legal_and_regulatory_warnings
: Law-Enforcement and Regulatory bodies Monitored Lists (including Terrorism, Money Laundering and Most Wanted lists).
You can use a Watchlist PEPs Only report to search only PEPs lists, or a Watchlist Sanctions Only` report to search only sanctions and warnings lists. The Watchlist Standard report will search all types.
Records
If no match is found against the subject, the records
field will read []
and the overall result
will be clear
.
If one or more matches are found, each match will be returned under records
and the overall result
will be consider
.
See Watchlist AML records for details of the possible fields.
Required applicant data
For watchlist_standard
reports, first_name
and last_name
must be provided.
Recommended applicant data
dob
address[]postcode
(ZIP code in US)
address[]country
address[]state
(required for US addresses)
The applicant address object is nested inside the applicant object. If you create an applicant object with an address, you must provide postcode and country, and state for US addresses.
If the applicant's address is provided, the address[]country
field will narrow the search to include only PEPs who hold office in that country. The country filter will also be applied if an individual is both a PEP and has warnings or adverse media.
The country filter has no impact on sanctions results.
1HTTP/1.1 201 Created2Content-Type: application/json34{5 "created_at": "2019-10-03T15:42:36Z",6 "href": "/v3.1/reports/<REPORT_ID>",7 "id": "<REPORT_ID>",8 "name": "watchlist_standard",9 "properties": {10 "records": []11 },12 "result": "clear",13 "status": "complete",14 "sub_result": null,15 "breakdown": {16 "sanction": {17 "result": "clear"18 },19 "politically_exposed_person": {20 "result": "clear"21 },22 "legal_and_regulatory_warnings": {23 "result": "clear"24 }25 },26 "check_id": "<CHECK_ID>",27 "documents": []28}
Watchlist PEPs Only
The Watchlist PEPs Only report is a subset of the Watchlist Standard report. It provides a granular breakdown of politically_exposed_person
breakdown matches.
Each match will be returned under records
and includes, but is not limited
to: name of match, associates, date of birth, related keywords, type of list,
name of list, and when the entry was last updated. When available, URLs to
data sources are provided, as well as pictures of the individual found in the
match. This allows you to quickly assess the relevancy of the match and
eliminate false positives. See Watchlist AML records for details of the possible fields.
More than one date of birth might be found per match, due to the nature of the data sources, such as news papers articles, which might include someone's age but not their full date of birth.
Required applicant data
For watchlist_peps_only
reports, first_name
and last_name
must be provided.
Recommended applicant data
dob
If applicant's address is provided, address[]country
field will be treated as the country where the PEP holds office, not the applicant nationality.
Watchlist Sanctions Only
The Watchlist Sanctions Only report is a subset of the Watchlist Standard report. It provides a granular breakdown of sanction
breakdown matches.
Each match will be returned under records
and includes, but is not limited
to: name of match, associates, date of birth, related keywords, type of list,
name of list, and when the entry was last updated. When available, URLs to
data sources are provided, as well as pictures of the individual found in the
match. This allows you to quickly assess the relevancy of the match and
eliminate false positives. See Watchlist AML records for details of the possible fields.
More than one date of birth might be found per match, due to the nature of the data sources, such as news papers articles, which might include someone's age but not their full date of birth.
Required applicant data
For Watchlist Sanctions Only reports, first_name
and last_name
must be provided.
Recommended applicant data
dob
Proof of Address report
This section contains API documentation for the Proof of Address report. You can also read our product documentation , which contains a guide on the logic the Proof of Address report uses.
To request a Proof of Address report as part of a check in the API,
use the report_names
field (which takes an array of strings):
"report_names": ["proof_of_address"]
The Proof of Address (PoA) report is for use with UK documents only.
You must set the issuing_country
field to "GBR"
when uploading the document via the document upload endpoint.
If the issuing_country
field is not specified or is from an unsupported country, the document will be uploaded however it will not be processed and the report will complete with the status set to withdrawn
and the result set to null
.
Applicants are able to upload documents from anywhere in the world, but the document must have been issued by the United Kingdom and be a supported document for this report.
Required applicant data
For Proof of Address reports, the following applicant data must be provided:
first_name
last_name
address[]street
address[]town
address[]postcode
address[]country
(must be a 3-letter ISO code e.g. "GBR")
The applicant address object is nested inside the applicant object. If you create an applicant object with an address, you must provide postcode and country, and state for US addresses.
Checks where applicant_provides_data
is set to true
are not compatible
with Proof of Address reports.
Supported document types
The following document types are supported for a PoA report:
Document | API document type |
---|---|
Bank Statement/Building Society Statements | bank_building_society_statement |
Utility Bill (electricity, water, gas, broadband ) | utility_bill |
Local Government Tax Letter | council_tax |
Benefits Letter (i.e. Job seeker allowance, House benefits, Tax credits) | benefit_letters |
Proof of Address: Breakdowns
A PoA report is composed of the following 3 breakdowns:
Breakdown | Description |
---|---|
image_integrity | object Asserts whether the quality of the uploaded document was sufficient to verify the address |
document_classification | object Asserts whether the document is a supported document type |
data_comparison | object Asserts whether the first name, last name and address provided by the applicant match those on the PoA document |
source_integrity | object Asserts whether the source integrity of the uploaded document is sufficient to verify the address |
Proof of Address: Properties
In addition, data points extracted from PoA documents are returned in the properties
attribute.
Field | Description |
---|---|
document_type | This property provides the document type according to the set of supported documents |
issue_date | This property provides the issue date of the document |
expiry_date | This property provides the expiry date of the document |
summary_period_start | This property provides the summary period start date |
summary_period_end | This property provides the summary period end date |
issuer | This property provides the document issuer (e.g. HSBC, British Gas) |
first_names | This property provides the first names on the document, including any initials and middle names |
last_names | This property provided the last names on the document |
address | This property provides the address on the document |
Only the summary period or the issue date will be returned in the report properties attribute as they are mutually exclusive. Issue date may not be returned if document has only expiry date.
Proof of Address report: Overall Result Logic
We've moved this content.
1HTTP/1.1 201 Created2Content-Type: application/json34{5 "created_at": "2021-04-27T14:51:35Z",6 "documents": [],7 "href": "/v3.1/reports/<REPORT_ID>",8 "id": "<REPORT_ID>",9 "name": "proof_of_address",10 "properties": {11 "document_type": "council_tax",12 "issuer": "city of london",13 "issue_date": "2020-01-01",14 "first_names": "John",15 "last_names": "Smith",16 "address": "123 sample street london xyz 1ab"17 },18 "result": "clear",19 "status": "complete",20 "sub_result": null,21 "breakdown": {22 "image_integrity": {23 "result": "clear",24 "breakdown": {25 "image_quality": {26 "result": "clear",27 "properties": {}28 }29 }30 },31 "document_classification": {32 "result": "clear",33 "breakdown": {34 "supported_document": {35 "result": "clear",36 "properties": {}37 }38 }39 },40 "data_comparison": {41 "result": "clear",42 "breakdown": {43 "first_name": {44 "result": "clear",45 "properties": {}46 },47 "last_name": {48 "result": "clear",49 "properties": {}50 },51 "address": {52 "result": "clear",53 "properties": {}54 }55 }56 },57 "source_integrity": {58 "result": "clear",59 "breakdown": {60 "digital_tampering": {61 "result": "clear",62 "properties": {}63 }64 }65 }66 },67 "check_id": "<CHECK_ID>"68}
Driver's License Data Verification report
This section contains API documentation for the Driver's License Data Verification (DLDV) report. You can also read our product documentation.
The DLDV report is for United States documents only.
To request a DLDV report as part of a check in the API, use the report_names
field (which takes an array of strings):
"report_names": ["us_driving_licence"]
To upload document data, use the us_driving_licence
field (which is an object containing all accepted fields for the DLDV report).
1...2"report_names": ["us_driving_licence"],3"us_driving_licence":{4 "id_number": "<DRIVER_LICENCE_ID>", // required5 "issue_state": "<TWO_LETTER_STATE_CODE>", // required6 ... // all other optional fields7 }8...
See optional document data for a table of the accepted optional fields in the us_driving_licence
object for a DLDV report.
See create a check for a full list of the possible request body parameters.
If you use this report, Onfido will use a third-party subprocessor to verify driving license data against the American Association of Motor Vehicle Administrators (AAMVA) facilitated Department of Motor Vehicles (DMV) driver's license database.
Required applicant data
For DLDV reports, first_name
and last_name
must be provided.
Required document data
For DLDV reports, the following document data must be provided in the report request in the us_driving_licence
field:
Field | Format |
---|---|
id_number | String |
issue_state | String (2-character state code) |
Optional document data
The following optional fields are also accepted in the us_driving_licence
object:
Field | Format | Possible values |
---|---|---|
address_line_1 | String | |
address_line_2 | String | |
city | String | |
date_of_birth | Date YYYY-MM-DD | |
document_category | Enum | "driver license", "driver permit", "id card" |
expiration_date | Date YYYY-MM-DD | |
eye_color_code | Enum | "BLK", "BLU", "BRO", "DIC", "GRY", "GRN", "HAZ", "MAR", "PNK" |
first_name | String | |
gender | String | |
height_measure_feet | Integer | |
height_measure_inches | Integer | |
issue_date | Date YYYY-MM-DD | |
last_name | String | |
middle_name | String | |
name_suffix | String | |
postal_code | String | |
state | String (2-character state code) | |
weight_measure | Integer (in pounds) |
Supported document types
- US driver's license
- US learner's permit or provisional license
- ID card
A DLDV report does not require a document upload. Data is entered manually in the report request.
Supported Issue States
- AR
- AZ
- CO
- CT
- DC
- DE
- HI
- FL
- IA
- ID
- IN
- IL
- KS
- KY
- MA
- MD
- ME
- MI
- MO
- MS
- MT
- NC
- ND
- NE
- NJ
- NM
- OH
- PA
- RI
- SD
- TN
- TX
- VA
- VT
- WI
- WA
- WY
- GA
- OR
DLDV: Results
The result
field indicates the overall report result. Any optional fields submitted in the report request will be accounted for in the final result.
Possible values for
DLDV reports are clear
, consider
and unidentified
:
Report result | Description |
---|---|
clear | All fields exact match |
consider | Name fields have been flagged as a mismatch through fuzzy matching* or any optional fields don't match |
unidentified | ID number or name field doesn't match |
* Onfido's third-party subprocessor uses fuzzy matching on the name fields during DLDV checks. This is because information can be provided in many different ways and errors in data submission or collection can be quite high.
DLDV: Breakdowns
Breakdowns can have a clear
or consider
result. Breakdowns will only have a clear
result when all included sub-breakdowns are clear
.
Breakdown | description | sub-breakdowns |
---|---|---|
document | object Asserts whether the document data provided matches a real driving license in the DMV driver's license database. | category expiration_date issue_date document_number |
address | object Asserts whether the address data provided matches a real driving license in the DMV driver's license database. | city line_1 line_2 state_code zip4 zip5 |
personal | object Asserts whether the personal data provided matches a real driving license in the DMV driver's license database. | name_suffix height weight sex_code eye_color date_of_birth first_name last_name middle_name first_name_fuzzy middle_name_fuzzy last_name_fuzzy middle_initial |
1HTTP/1.1 201 Created2Content-Type: application/json34{5 "created_at": "2021-03-26T19:51:37Z",6 "documents": [],7 "href": "/v3.1/reports/<REPORT_ID>",8 "id": "<REPORT_ID>",9 "name": "us_driving_licence",10 "properties": {},11 "result": "clear",12 "status": "complete",13 "sub_result": null,14 "breakdown": {15 "document": {16 "result": "clear",17 "breakdown": {18 "category": {19 "result": "clear",20 "properties": {}21 },22 "expiration_date": {23 "result": "clear",24 "properties": {}25 },26 "issue_date": {27 "result": "clear",28 "properties": {}29 },30 "document_number": {31 "result": "clear",32 "properties": {}33 }34 }35 },36 "address": {37 "result": "clear",38 "breakdown": {39 "city": {40 "result": "clear",41 "properties": {}42 },43 "line_1": {44 "result": "clear",45 "properties": {}46 },47 "line_2": {48 "result": "clear",49 "properties": {}50 },51 "state_code": {52 "result": "clear",53 "properties": {}54 },55 "zip4": {56 "result": "clear",57 "properties": {}58 },59 "zip5": {60 "result": "clear",61 "properties": {}62 }63 }64 },65 "personal": {66 "result": "clear",67 "breakdown": {68 "first_name": {69 "result": "clear",70 "properties": {}71 },72 "name_suffix": {73 "result": "clear",74 "properties": {}75 },76 "height": {77 "result": "clear",78 "properties": {}79 },80 "weight": {81 "result": "clear",82 "properties": {}83 },84 "sex_code": {85 "result": "clear",86 "properties": {}87 },88 "eye_color": {89 "result": "clear",90 "properties": {}91 },92 "date_of_birth": {93 "result": "clear",94 "properties": {}95 },96 "last_name": {97 "result": "clear",98 "properties": {}99 },100 "middle_name": {101 "result": "clear",102 "properties": {}103 },104 "first_name_fuzzy": {105 "result": "clear",106 "properties": {}107 },108 "middle_name_fuzzy": {109 "result": "clear",110 "properties": {}111 },112 "last_name_fuzzy": {113 "result": "clear",114 "properties": {}115 },116 "middle_initial": {117 "result": "clear",118 "properties": {}119 }120 }121 }122 },123 "check_id": "<CHECK_ID>"124}
Other Endpoints
Ping
Runs a health check on the Onfido API.
If the regional base URL you're using is operational, the ping
endpoint will return OK
in
Text format.
You can also subscribe to webhook notifications from https://status.onfido.com.
1GET /ping HTTP/1.12Host: api.eu.onfido.com
Webhooks
About webhooks
Onfido provides webhooks to alert you of changes in the status of your resources (i.e. checks and reports). These are POST requests to your server that are sent as soon as an event occurs. The body of the request contains details of the event.
You can create and configure up to 20 webhooks to receive status changes from live, sandbox or both environments.
Retry logic
Upon receiving a webhook notification, you should acknowledge success by
responding with an HTTP 20x
response within 10 seconds. Otherwise, we will
attempt to resend the notification 5 times according to the following
schedule:
- 30 seconds after the first attempt
- 2 minutes after the first attempt
- 15 minutes after the first attempt
- 2 hours after the first attempt
- 10 hours after the first attempt
We also use circuit breaking for webhooks: if any 5 requests to the same webhook fail in a row, then that webhook will be disabled for one minute.
Testing
You can quickly inspect webhook requests with temporary endpoint URLs. You can create these using free hosted services such as https://webhook.site.
Security
The webhook URL must use HTTPS and both TLSv1.2
and TLSv1.3
versions are supported.
Duplicate events
We guarantee at-least-once delivery of webhooks, which means that in rare occasions you may receive duplicate events. You should treat events as idempotent to avoid unwanted effects in your application.
Ordering
Onfido doesn't guarantee order when delivering events. As a result, you may receive an event before another event that was created earlier. You should expect to receive them out of order and handle them accordingly.
Webhook object
Attribute | Description |
---|---|
id | string The unique identifier for the webhook. |
url | string The url to listen to notifications (must be HTTPS). |
enabled | Boolean Determines if the webhook should be active. If omitted, will be set to true by default. |
events | array The events that should be published to the webhook. If omitted, all events will be subscribed by default. You can read about the supported events. |
token | string The webhook token (read more about verifying webhook signatures. |
href | string The URI of this resource. |
environments | array Lists the environments that the webhook will receive events from. |
1HTTP/1.1 200 OK2Content-Type: application/json34{5 "webhooks": [6 {7 "id": "<WEBHOOK_ID>",8 "url": "https://demo.com",9 "enabled": false,10 "href": "/v3.1/webhooks/<WEBHOOK_ID>",11 "token": "<WEBHOOK_TOKEN>",12 "environments": [13 "sandbox"14 ],15 "events": [16 "check.started"17 ]18 }19 ]20}
Webhook IP addresses
All webhook requests will come from the following IPs:
Europe:
52.51.171.25
52.51.228.228
52.51.234.203
United States:
34.232.2.222
52.55.124.58
34.224.182.19
Canada:
15.223.105.11
15.222.176.53
15.222.71.172
Please make sure that you allow these IPs in order to receive webhook notifications.
Events
By default, webhooks are subscribed to all events, but can be subscribed to a
subset using the events
array.
Beware that some webhooks payload may contain personal data, such as audit_log.created
, watchlist_monitor.matches_updated
, or Studio related resources (workflow_* events).
You can configure the following events to trigger a message to registered webhooks:
Resource | Events | Description |
---|---|---|
check | check.started | A check has been started. When applicant_provides_data is true , this indicates the applicant has submitted all required information. |
check | check.reopened | A check has been reopened. This indicates the applicant needs to re-submit required information. |
check | check.withdrawn | A check has been withdrawn. |
check | check.completed | A check has been completed. |
check | check.form_completed | An applicant has submitted their information using the check form. |
report | report.withdrawn | A report has been withdrawn. |
report | report.resumed | A paused report has been resumed. |
report | report.cancelled | A paused report has been cancelled. |
report | report.awaiting_approval | A report has transitioned to the "Awaiting Approval" status. |
report | report.completed | A report has been completed and results are available. |
Event object
Attributes
Attribute | Description |
---|---|
payload | object The top level element. |
resource_type | string Indicates the resource affected by this event. |
action | string The event that triggered this webhook, e.g. report.completed . |
object | object The object affected by this event. This will contain an id and an href to retrieve that resource. |
Webhook event versioning
Refer to our API versioning guide for details on webhook event versioning.
1HTTP/1.1 201 Created2Content-Type: application/json34{5 "payload": {6 "resource_type": "report",7 "action": "report.completed",8 "object": {9 "id": "<REPORT_ID>",10 "status": "complete",11 "completed_at_iso8601": "2019-10-28T15:00:39Z",12 "href": "https://api.onfido.com/v3.1/reports/<REPORT_ID>"13 }14 }15}
Verifying webhook signatures
You should verify request signatures on your server to prevent attackers from imitating valid webhook events.
Each webhook you register will return a single secret
token in the token
field of the API response body, which is used to generate
an HMAC using SHA-256. You only need to register a webhook once. The token for
each webhook is also displayed on the Onfido Dashboard ‘Webhook Management’
page.
If possible, we recommend that you verify request signatures with our supported client libraries in your integration.
The following Onfido client libraries have support built in:
-
Java
-
Node
-
Python
-
Ruby
Using Onfido client libraries
You must initialise the verifier instance with your webhook’s secret token. For each webhook event, the verifier instance needs:
-
the signature of the webhook (from the
X-SHA2-Signature
header) -
the body of the event request (must be in raw format, not decoded from JSON)
Manually
We provide a detailed guide for manually verifying webhook signatures.
1X-SHA2-Signature: <HMAC_VALUE>
Register webhook
Registers a webhook. Returns a webhook object.
You can read more about how to verify request signatures on your server.
You cannot use sandbox tokens to create or manage webhooks for live environments.
Request body parameters
Parameter | Description |
---|---|
url | required The url that will listen to notifications (must be HTTPS). |
enabled | optional Determine if the webhook should be active. If omitted, will be set to true by default. |
environments | optional The environments from which the webhook will receive events. Allowed values are "sandbox" or "live" but sandbox tokens cannot be used for the "live" environment. If omitted (with a live token), the webhook will receive events from both environments. |
events | optional The events that should be published to the webhook. If omitted, all events will be subscribed by default. You can read about the supported events. |
Register a webhook using the Dashboard
You can also register webhooks through the Onfido Dashboard.
Webhook logs
To help you diagnose webhook issues, you can review logs on the Onfido Dashboard.
1POST /v3.1/webhooks/ HTTP/1.12Host: api.eu.onfido.com3Authorization: Token token=<YOUR_API_TOKEN>4Content-Type: application/json56{7 "url": "https://yourdomain.com",8 "enabled": true,9 "events": [10 "report.completed",11 "check.completed"12 ]13}
List webhooks
Lists all webhooks you've created.
Returns data in the form: {"webhooks": [<LIST_OF_WEBHOOK_OBJECTS>]}
.
1GET /v3.1/webhooks/ HTTP/1.12Host: api.eu.onfido.com3Authorization: Token token=<YOUR_API_TOKEN>
1GET /v3.1/webhooks/<WEBHOOK_ID> HTTP/1.12Host: api.eu.onfido.com3Authorization: Token token=<YOUR_API_TOKEN>
1PUT /v3.1/webhooks/<WEBHOOK_ID> HTTP/1.12Host: api.eu.onfido.com3Authorization: Token token=<YOUR_API_TOKEN>4Content-Type: application/json56{7 "url": "https://yourdomain.com"8}
Delete webhook
Deletes a webhook. If successful, returns a 204 No Content
response.
1DELETE /v3.1/webhooks/<WEBHOOK_ID> HTTP/1.12Host: api.eu.onfido.com3Authorization: Token token=<YOUR_API_TOKEN>4Content-Type: application/json
Address Picker
Performs a search for addresses by postcode (UK only).
Returns data in the form: {"addresses": [<LIST_OF_ADDRESS_OBJECTS>]}
.
The Onfido Address Picker will always use a third-party subprocessor for address cleansing. In this way, it can be used to make sure addresses passed to the create applicant endpoint are valid.
Query string parameters
postcode
(required): the applicant's postcode.
1GET /v3.1/addresses/pick?postcode=SW46EH HTTP/1.12Host: api.eu.onfido.com3Authorization: Token token=<YOUR_API_TOKEN>
Generate SDK token
Generating an SDK token will enable applicants to send personal data to Onfido via one of our SDKs. For more information on how Onfido uses personal data, view our Privacy Policy.
Generates an SDK token. Returns a token
object containing the SDK token.
SDK tokens can only be used in our input-capture SDKs. They are restricted to an individual applicant, and expire after 90 minutes.
You’ll need to generate and include a new token each time you initialize the Onfido SDKs.
The SDK token object returned in the response is of the form: {"token": "header.payload.signature"}
.
The composition and length of SDK tokens is variable and can change over time.
Request body parameters
Parameter | Description |
---|---|
applicant_id | required Specifies the applicant for the SDK instance. |
application_id | optional, should not be used if referrer provided The application ID (or "application bundle ID") - used with the iOS and Android SDKs. |
referrer | optional, should not be used if application_id provided The referrer URL pattern - used with the Web SDK. |
cross_device_url | optional The URL to be used by the Web SDK for the cross-device flow. (Max 24 characters). This replaces the default id.onfido.com and requires additional setup to map back to the Onfido hosted cross-device address. |
Each authenticated instance of the SDK will correspond to a single Onfido
applicant as specified by the applicant_id
.
The application_id
The application_id
is the "Application ID" or "Bundle ID" on iOS and Android
that was set up during development. For iOS, this is usually in the form
com.your-company.app-name
. For Android, this is usually in the form
com.example.yourapp
. Make sure to use a valid application_id
or you'll
receive a 401 error.
If you want to disable the application ID check, you can pass the wildcard *
. Alternatively, don't pass either of the application_id
and referrer
parameters.
The referrer argument
The referrer argument specifies the URL of the web page where the Web SDK will be used. The referrer sent by the browser must match the referrer URL pattern in the SDK token for the SDK to successfully authenticate. The referrer is based on the Google Chrome match pattern URLs. URLs can contain wild card characters.
The referrer pattern guarantees that other malicious websites cannot reuse the token in case it is lost. You can read more about referrer policy in Mozilla's documentation.
If you want to disable the referer header check, you can pass the wildcard *
. Alternatively, don't pass either of the application_id
and referrer
parameters.
You must use a site referrer policy that lets the
Referer
header be sent. If your policy does not allow this (e.g.
Referrer-Policy: no-referrer
), then you'll receive a 401 bad_referrer
error when trying to use the Web SDK.
Permitted referrer patterns are as follows:
Section | Format | Example |
---|---|---|
Referrer | scheme://host/path | https://*.<DOMAIN>/<PATH>/* |
Scheme | * or http or https | https |
Host | * or *. then any char except / and * | *.<DOMAIN> |
Path | Any char or none | <PATH>/* |
An example of a valid referrer is https://*.example.com/example_page/*
.
The cross_device_url argument
The cross-device flow of the Web SDK allows users to continue the identity verification process
from their phone where they can take pictures of their document and themselves rather than uploading
images from their desktop. This feature is available to all customers and uses the URL id.onfido.com
as the default. The cross_device_url
argument is used to white-label the default Onfido cross-device
URL to one of your choosing with a maximum character length of 24 including https://
. While the
cross-device flow is available to all customers, white-labeling the URL using this argument is a premium
enterprise feature that must be activated for your account before it may be used. Please talk to
your account executive for more information about purchasing this feature.
Example SMS before and after using this feature:
Before:
Continue your identity verification by tapping https://id.onfido.com/<UNIQUE-PATH>
After:
Continue your identity verification by tapping <YOUR-CROSS-DEVICE-URL>/<UNIQUE-PATH>
1POST /v3.1/sdk_token HTTP/1.12Host: api.eu.onfido.com3Authorization: Token token=<YOUR_API_TOKEN>4Content-Type: application/json56{7 "applicant_id": "<APPLICANT_ID>",8 "referrer:": "https://*.example.com/example_page/*",9 "cross_device_url": "https://example.com"10}
Repeat attempts
The repeat attempts endpoint allows you to request a list of repeat attempt matches for Document reports to show instances of repeat fraud where users submit multiple requests using the same document.
A repeat attempt is any previous Document report that was submitted using a document that matches other previously onboarded documents in your Onfido database. For each repeat attempt match, Onfido returns whether the name and date of birth (and document number starting from API version 3.6) on the document matches the personal document data used for each previous attempt. If the personal document data doesn't match, this indicates that one, or potentially multiple, of the documents might be fraudulent. A large number of repeat attempts can also signal fraudulent behaviour.
The repeat attempts endpoint is for use with Document reports only.
Retrieve repeat attempts
Returns all repeat attempts for a given Document report.
The Document report must have completed before you can request repeat attempts via this endpoint.
1curl -X GET https://api.eu.onfido.com/v3.1/repeat_attempts/<REPORT_UUID> \2 -H 'Authorization: Token token=<YOUR_API_TOKEN>'
1HTTP/1.1 200 OK2Content-Type: application/json34{5 "report_id": "<REPORT_UUID>",6 "repeat_attempts": [7 {8 "report_id": "<REPORT_ID>",9 "applicant_id": "<APPLICANT_ID>",10 "date_of_birth": "mismatch",11 "names": "match",12 "result": "clear",13 "created_at": "2021-12-10T00:00:00",14 "completed_at": "2021-12-12T00:10:00"15 },16 {17 "report_id": "<REPORT_ID>",18 "applicant_id": "<APPLICANT_ID>",19 "date_of_birth": "match",20 "names": "match",21 "result": "clear",22 "created_at": "2021-12-12T00:00:00",23 "completed_at": "2021-12-12T00:10:00"24 }25 ],26 "attempts_count": 3,27 "attempts_clear_rate": 0.67,28 "unique_mismatches_count": 1,29}
Response
Returns a repeat attempts object containing an array of repeat attempts.
Attribute | Description |
---|---|
report_id | string The uuid of the completed Document report. |
repeat_attempts | array of objects An array of repeat attempt objects. If no repeat attempts were found, the array will be empty. The number of objects returned can increase over time if more matches are received. |
attempts_count | int The total number of attempts using the same document, including the current report under assessment. |
attempts_clear_rate | float A number between 0 and 1 which indicates the proportion of attempts that have been cleared, including the current report under assessment. |
unique_mismatches_count | int The number of unique entries in the repeat_attempts field for which at least one of the fields is a mismatch. |
Repeat attempts object
The repeat_attempts
array of objects is nested inside the repeat attempts response object.
Attribute | Description | Possible values |
---|---|---|
report_id | string The uuid of the matching Document report. | - |
applicant_id | string The uuid of the applicant for the matching Document report. | - |
date_of_birth | string Whether the dates of birth are exactly the same or are different. | match , mismatch |
names | string Whether the names are exactly the same or are different. | match , mismatch |
result | string The report result of this attempt. | clear , consider |
created_at | datetime When the matching report was created. | - |
completed_at | datetime When the matching report was completed. | - |
Document reports flagged as suspected
for data_consistency
will not be returned by this endpoint. This is to ensure that data was correctly extracted, and the matches are relevant.
Autofill
Using this endpoint in a live context will cause you to send personal data to Onfido. Always make sure you inform your users about this and obtain any necessary permissions. For more information on how Onfido uses personal data, view our Privacy Policy.
Autofill takes an uploaded document and returns information extracted from the document. This is a synchronous request, which means the extracted information will be presented immediately in the API response.
Request body parameters
Parameter | Description |
---|---|
document_id | required The unique identifier of the uploaded document to run extraction on |
1POST /v3.1/extractions HTTP/1.12Host: api.eu.onfido.com3Authorization: Token token=<YOUR_API_TOKEN>4Content-Type: application/json56{7 "document_id": "<DOCUMENT_ID>"8}
Extraction result
If data has been successfully extracted, the API response will contain the properties document_classification
and extracted_data
.
document_classification
has the following properties:
Field | Description |
---|---|
issuing_country | Document country in 3-letter ISO code |
document_type | Type of document. See Document types. Only certain document types are supported by Autofill. Please contact client-support@onfido.com to find out more. |
issuing_state | The state that issued the document. Only returned for a subset of documents. |
subtype | The document subtype (full, not_full, provisional). Only extracted from USA and UK driving licences. |
version | The document issuing version. Only returned for a subset of documents. |
extracted_data
has the following properties:
As extraction is done on a best-effort basis, and also information varies across different documents, none of these properties are guaranteed to be present in the response.
Extraction data will not be populated if the document is issued by a country subject to comprehensive US sanctions.
Field | Description |
---|---|
document_number | The official document number. |
first_name | First name. |
last_name | Last name. |
middle_name | Middle name. |
full_name | Full name. |
spouse_name | Spouse name (French documents only). |
widow_name | Widow name (French documents only). |
gender | Gender. Valid values are Male and Female . |
date_of_birth | Date of birth in YYYY-MM-DD format. |
date_of_expiry | Date of expiry in YYYY-MM-DD format. |
expiry_date | Date of expiry in YYYY-MM-DD format. |
nationality | Nationality in 3-letter ISO code. |
mrz_line1 | Line 1 of the MRZ code. |
mrz_line_1 | Line 1 of the MRZ code. |
mrz_line2 | Line 2 of the MRZ code. |
mrz_line_2 | Line 2 of the MRZ code. |
mrz_line3 | Line 3 of the MRZ code. |
mrz_line_3 | Line 3 of the MRZ code. |
address_line_1 | Line 1 of the address. |
address_line_2 | Line 2 of the address. |
address_line_3 | Line 3 of the address. |
address_line_4 | Line 4 of the address. |
address_line_5 | Line 5 of the address. |
issuing_authority | Issuing authority. |
issuing_country | Document country in 3-letter ISO code. |
document_type | Type of document. See Document types. Only certain document types are supported by Autofill. Please contact client-support@onfido.com to find out more. |
place_of_birth | Place of birth. |
issuing_state | The state that issued the document. |
issuing_date | Issuing date in YYYY-MM-DD format. |
personal_number | The owner's unique identification number. |
1HTTP/1.1 2002Content-Type: application/json34{5 "document_id": "<DOCUMENT_ID>",6 "document_classification": {7 "document_type": "driving_licence",8 "issuing_country": "USA",9 "issuing_state": "CA",10 "subtype": "full",11 "version": "2018"12 },13 "extracted_data": {14 "first_name": "JANE",15 "last_name": "DOE",16 "full_name": "JANE DOE",17 "date_of_birth": "1977-08-31",18 "document_number": "I1234568",19 "gender": "Female",20 "issuing_date": "2009-08-31",21 "date_of_expiry": "2014-08-31",22 "expiry_date": "2014-08-31",23 "address_line_1": "2570 24TH STREET",24 "address_line_2": "ANYTOWN, CA 95818",25 "document_type": "driving_licence",26 "issuing_country": "USA",27 "issuing_state": "CA",28}
Unsuccessful extraction
Classification failure
If the document cannot be recognised, a classification_failure
will be returned.
1HTTP/1.1 422 Unprocessable Entity2Content-Type: application/json34{5 "document_id": "<DOCUMENT_ID>",6 "error": {7 "type": "classification_failure",8 "message": "We couldn’t recognise the type of this document."9 }10}
Extraction failure
If no data can be extracted, an extraction_failure
will be returned.
1HTTP/1.1 422 Unprocessable Entity2Content-Type: application/json34{5 "document_id": "<DOCUMENT_ID>",6 "error": {7 "type": "extraction_failure",8 "message": "We couldn’t extract data from this document."9 }10}
Fraud reporting ALPHA
Fraud reporting via the API is currently an ALPHA product. Please contact Client Support to find out more.
Onfido provides an endpoint which allows you to report known or suspected missed fraud, or an end user that was flagged by Onfido as potentially fraudulent but who you believe should have been cleared. By reporting missed fraud or genuine users, Onfido is then able to re-review these results as well as use this information to train our ML models to improve our services and catch additional fraud in the future.
You can also report via the Onfido Dashboard.
Using this endpoint in a live context will cause you to send personal data to Onfido and authorises Onfido to use the data to improve and further develop its products (including by sharing with third party providers as set out in Onfido’s Record of Processing). 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.
Submits a single request in relation to a specific check or report. If successful, returns a 201 Created
response.
The expected_result
should be provided in the request indicating what you believe to be the correct result of the check or report, along with either the associated check_id
or report_id
. You can optionally provide additional information to give reasons or context for the expected result.
Request body parameters
Parameter | Description |
---|---|
expected_result | required An enum. Accepts the values ”clear” or ”consider” . The expected result for the check or report. |
check_id | optional, should not be used if report_id is providedA string. The ID of the check.. |
report_id | optional, should not be used if check_id is providedA string. The ID of the report. |
feedback_notes | optional A string. Any additional information or feedback. |
You will not receive a detailed response or follow up after submitting to this endpoint.
1curl -X POST https://api.eu.onfido.com/v3.1/results_feedback \2 -H 'Authorization: Token token=<YOUR_API_TOKEN>' \3 -H 'Content-Type: application/json' \4 -d '{5 "expected_result": "consider",6 "report_id": "<REPORT_ID>"7 }'
Checks
Checks are performed on an applicant and consist of one or more reports.
Please note: When integrating with Onfido Studio workflows, checks are created automatically based on your specific workflow implementation. Checks are only applicable for implementations that rely on the explicit SDK configuration of verification steps.
Check object
Attribute | Description |
---|---|
id | string The unique identifier for the check. |
created_at | datetime The date and time at which the check was initiated. |
privacy_notices_read_consent_given | Boolean Indicates that the privacy notices and terms of service have been read and, where specific laws require, that consent has been given for Onfido. This will be true if specified during check creation, otherwise it will be null . |
webhook_ids | array of strings The list of registered webhook IDs to notify as part of this check. Unless the value is included during check creation, this parameter will be null . |
href | string The API endpoint to retrieve the check. |
applicant_provides_data | Boolean Run an applicant_provides_data check or not. Default is false . |
applicant_id | string The ID for the applicant associated with the check. |
status | string The current state of the check in the checking process. |
tags | array of strings A list of tags associated with this check. |
result | string The overall result of the check, based on the results of the reports used. |
form_uri | string A link to the applicant form, if applicant_provides_data is true . |
redirect_uri | string For checks where applicant_provides_data is true , redirect to this URI when the applicant has submitted their data. |
results_uri | string A link to the corresponding results page on the Onfido Dashboard |
report_ids | array of strings The list of report object IDs associated with the check. |
sandbox | Boolean Indicates whether the object was created in the sandbox or not. |
Check status
Status | Description |
---|---|
in_progress | We are currently processing the check. |
awaiting_applicant | The applicant has not yet submitted the applicant form, either because they have not started filling the form out or because they have started but have not finished. |
complete | All reports for the applicant have been completed or withdrawn. |
withdrawn | The check has been withdrawn. |
paused | The check is paused until you (the client) switch it on manually. Special case used by clients who wants to collect data and run the checks when they want and not immediately. |
reopened | Insufficient or inconsistent information was provided by the applicant, and the report has been bounced back for further information. |
1HTTP/1.1 201 Created2Content-Type: application/json34{5 "applicant_id": "<APPLICANT_ID>",6 "applicant_provides_data": false,7 "created_at": "2021-03-22T17:13:12Z",8 "form_uri": null,9 "href": "/v3.1/checks/<CHECK_ID>",10 "id": "<CHECK_ID>",11 "paused": false,12 "privacy_notices_read_consent_given": true,13 "redirect_uri": null,14 "report_ids": [15 "<REPORT_ID>"16 ],17 "result": null,18 "results_uri": "<RESULTS_URI>",19 "sandbox": true,20 "status": "in_progress",21 "tags": [],22 "version": "3.1",23 "webhook_ids": null24}
Check results
The value of the check is derived from the results of the individual reports that it contains:
Check result | Description |
---|---|
clear | If all the reports contained in the check have clear as their results. |
consider | If any reports contained in the check have either consider or unidentified as their result. |
Create check
Using this endpoint in a live context will cause you to create a check using an applicant's personal data. Always make sure you inform your users about this and obtain any necessary permissions. For more information on how Onfido uses personal data, view our Privacy Policy.
Initiates a check for an applicant, which can contain one or more reports. Returns a check object.
Having created the first check, you are allowed to create further checks for the same applicant, as long as the previous check is not still ongoing (i.e. check has been completed, withdrawn or cancelled). You will receive an error message if you try to create a check for an applicant with an ongoing check.
If you are creating multiple checks for the same applicant you should reuse the same applicant_id
in every check request. This ensures all checks are associated with the same individual.
When creating checks, you must use the report_names
field (which takes an
array of strings). For example, to create a check with 2 reports:
"report_names": ["report_name_1", "report_name_2"]
Request body parameters
Parameter | Description |
---|---|
applicant_id | required The ID of the applicant to run the check on. |
report_names | required Array of strings describing reports requested for the check. |
privacy_notices_read_consent_given | optional Boolean to indicate that the privacy notices and terms of service have been read and, where specific laws require, that consent has been given for Onfido. This parameter should be set to true after gaining the necessary consent, and if it's set to false the request will fail with a validation error. If this parameter is omitted when creating the check, it will be returned as null in the check response object. |
document_ids | optional Array of strings describing which document to process in checks containing a Document report, a Facial Similarity report or both, which takes a maximum of 2 strings (document IDs) 1. By default, the most recently uploaded document is used. document_ids is only usable with Document and Facial Similarity reports.Note: document_ids is a required parameter for Document Video Report. |
applicant_provides_data | optional Default is false . If true , applicant provides required information and documents using the Onfido applicant form. |
asynchronous | optional Default is true .2 It’s strongly recommended that you leave this as the default, and configure webhooks to notify you when a check or report is complete. |
tags | optional Array of tags being assigned to this check. |
suppress_form_emails | optional For checks where applicant_provides_data is true , applicant form will not be automatically sent if suppress_form_email is true . You can manually send the form at any time after the check has been created, using the link found in the form_uri attribute of the check object.Defaults to false (i.e., form will be sent automatically by default). |
redirect_uri | optional For checks where applicant_provides_data is true , redirect to this URI when the applicant has submitted their data. |
consider | optional Array of names of particular reports to return consider as their results. This is a feature available in sandbox testing which you can read more about. |
webhook_ids | optional Array of strings describing which webhooks to trigger for this check. By default, all webhooks registered in the account will be triggered and this value will be null in the responses. |
us_driving_licence | optional An object that contains all accepted fields for the Driver's License Data Verification report. |
1: For a check containing a Document and Facial Similarity report, you only need to specify 1 document ID which will be used for both reports. You should only specify 2 document IDs when the uploaded document has a front and a back side. If 2 document IDs are submitted in any other case, the Document report will be rejected for Image Quality: two_documents_uploaded
.
2: If asynchronous
is set to false
:
- the request to create a check will only return a response when all the reports in the check complete the automatic part of the review, or the request times out after 29 seconds
- if all reports are completed automatically, the check response is returned with a status of
complete
- if one of the reports goes to manual review (the status of the report is
awaiting_approval
) the check response is returned with a status ofin_progress
- a check created in sandbox will always complete automatically and never time out, so may not give an accurate representation of the behaviour
webhook_ids
The majority of users do not need to set this parameter. By default, events will be sent to all configured webhooks.
If you need a check to only trigger a subset of your webhooks (for example, if you have multiple regional specific webhooks subscribed to report.completed
), you can list the IDs of the webhooks this check should trigger by passing the following array as part of your check request:
"webhook_ids": ["<VALID-WEBHOOK-ID-1>", "<VALID-WEBHOOK-ID-2>", ...]
If an invalid webhook ID is included in the list, that ID will be ignored and the request will be processed as though it were not included.
Omitting webhook_ids
from the request, or including any of the following in your request
will cause the default behavior of setting the check to trigger all webhooks you've created:
"webhook_ids": undefined
"webhook_ids": null
"webhook_ids": []
To make a check ignoring all webhooks you've created, pass the following as part of your check request:
"webhook_ids": ["no_webhooks"]
If any webhook IDs are included in addition to "no_webhooks"
, you will receive an error.
Inclusion of a webhook ID in webhook_ids
does not affect the type of events that webhook is
subscribed to.
Report names in API
The following table is of report names as they are described in the API.
Report name | API report name(s) |
---|---|
Document | document |
Document Video Report | document_video |
Document with Address Information | document_with_address_information |
Document with Driving Licence Information | document_with_driving_licence_information |
Facial Similarity | facial_similarity_photo facial_similarity_photo_fully_auto facial_similarity_video facial_similarity_motion |
Known Faces | known_faces |
Identity | identity_enhanced |
Watchlist | watchlist_aml watchlist_enhanced watchlist_standard watchlist_peps_only watchlist_sanctions_only |
Proof of Address | proof_of_address |
Driver's License Data Verification | us_driving_licence |
When creating a check, pass these in an array of strings to report_names
.
1POST /v3.1/checks/ HTTP/1.12Host: api.eu.onfido.com3Authorization: Token token=<YOUR_API_TOKEN>4Content-Type: application/json56{7 "applicant_id": "<APPLICANT_ID>",8 "report_names": [9 "document",10 "facial_similarity_photo"11 ]12}
1GET /v3.1/checks/<CHECK_ID> HTTP/1.12Host: api.eu.onfido.com3Authorization: Token token=<YOUR_API_TOKEN>
List checks
Returns all checks for an applicant. Returns data in the form: {"checks": [<LIST_OF_CHECK_OBJECTS>]}
.
Query string parameters
applicant_id
(required): the ID of the applicant whose checks you want to list.
1GET /v3.1/checks?applicant_id=<APPLICANT_ID> HTTP/1.12Host: api.eu.onfido.com3Authorization: Token token=<YOUR_API_TOKEN>
Resume check
Resumes a paused check. If successful, returns a 204 No Content
response.
A check is paused if all the reports that it contains are in the paused state.
When a check where applicant_provides_data
is true
gets resumed, all its reports will start processing immediately if the applicant has already submitted the form. The check status will automatically change to in_progress
. Otherwise, the check will remain as awaiting_applicant
and the reports will only start processing after the applicant submits the form.
1GET /v3.1/checks/<CHECK_ID>/resume HTTP/1.12Host: api.eu.onfido.com3Authorization: Token token=<YOUR_API_TOKEN>
Download check
Downloads a PDF of a check with a given check ID. Returns the binary data representing the PDF.
1GET /v3.1/checks/{check_id}/download HTTP/1.12Host: api.eu.onfido.com3Authorization: Token token=<YOUR_API_TOKEN>
Reports
In the Onfido API, checks are composed of one or more reports.
Please note: When integrating with Onfido Studio workflows, the results of reports are managed by workflow run output and can be retrieved by making a call to the Retrieve Workflow Run endpoint, with results returned in the output attribute. Report endpoints are only applicable for implementations where reports are part of checks created with the explicit SDK configuration of verification steps.
Report object
The report object will differ depending on the report itself.
Attribute | Description |
---|---|
id | string The unique identifier for the report. |
created_at | datetime The date and time at which the report was first initiated. |
name | string The type of report. |
href | string The API endpoint to retrieve the report. |
status | string The current state of the report in the checking process. |
result | string The result of the report ( null if report is incomplete). |
sub_result | string The sub_result of the report. It gives a more detailed result for Document reports only, and will be null otherwise. |
breakdown | object The details of the report. This is specific to each type of report. |
properties | object The properties associated with the report, if any. |
documents | array The document IDs that were processed. Populated for Document reports, otherwise an empty array. |
check_id | string The ID of the check to which the report belongs. |
The breakdown
object differs for each report type. For example, for
Document reports.
Report status
Status | Description |
---|---|
awaiting_data | Onfido has made a request to one of its data providers and we are waiting on their reply. |
awaiting_approval | Report is undergoing manual review. |
cancelled | Report has been cancelled using the cancel report endpoint. |
complete | Report is done. |
withdrawn | Report has been automatically withdrawn by the system. For example, due to missing data. |
paused | Report is paused until you, i.e. the client, switch it on manually. Special case used by clients who want to collect data and run the reports when they want and not immediately. |
Report results
The result
field indicates the overall result of a report. The possible values of this field are:
Report result | Description |
---|---|
clear | If all underlying verifications pass, the overall result will be clear . |
consider | If the report has returned information that needs to be evaluated, the overall result will be consider . |
unidentified | For Identity Enhanced and Driver's License Data Verification reports only. |
null | For Proof of Address reports only. |
Sub results (Document reports)
The sub_result
field indicates a more detailed result and is unique to Document reports.
Report sub_result | Description |
---|---|
clear | If all underlying verifications pass, the overall sub result will be clear . |
rejected | If the report has returned information where the check cannot be processed further (poor quality image or an unsupported document). |
suspected | If the document that is analysed is suspected to be fraudulent. |
caution | If any other underlying verifications fail but they don't necessarily point to a fraudulent document (such as the name provided by the applicant doesn't match the one on the document). |
1GET /v3.1/reports/<REPORT_ID> HTTP/1.12Host: api.eu.onfido.com3Authorization: Token token=<YOUR_API_TOKEN>
List reports
Lists all reports belonging to a particular check. Returns data in the form:
{"reports": [<LIST_OF_REPORT_OBJECTS>]}
.
Query string parameters
check_id
(required): the ID of the check whose reports you want to list.
1GET /v3.1/reports?check_id=<CHECK_ID> HTTP/1.12Host: api.eu.onfido.com3Authorization: Token token=<YOUR_API_TOKEN>
Resume report
Resumes a single paused report. If successful, returns a 204 No Content
response.
When an individual report gets resumed in a check where
applicant_provides_data
is true
, it will start
processing immediately if the applicant has already submitted the form. The
report status will automatically change from paused
to awaiting_data
.
Otherwise, the status change will happen but the report processing will only
start after the applicant submits the form.
Note that you can resume all reports within a check by resuming the check itself.
1POST /v3.1/reports/<REPORT_ID>/resume HTTP/1.12Host: api.eu.onfido.com3Authorization: Token token=<YOUR_API_TOKEN>
Cancel report
Cancels single paused reports. If successful, returns a 204 No Content
response.
When a report gets cancelled in a check where applicant_provides_data
is true
, its status will change from paused
to cancelled
and the report will never get processed.
1POST /v3.1/reports/<REPORT_ID>/cancel HTTP/1.12Host: api.eu.onfido.com3Authorization: Token token=<YOUR_API_TOKEN>
Responsible Disclosure
Responsible Disclosure Policy
Security is a top priority for Onfido and we value the work done by researchers in improving the security of our products and services. We encourage responsible vulnerability research and disclosure and if you discover a vulnerability in any of our systems, please let us know about it so we can address it as quickly as possible. We are committed to working with the community to verify, reproduce, and respond to all the submissions in a timely manner.
Our full policy can be found at the following URLs:
Reporting a Vulnerability
If you believe you’ve discovered a security vulnerability, please let us know by submitting a report at https://vdp.onfido.com/p/Send-a-report
Onfido highly appreciates the efforts made by the reporting party in identifying the vulnerability or error. Reporting of such vulnerabilities and errors will contribute to improving the security and reliability of our product and services.
Bug Bounty
Onfido currently operates a private bug bounty on the YesWeHack platform. If you want to actively participate in the program, please let us know and contact us at bugbounty@onfido.com. You can find more information here.
Contact
Please submit any vulnerability reports at https://vdp.onfido.com/p/Send-a-report. If you aren’t sure whether a system or an issue is in scope or not, contact us at bugbounty@onfido.com.