Get started (API v3.6)
Welcome to our new API v3.6 documentation. If you're migrating and are
currently using api.onfido.com
, please make sure you use api.eu.onfido.com
with API v3.6.
You'll find migration guides on our main Developer Hub.
The Onfido API is based on REST principles. It uses standard HTTP response codes and verbs, and token-based authentication.
If you're just getting started with our API, read our quick-start guides.
Request, response format
You should use a Content-Type: application/json
header with all PUT and POST
requests except when uploading documents or live photos. For these requests,
use a Content-Type: multipart/form-data
header.
Responses return JSON with a consistent structure, except downloads.
You must make all your requests to the API over HTTPS and TLS 1.2, with Server Name Indication enabled. Any requests made over HTTP will fail.
Text fields support UTF-8, but do not allow certain special characters.
Token authentication
The Onfido API uses token-based authentication. API tokens must be included in the header of all requests made to the API.
You can generate new tokens and find your existing ones in your Onfido Dashboard.
You can make requests using sandbox tokens to test our API before you go live.
Authorization: Token token=<YOUR_API_TOKEN>
API tokens
You can use API tokens to authenticate any API action described in this documentation.
You can create and revoke API tokens, and see when they were last used, in your Onfido Dashboard.
You must never use API tokens in the frontend of your application or malicious users could discover them in your source code. You should only use them on your server.
If you do need to collect applicant data in the frontend of your application, we recommend that you use one of the Onfido input-capture SDKs.
You should limit live API token access to only the minimum number of people necessary, but you can use sandbox tokens to freely experiment with the sandbox Onfido API.
Note that there are some differences between the sandbox and live APIs.
You should not embed API tokens in your backend code—even if it’s not public—because this increases the risk that they will be discovered. Instead, you should store them in configuration files or environment variables.
You should also periodically rotate your live API tokens (see next section).
API token rotation
We highly recommend that you rotate live API tokens when staff members with access to those tokens leave your organisation. Consider creating a leaver's process which covers this.
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 input-capture SDKs authenticate using SDK tokens. You cannot use an API token to authenticate the SDKs.
SDK tokens are restricted to an individual applicant and expire after 90 minutes.
You can generate SDK tokens using an API endpoint.
Mobile tokens
Mobile tokens will 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 Product 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 input-capture SDKs.
Pre-determined responses
To help you test your integration in the sandbox API, you can trigger pre-determined report responses.
Pre-determined responses work for the following report types:
- Identity Enhanced
- Document
- Watchlist Standard
- Watchlist Enhanced
- Watchlist AML
- 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).
POST /v3.6/applicants/ HTTP/1.1 Host: api.eu.onfido.com Authorization: Token token=<YOUR_API_TOKEN> Content-Type: application/json { "first_name": "Jane", "last_name": "Consider" }
Pre-determined 'consider' and 'clear' results
To test multiple different sandbox report responses simultaneously, you can pass specific report
types to the consider
parameter (in an array).
Only the reports specified in the consider
array will
return a consider
report result. All other reports in the check will return a clear
result.
POST /v3.6/checks/ HTTP/1.1 Host: api.eu.onfido.com Authorization: Token token=<YOUR_API_TOKEN> Content-Type: application/json { "applicant_id": "<APPLICANT_ID>", "report_names": [ "watchlist_standard", "identity_enhanced" ], "consider": [ "watchlist_standard" ] }
Pre-determined responses for Document reports
The sandbox API supports additional functionality for testing Document reports. You can trigger pre-determined Document report responses for specific:
For Document reports, first_name
and last_name
must be provided when creating an applicant (even in the Sandbox).
Breakdowns and sub-breakdowns
You can trigger responses for particular breakdowns and sub-breakdowns for sandbox Document reports. These responses show possible breakdown and sub-breakdown combinations that can be flagged for a consider
report result.
To test breakdown - sub-breakdown combinations:
- Create an applicant which has the
first_name
as the "breakdown - sub-breakdown" combination you would like to trigger.
Sandbox supports the following options:
"Image Integrity - Supported Document"
"Image Integrity - Image Quality"
"Visual Authenticity - Fonts"
"Visual Authenticity - Security Features"
"Visual Authenticity - Face Detection"
"Data Validation - Document Numbers"
"Data Consistency - Document Type"
- 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
.
POST /v3.6/applicants/ HTTP/1.1 Host: api.eu.onfido.com Authorization: Token token=<YOUR_API_TOKEN> Content-Type: application/json { "first_name": "Image Integrity - Supported Document", "last_name": "Smith" }
Document types
You can trigger responses for particular document types for sandbox Document reports. These responses show a Document report response including the specific properties
for the associated document type.
To test different document types:
- Create an applicant which has the
last_name
as the document type you would like 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" | 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.
- Create a check with this applicant.
POST /v3.6/applicants/ HTTP/1.1 Host: api.eu.onfido.com Authorization: Token token=<YOUR_API_TOKEN> Content-Type: application/json { "first_name": "Jane", "last_name": "CA DL 2018" }
Sub-results
You can trigger responses for particular sub-results for sandbox Document reports. These responses show possible individual breakdown results which can lead to different sub-results.
To do this:
- Create an applicant which has the
last_name
as one of the following strings:
"clear"
"rejected"
"suspected"
"caution"
- Create a check with this applicant.
POST /v3.6/applicants/ HTTP/1.1 Host: api.eu.onfido.com Authorization: Token token=<YOUR_API_TOKEN> Content-Type: application/json { "first_name": "Jane", "last_name": "rejected" }
Pre-determined responses for Facial Similarity reports
The sandbox API supports additional functionality for testing breakdowns and sub-breakdowns for Facial Similarity Photo and Photo Fully Auto reports.
For Facial Similarity reports, first_name
and last_name
must be provided when creating an applicant (even in the Sandbox).
Breakdowns and sub-breakdowns
You can trigger responses for particular breakdowns and sub-breakdowns for sandbox Facial Similarity reports. These responses show possible breakdown and sub-breakdown combinations that can be flagged for a consider
report result.
To test breakdown - sub-breakdown combinations:
- Create an applicant which has the
first_name
as the "breakdown - sub-breakdown" combination you would like to trigger.
Sandbox supports the following options:
"Visual Authenticity - Spoofing Detection"
"Face Comparison - Face Match"
"Image Integrity - Source Integrity"
"Image Integrity - Face Detected"
- Create a check with this applicant.
POST /v3.6/applicants/ HTTP/1.1 Host: api.eu.onfido.com Authorization: Token token=<YOUR_API_TOKEN> Content-Type: application/json { "first_name": "Visual Authenticity - Spoofing Detection", "last_name": "Smith" }
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
$ curl -X POST https://api.eu.onfido.com/v3.6/repeat_attempts/match \ -H 'Authorization: Token token=<YOUR_API_TOKEN>' \
Below is a pre-determined response example for a Repeat Attempts match:
{ "report_id": "00000000-0000-0000-0000-000000000000", "repeat_attempts": [ { "report_id": "00000000-0000-0000-0000-000000000001", "applicant_id": "00000000-0000-0000-0000-000000000003", "date_of_birth": "match", "names": "match", "result": "clear", "created_at": "2022-01-06T14:46:43Z", "completed_at": "2022-01-06T15:46:43Z" }, { "report_id": "00000000-0000-0000-0000-000000000002", "applicant_id": "00000000-0000-0000-0000-000000000003", "date_of_birth": "match", "names": "match", "result": "clear", "created_at": "2022-02-18T03:09:34Z", "completed_at": "2022-02-18T03:10:34Z" } ], "attempts_count": 3, "attempts_clear_rate": 1, "unique_mismatches_count": 0 }
Postman collection
You can run the Onfido API version 3.6 collection in Postman:
The API version 3.6 Postman collection is at version 1.0.
In your Postman environment, you'll need to define the apiToken
and baseUrl
variables. See region base URLs for baseUrl
options.
You can read more in Postman's documentation about managing environments.
Go live
Before you go live, you may find the introductory guides on our Developer Hub 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 api@onfido.com if you write your own library and would like us to link to it.
OpenAPI specification
We use an OpenAPI specification to generate our PHP library, which we also host publicly.
For any custom libraries you generate yourself with this specification, we can only provide support on a best-effort basis.
Rate limits
Onfido's API enforces a maximum volume of requests per 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 30 requests per minute (up to 1 request per second with a burst of 2 requests).
Onfido uses the token bucket algorithm to handle usage.
Any request over the limit will return a 429 Too Many Requests
error.
HTTP/1.1 429 Too Many Requests Content-Type: application/json { "error": { "type": "rate_limit", "message": "Rate limit exceeded. Please try again later." } }
Regions
There is no default region in API v3.6. If you were previously using api.onfido.com
, you should use api.eu.onfido.com
with v3.6.
$ curl https://api.eu.onfido.com/v3.6/
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.
$ curl https://api.us.onfido.com/v3.6/
Regions have unique base URLs and API token formats for both live and sandbox environments.
$ curl https://api.ca.onfido.com/v3.6/
Region | Notes | API base URL | API token format |
---|---|---|---|
EU | Replaces api.onfido.com for EU region in v3.1, v3.2, v3.3, v3.4, v3.5 and v3.6 | 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 |
---|---|
2023-01-24 | General release of API version 3.6. Please see our release notes. |
Errors
All errors are returned with the same structure:
{ "error": { "type": <TYPE>, "message": <MESSAGE>, "fields": <FIELDS - NOT ALWAYS PRESENT> } }
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. |
HTTP/1.1 422 Unprocessable Entity Content-Type: application/json { "error": { "type": "validation_error", "message": "", "fields": { "email": [ "invalid format" ] "name": [ "can't be blank" ] } } }
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 input-capture SDKs use SDK tokens for authentication, not API tokens. If you're receiving a 401 error on one of our SDKs, check you've entered a valid application ID when generating the SDK token. |
401 user_authorization_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 missing_applicant_location | Make sure you've provided the applicant's location before starting a check |
422 missing_applicant_provided_consents | Make sure you've provided the required consents |
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_with_unsupported_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. |
Applicants
An applicant represents an individual who will be the subject of a check. An applicant must exist before a check can be initiated.
Different report types have different minimum requirements for applicant data, and different recommended data. For each report, this information is noted in under the relevant section of this documentation. For example, for Document reports.
If you're requesting multiple checks for the same individual, you should reuse the id
returned in the initial applicant response object in the applicant_id
field when creating a check.
Applicant object
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. |
location | location object The location of the applicant. |
phone_number | string The applicant's phone number with country code. |
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 , driving_licence , share_code , voter_id , passport and other (e.g. AUS Foreign Passport). |
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.
Location object
The location object is nested inside the applicant object.
Attribute | Description |
---|---|
ip_address | string The IP address of the applicant. |
country_of_residence | string The 3 character ISO country code of the country where the applicant resides. |
If country_of_residence
is not provided in the request, it will be inferred from the IP address which may result in an incorrect value.
If you submitted location
during document upload, it will not be returned here.
Forbidden characters
For addresses the following characters are forbidden:
!$%^*=<>
For names the following characters are forbidden:
^!#$%*=<>;{}"
HTTP/1.1 201 Created Content-Type: application/json { "id": "<APPLICANT_ID>", "created_at": "2019-10-09T16:52:42Z", "sandbox": true, "first_name": "Jane", "last_name": "Doe", "email": null, "dob": "1990-01-01", "delete_at": null, "href": "/v3.6/applicants/<APPLICANT_ID>", "id_numbers": [], "phone_number": "+44 7911 123456", "address": { "flat_number": null, "building_number": null, "building_name": null, "street": "Second Street", "sub_street": null, "town": "London", "state": null, "postcode": "S2 2DF", "country": "GBR", "line1": null, "line2": null, "line3": null }, "location": { "ip_address": "127.0.0.1", "country_of_residence": "GBR" } }
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. |
phone_number | optional The applicant's phone number with country code. |
location | optional An object that contains the location of the applicant. |
consents | optional An array of objects indicating whether consent has been given by the applicant. |
location
You must provide location
for every applicant. If you do not, all checks with a Facial Similarity report will fail with a validation error.
You must provide location information for each end user as this determines the necessary consent required in order to process a verification.
You can specify either or both the IP address and the country of residence (3 character ISO country code) of the applicant in the location
object.
... "location": { "ip_address": "127.0.0.1", "country_of_residence": "GBR" } ...
You can also provide location information during document upload.
If you submit location information in multiple requests, the document upload location will take precedence.
If you use the Onfido SDK, location is provided directly by the SDK. You do not need to manually submit the location
parameter in this case.
consents
Where required, you must collect end user consent before creating a check with Onfido. If you do not, Onfido is unable to process an applicant's data and complete a verification.
Exact consent requirements are linked to the location of the end user and the report type. You must specify an applicant's location in the location
parameter when creating an applicant or uploading a document.
privacy_notices_read
End users located in the United States, must read the Privacy Notices and Terms of Service before giving consent for Onfido.
granted
should be set to true
after gaining the necessary consent from the applicant. If it's set to false
, or the parameter is not provided, all check creation requests will fail with a validation error.
For more information on the requirements and implementation options for collecting US end user consent, please see our Onfido privacy notices and consent guide.
ssn_verification
End users must give consent to process their Social Security Number (SSN) before you can submit an Identity Enhanced report.
granted
should be set to true
after gaining the necessary consent from the applicant. If it's set to false
, or the parameter is not provided, SSN reports will fail with a validation error.
phone_number_verification
End users must give consent to process their phone number before you can submit a Phone Verification report.
granted
should be set to true
after gaining the necessary consent from the applicant. If it's set to false
, or the parameter is not provided, Phone Verification reports will fail with a validation error.
... "consents": [ { "name": "privacy_notices_read", "granted": true }, { "name": "ssn_verification", "granted": true }, { "name": "phone_number_verification", "granted": true } ] ...
You can also provide consents
when updating an applicant.
If you use the Onfido SDK, consent is collected directly by the SDK. The SDK contains a mandatory consent screen which the end user must accept in order to proceed. You do not need to manually provide the consents
parameter in this case.
POST /v3.6/applicants/ HTTP/1.1 Host: api.eu.onfido.com Authorization: Token token=<YOUR_API_TOKEN> Content-Type: application/json { "first_name": "Jane", "last_name": "Doe", "dob": "1990-01-31", "address": { "building_number": "100", "street": "Main Street", "town": "London", "postcode": "SW4 6EH", "country": "GBR" } }
Retrieve applicant
Retrieves a single applicant. Returns an applicant object.
GET /v3.6/applicants/<APPLICANT_ID> HTTP/1.1 Host: api.eu.onfido.com Authorization: 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
PUT /v3.6/applicants/<APPLICANT_ID> HTTP/1.1 Host: api.eu.onfido.com Authorization: Token token=<YOUR_API_TOKEN> Content-Type: application/json { "first_name": "New", "last_name": "Name" }
Delete applicant
Deletes a single applicant. If successful, returns a 204 No Content
response.
Sending a deletion request adds the applicant object and all associated documents, photos, videos, checks, reports and analytics data to our deletion queue. The objects will be permanently deleted from Onfido's production object storage and relational database system after a deletion delay which can be configured by emailing our client support team. After deletion, applicant details cannot be recovered or queried, and Onfido will not be able to troubleshoot. Within the delay period, the applicant can be restored. For more information about Onfido's deletion service, see our Data Deletion FAQ.
Once deleted, Onfido will not be able to carry out any troubleshooting or investigate any queries raised by the client. It is for this reason we recommend a longer deletion period, for example, a minimum of thirty days.
DELETE /v3.6/applicants/<APPLICANT_ID> HTTP/1.1 Host: api.eu.onfido.com Authorization: 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.
POST /v3.6/applicants/<APPLICANT_ID>/restore HTTP/1.1 Host: api.eu.onfido.com Authorization: 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.5/applicants?page=3059>; rel="last", <https://api.eu.onfido.com/v3.5/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.
GET /v3.6/applicants?page=1&per_page=5 HTTP/1.1 Host: api.eu.onfido.com Authorization: Token token=<YOUR_API_TOKEN>
Documents
Some reports require uploaded identity documents in order to be processed successfully.
Depending on the type of the document, we may require both sides of the image to be uploaded. See the full list of documents we support.
Documents belong to a single applicant, so they must be uploaded after an applicant has been created.
The API uses the British English spelling driving_licence
.
Document object
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. |
HTTP/1.1 201 Created Content-Type: application/json { "id": "<DOCUMENT_ID>", "created_at": "2019-02-11T13:49:20Z", "file_name": "sample_driving_licence.png", "file_type": "png", "file_size": 490408, "type": "driving_licence", "side": "front", "issuing_country": null, "applicant_id": "<APPLICANT_ID>", "href": "/v3.6/documents/<DOCUMENT_ID>", "download_href": "/v3.6/documents/<DOCUMENT_ID>/download" }
Document types
Identity documents
The following is a partial list of document types (i.e. type
when uploading
a document):
Type |
---|
national_identity_card |
driving_licence |
passport |
voter_id |
work_permit |
This list is not exhaustive.
If you're unsure of the type of document you want to verify, you can
submit documents with type unknown
. In this case, we will attempt to
classify and recognize the document type when processing a Document report.
Upload document
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. |
location | optional An object that contains the location of the applicant. |
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. |
location
You must provide location
for every applicant. If you do not, all checks will fail with a validation error.
You must provide location information for each end user as this determines the necessary consent required in order to process a verification.
You can specify either or both the IP address and the country of residence (3 character ISO country code) of the applicant in the location
object.
... -F 'location[ip_address]=127.0.0.1' \ -F 'location[country_of_residence]=GBR' ...
You can also provide location information during applicant creation.
If you submit location information in multiple requests, the document upload location will take precedence.
If you submit location information during document upload, this will not be returned in the applicant object.
If you use the Onfido SDK, location is provided directly by the SDK. You do not need to manually submit the location
parameter in this case.
Image quality
You can request image quality validation when uploading a document. It is conducted synchronously and you'll receive the result as a response to your request.
When the image passes validation, returns a document object.
When the image fails validation, returns a 422 validation_error. There can be one or more failed image quality validations for a request. The list of reasons is provided in the fields
property.
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.
POST /v3.6/documents/ HTTP/1.1 Host: api.eu.onfido.com Authorization: Token token=<YOUR_API_TOKEN> Content-Type: multipart/form-data
Retrieve document
Retrieves a single document. Returns a document object.
GET /v3.6/documents/<DOCUMENT_ID> HTTP/1.1 Host: api.eu.onfido.com Authorization: Token token=<YOUR_API_TOKEN>
GET /v3.6/documents?applicant_id=<APPLICANT_ID> HTTP/1.1 Host: api.eu.onfido.com Authorization: Token token=<YOUR_API_TOKEN>
GET /v3.6/documents/<DOCUMENT_ID>/download HTTP/1.1 Host: api.eu.onfido.com Authorization: Token token=<YOUR_API_TOKEN>
GET /v3.6/documents/<DOCUMENT_ID>/video/download HTTP/1.1 Host: api.eu.onfido.com Authorization: Token token=<YOUR_API_TOKEN>
Live photos
Live photos are images of the applicant's face, typically taken at the same time as documents are provided. Some reports require uploaded live photos in order to be processed successfully.
Live photo object
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. |
HTTP/1.1 201 Created Content-Type: application/json { "id": "<LIVE_PHOTO_ID>", "created_at": "2019-10-09T16:59:06Z", "file_name": "<FILE_NAME>.png", "file_type": "image/png", "file_size": 536630, "href": "/v3.6/live_photos/<LIVE_PHOTO_ID>", "download_href": "/v3.6/live_photos/<LIVE_PHOTO_ID>/download" }
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. |
POST /v3.6/live_photos/ HTTP/1.1 Host: api.eu.onfido.com Authorization: Token token=<YOUR_API_TOKEN> Content-Type: multipart/form-data
Retrieve live photo
Retrieves a single live photo. Returns a live photo object.
GET /v3.6/live_photos/<LIVE_PHOTO_ID> HTTP/1.1 Host: api.eu.onfido.com Authorization: Token token=<YOUR_API_TOKEN>
GET /v3.6/live_photos/live_photos?applicant_id=<APPLICANT_ID> HTTP/1.1 Host: api.eu.onfido.com Authorization: Token token=<YOUR_API_TOKEN>
GET /v3.6/live_photos/<LIVE_PHOTO_ID>/download HTTP/1.1 Host: api.eu.onfido.com Authorization: Token token=<YOUR_API_TOKEN>
Live videos
Live videos are footage of the applicant's face, recorded and uploaded by the Onfido input-capture SDKs (iOS, Android or Web), at the same time as the document image is captured—also by the SDKs. These videos are used for Facial Similarity Video reports.
Live video object
During the video recording end users are asked to perform randomly generated actions, represented in challenge
. Challenges always have 2 parts recite
and movement
, but the order in which these happen can vary. The order of the challenges is maintained in the live video object. recite
asks the user to say 3 randomly generated digits, whereas movement
asks the user to look over their right or left shoulder.
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. |
HTTP/1.1 201 Created Content-Type: application/json { "id": "<LIVE_VIDEO_ID>", "created_at": "2018-05-14T16:44:53Z", "href": "/v3.6/live_videos/<LIVE_VIDEO_ID>", "download_href": "/v3.6/live_videos/<LIVE_VIDEO_ID>/download", "file_name": "<FILE_NAME>.mp4", "file_type": "video/mp4", "file_size": 1431121, "challenge": [ { "type": "recite", "query": [ 1, 2, 3 ] }, { "type": "movement", "query": "turnRight" } ] }
Upload live video
Live videos can only be uploaded via one of Onfido's input-capture SDKs, not via the API directly.
As a result, Onfido does not provide an upload live video endpoint.
To upload live videos for Facial Similarity Video reports, integrate with one of our input-capture SDKs (iOS, Android or Web).
Retrieve live video
Retrieves a single live video. Returns the corresponding live video object.
GET /v3.6/live_videos/<LIVE_VIDEO_ID> HTTP/1.1 Host: api.eu.onfido.com Authorization: Token token=<YOUR_API_TOKEN>
GET /v3.6/live_videos?applicant_id=<APPLICANT_ID> HTTP/1.1 Host: api.eu.onfido.com Authorization: Token token=<YOUR_API_TOKEN>
GET /v3.6/live_videos/<LIVE_VIDEO_ID>/download HTTP/1.1 Host: api.eu.onfido.com Authorization: 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.
GET /v3.6/live_videos/<LIVE_VIDEO_ID>/frame HTTP/1.1 Host: api.eu.onfido.com Authorization: Token token=<YOUR_API_TOKEN>
Unsuccessful frame extraction
Frame extraction failed
If a frame cannot be extracted from the live video, a frame_extraction_failed
response will be returned.
HTTP/1.1 422 Unprocessable Entity Content-Type: application/json { "error": { "type": "frame_extraction_failed", "message": "<Reason>" } }
Frame extraction unavailable
If the extraction feature is temporarily unavailable, a frame_extraction_unavailable
response will be returned instead.
HTTP/1.1 503 Service Unavailable Content-Type: application/json { "error": { "type": "frame_extraction_unavailable", "message": "Frame extraction is temporarily unavailable" } }
Checks
Checks are performed on an applicant and consist of one or more reports.
Check object
Attribute | Description |
---|---|
id | string The unique identifier for the check. |
created_at | datetime The date and time at which the check was initiated. |
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. |
HTTP/1.1 201 Created Content-Type: application/json { "applicant_id": "<APPLICANT_ID>", "applicant_provides_data": false, "created_at": "2021-03-22T17:13:12Z", "form_uri": null, "href": "/v3.6/checks/<CHECK_ID>", "id": "<CHECK_ID>", "paused": false, "redirect_uri": null, "report_ids": [ "<REPORT_ID>" ], "result": null, "results_uri": "<RESULTS_URI>", "sandbox": true, "status": "in_progress", "tags": [], "version": "3.6", "webhook_ids": null }
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
Please note: When integrating with Onfido Studio workflows, checks are created automatically based on your specific workflow implementation. This endpoint is only applicable for implementations that rely on the explicit SDK configuration of verification steps.
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"]
Required applicant data
The following applicant data is required for all checks. Each report type may also require additional applicant data in order to be processed.
Location
You must provide location information for each applicant before creating a check with a Facial Similarity report. You can include location
as part of your API request when creating an applicant or uploading a document. If you do not provide location
all check requests will fail with a validation error.
Consent
If the location of the applicant is the US, you must also provide consent information confirming that the end user has viewed and accepted Onfido’s privacy notices and terms of service. You can specify consents
as part of your API request when creating or updating an applicant. If privacy_notices_read
is not set to "granted": true
, all check requests will fail with a validation error.
If you use the Onfido SDK, location and consent is collected directly by the SDK. You do not need to manually provide the location
or consents
parameter in this case.
For more information on the requirements and implementation options for collecting US end user consent please see our Onfido privacy notices and consent guide.
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. |
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. |
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 |
Device Intelligence | device_intelligence |
When creating a check, pass these in an array of strings to report_names
.
POST /v3.6/checks/ HTTP/1.1 Host: api.eu.onfido.com Authorization: Token token=<YOUR_API_TOKEN> Content-Type: application/json { "applicant_id": "<APPLICANT_ID>", "report_names": [ "document", "facial_similarity_photo" ] }
Retrieve check
Retrieves a single check. Returns a check object.
Please note: When integrating with Onfido Studio workflows, the status of verification checks is managed by workflow run output and can be retrieved by making a call to the Retrieve Workflow Run endpoint. This endpoint is only applicable for implementations where checks are created with the explicit SDK configuration of verification steps.
GET /v3.6/checks/<CHECK_ID> HTTP/1.1 Host: api.eu.onfido.com Authorization: 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.
GET /v3.6/checks?applicant_id=<APPLICANT_ID> HTTP/1.1 Host: api.eu.onfido.com Authorization: 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 are going to start processing immediately if the applicant has already submitted the form. The check status will automatically change to in_progress
. Otherwise, the check will remain as awaiting_applicant
and the reports are only going to start processing after the applicant submits the form.
GET /v3.6/checks/<CHECK_ID>/resume HTTP/1.1 Host: api.eu.onfido.com Authorization: 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.
GET /v3.6/checks/{check_id}/download HTTP/1.1 Host: api.eu.onfido.com Authorization: Token token=<YOUR_API_TOKEN>
Reports
In the Onfido API, checks are composed of one or more reports.
Report object
The report object will differ depending on the report itself.
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 and Facial Similarity 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 going through 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). |
Retrieve report
Retrieves a single report. Returns a report object.
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. This endpoint is only applicable for implementations where reports are part of checks created with the explicit SDK configuration of verification steps.
GET /v3.6/reports/<REPORT_ID> HTTP/1.1 Host: api.eu.onfido.com Authorization: Token token=<YOUR_API_TOKEN>
GET /v3.6/reports?check_id=<CHECK_ID> HTTP/1.1 Host: api.eu.onfido.com Authorization: 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.
POST /v3.6/reports/<REPORT_ID>/resume HTTP/1.1 Host: api.eu.onfido.com Authorization: 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.
POST /v3.6/reports/<REPORT_ID>/cancel HTTP/1.1 Host: api.eu.onfido.com Authorization: Token token=<YOUR_API_TOKEN>
Motion captures
Motion captures are representations of an applicant's face, recorded and uploaded by the Onfido input-capture SDKs (iOS, Android or Web), at the same time as the document image is captured—also by the SDKs. These 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. |
HTTP/1.1 201 Created Content-Type: application/json { "id": "<MOTION_CAPTURE_ID>", "created_at": "2022-11-12T17:12:44Z", "href": "/v3.6/motion_captures/<MOTION_CAPTURE_ID>", "download_href": "/v3.6/motion_captures/<MOTION_CAPTURE_ID>/download", "file_name": "<FILE_NAME>.mp4", "file_type": "video/mp4", "file_size": 1431121 }
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 input-capture SDKs (iOS, Android or Web).
Retrieve motion capture
Retrieves a single motion capture. Returns the corresponding motion capture object.
GET /v3.6/motion_captures/<MOTION_CAPTURE_ID> HTTP/1.1 Host: api.onfido.com Authorization: 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.
GET /v3.6/motion_captures?applicant_id=<APPLICANT_ID> HTTP/1.1 Host: api.onfido.com Authorization: Token token=<YOUR_API_TOKEN>
GET /v3.6/motion_captures/<MOTION_CAPTURE_ID>/download HTTP/1.1 Host: api.onfido.com Authorization: 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.
GET /v3.6/motion_captures/<MOTION_CAPTURE_ID>/frame HTTP/1.1 Host: api.onfido.com Authorization: Token token=<YOUR_API_TOKEN>
Unsuccessful frame extraction
Frame extraction failed
If a frame cannot be extracted from the motion capture, a frame_extraction_failed
response will be returned.
HTTP/1.1 422 Unprocessable Entity Content-Type: application/json { "error": { "type": "frame_extraction_failed", "message": "<Reason>" } }
Frame extraction unavailable
If the extraction feature is temporarily unavailable, a frame_extraction_unavailable
response will be returned instead.
HTTP/1.1 503 Service Unavailable Content-Type: application/json { "error": { "type": "frame_extraction_unavailable", "message": "Frame extraction is temporarily unavailable" } }
Monitors
Monitors are used for Ongoing Monitoring of an applicant and must be used together with Watchlist Reports. They listen for changes to Watchlist reports and when an update is detected, a new Check and corresponding Watchlist Report are created. Learn more about this feature here.
If you are interested in using this feature, it must first be enabled for your account. Please reach out to your CSM or email our Client Support team.
Monitor object
Attribute | Description |
---|---|
id | string The unique identifier for the monitor. |
created_at | datetime The date and time at which the monitor was created. |
deleted_at | datetime The date and time at which the monitor was deleted. If the monitor is still active, this field will be null. |
applicant_id | string The ID for the applicant associated with the monitor. |
report_name | string The name of the report type the monitor creates. Can be either "watchlist_standard" or "watchlist_aml" . |
tags | array of strings A list of tags associated with this monitor. These tags will be applied to each check this monitor creates. |
sandbox | boolean Indicates whether the object was created in the sandbox or not. |
HTTP/1.1 201 Created Content-Type: application/json { "id": “<MONITOR_ID>”, "applicant_id": "<APPLICANT_ID>", "report_name": "watchlist_standard", "created_at": "2022-09-01T15:01:36.921Z", "deleted_at": null, "sandbox": false, "tags": [] }
Create monitor
Creates a new monitor for the applicant.
Once created, the monitor will create an initial Watchlist report under the given applicant.
Only one active monitor can be created per applicant.
Request body parameters
Parameter | Description |
---|---|
applicant_id | required The ID for the applicant associated with the monitor. |
report_name | required The name of the report type the monitor creates. Can be either "watchlist_standard" or "watchlist_aml" . |
tags | optional A list of tags associated with this monitor. These tags will be applied to each check this monitor creates. |
POST /v3.6/watchlist_monitors/ HTTP/1.1 Host: api.eu.onfido.com Authorization: Token token=<YOUR_API_TOKEN> Content-Type: application/json { "applicant_id": "<APPLICANT_ID>", "report_name": "watchlist_aml" }
Retrieve monitor
Retrieves a single monitor. Returns a monitor object.
GET /v3.6/watchlist_monitors/<MONITOR_ID> HTTP/1.1 Host: api.eu.onfido.com Authorization: Token token=<YOUR_API_TOKEN>
List monitors
Returns all available monitors for an applicant. Returns data in the form: {"monitors":
[<LIST_OF_MONITOR_OBJECTS>]}
.
Query string parameters
Parameter | Description |
---|---|
applicant_id | optional The ID of the applicant whose monitors you want to list. If omitted, all monitors for the account will be listed. |
include_deleted | optional If this option is included, deleted (inactive) monitors will also be included in the list. |
GET /v3.6/watchlist_monitors?applicant_id=<APPLICANT_ID> HTTP/1.1 Host: api.eu.onfido.com Authorization: Token token=<YOUR_API_TOKEN>
Delete monitor
Deactivates the given monitor. No further updates will be given on this monitor, and all search information for this monitor will be deleted. Reports that have already been generated by the monitor will still exist.
Once a monitor is deleted, it cannot be re-activated.
If a monitor on an applicant was deleted in error, a new monitor will need to be created.
DELETE /v3.6/watchlist_monitors/<MONITOR_ID> HTTP/1.1 Host: api.eu.onfido.com Authorization: Token token=<YOUR_API_TOKEN>
List matches (BETA)
Gets a list of match IDs on this monitor, as well as their enabled/disabled status.
Match IDs are also visible in the report properties of monitored watchlist reports.
This will NOT return details about each match. (Such as name, media links, match type, etc.) This will only return the IDs and enabled/disabled status.
Match details are only viewable on reports generated by the monitor.
HTTP/1.1 200 Success Content-Type: application/json { "matches": [ { "id": <MATCH_ID>, "enabled": true }, { "id": <MATCH_ID>, "enabled": false }, ... ] }
GET /v3.6/watchlist_monitors/<MONITOR_ID>/matches HTTP/1.1 Host: api.eu.onfido.com Authorization: Token token=<YOUR_API_TOKEN>
Set match status (BETA)
Update the enabled status of the given matches.
Matches that are disabled will no longer contribute to overall results in future reports generated by this monitor.
Additionally, any updates to disabled matches will no longer trigger a new report to be generated.
Request body parameters
Parameter | Description |
---|---|
enable | optional Array of match IDs to set to enable: true . |
disable | optional Array of match IDs to set to enable: false . |
If no match IDs are provided, a 204 No Content
response is returned.
If the same ID is provided to both the “enable” and “disable” lists, a 422 validation_error
is returned. The “fields” messages in this case will be the list of IDs that are duplicated.
If any of the IDs in either the “enable” or “disable” lists are invalid (or pertain to matches that are not on the given monitor), a 422 validation_error
is returned. The “fields” messages in this case will be the list of IDs that are invalid.
PATCH /v3.6/watchlist_monitors/<MONITOR_ID>/matches HTTP/1.1 Host: api.eu.onfido.com Authorization: Token token=<YOUR_API_TOKEN> Content-Type: application/json { "disable": ["<MATCH_ID>", "<MATCH_ID>"] }
Force new report creation (BETA)
Triggers a new check with an updated report to be generated by the monitor, as if the monitor had received an update.
The report generated will not have any new information (as it is pulling from the same information as the previous report), but if matches have been newly enabled or disabled, the overall results may be different. For example, if all matches have been disabled, this will generate a “clear” report.
This endpoint has no request body.
If a new report is successfully generated, it will return a 201 Created
response with no response body.
A link to the newly generated report will be listed in the “Location” header of the response.
HTTP/1.1 201 Created Content-Type: application/json Location: "/api/v3.5/checks/<CHECK_ID>"
POST /v3.6/watchlist_monitors/<MONITOR_ID>/new_report HTTP/1.1 Host: api.eu.onfido.com Authorization: Token token=<YOUR_API_TOKEN>
Workflow Runs
Workflows are the container for how the end user will be verified using interactive and non-interactive tasks as configured using the Studio via the Onfido Dashboard. Workflow Runs are individual instances of the Workflow, and each Workflow Run requires data in order for it to execute.
The required Workflow Run data will be based on how the Workflow is configured in Onfido Studio. Data can either be provided through the Applicant Object and/or through the Custom Input Data Object.
Workflow Run Versions
Workflows are version controlled, meaning everytime a Workflow is edited and saved a new version is created. The active version of the Workflow will be used during the creation of a Workflow Run. Workflow Runs can only be created against the active version of the Workflow. The active version of a workflow can be designated in Studio via the Onfido Dashboard.
Workflow Run Status
Workflow Runs are transitioned through statuses as the Applicant progresses through the tasks. These statuses are visible on the Dashboard and available via the Retrieve Workflow Run endpoint.
Workflow Status | Description |
---|---|
awaiting_input | When the Workflow is waiting for an Applicant to complete a Smart Capture SDK interactive task. Note: If your Workflow has parallel tasks, awaiting_input will take precedence over processing . |
processing | When the Workflow is processing non-interactive tasks. |
abandoned | When an interactive task times out, the Workflow will be abandoned. Time outs can be configured per task in the Studio via Onfido Dashboard. |
error | The Workflow ended due to a technical issue during run time. |
approved | The Workflow Run reached an end task of ‘Approve Applicant’ based on the Workflow configuration. |
review | The Workflow Run reached an end task of ‘Review Applicant’ based on the Workflow configuration. |
declined | The Workflow Run reached an end task of ‘Decline Applicant’ based on the Workflow configuration. |
Workflow Run object
Attribute | Description |
---|---|
id | string (UUID) The unique identifier for the Workflow Run. |
applicant_id | string (UUID) The unique identifier for the Applicant. |
workflow_id | string (UUID) The unique identifier for the Workflow. |
workflow_version_id | int The identifier for the Workflow Version. |
dashboard_url | string The URL for viewing the workflow run results on your Onfido Dashboard. |
status | string (enum) The status of the Workflow Run. Possible values are: processing , awaiting_input , approved , declined , review , abandoned and error . |
output | output object Output object contains all of the properties configured on the workflow version. |
reasons | array (string) The reasons the Workflow Run outcome was reached. Configurable when creating the Workflow Version. |
error | error object Error object. Only set when the Workflow Run status is error . |
link | link object Link object. |
created_at | datetime (ISO-8601) The date and time when the Workflow Run was created. |
updated_at | datetime (ISO-8601) The date and time when the Workflow Run was last updated. |
Output object
Workflow output data is a configurable set of properties which allows you to add any specific data attribute contained within a Workflow.
Workflow Output information must be first created as a property in Studio using the Workflow input and output configuration tab. Once the properties are created
then these need to be mapped on the end tasks. This gives full flexibility to add as little or as much detailed information to the Retrieve Workflow Run endpoint.
This is the recommended method to integrate with our API to get information into your systems.
Reasons
Workflow reasons are set during Workflow creation in Studio. Each end task can have one or more reasons configured by the user.
This provides the flexibility to capture more information about why an end user reached a specific end state.
For example, if a workflow contains multiple approval end tasks, the reasons field can be used to clearly identify which path the end user completed.
Error object
Error object that details why a Workflow Run is in Error status.
Attribute | Description |
---|---|
type | string The type of the error. |
message | string A textual description of the error. |
Link object
Object for the configuration of the Workflow Run link.
Attribute | Description |
---|---|
url | string Link to access the Workflow Run without the need to integrate with Onfido's SDKs. |
completed_redirect_url | string When the interactive section of the Workflow Run has completed successfully, the user will be redirected to this URL instead of seeing the default Onfido "thank you" page. |
expired_redirect_url | string When the Link has expired, the user will be immediately redirected to this URL instead of seeing the default Onfido error message. |
expires_at | string (ISO-8601) Date and time when the link will expire. Additional details. |
language | string (enum) The code for the language when the Workflow Run is acessed using the link. |
HTTP/1.1 201 Created Content-Type: application/json { "id": "<WORKFLOW_RUN_ID>", "applicant_id": "<APPLICANT_ID>", "workflow_id": "<WORKFLOW_ID>", "workflow_version_id": 11, "status": "approved", "dashboard_url":"https://dashboard.onfido.com/results/<WORKFLOW_RUN_ID>" "output": {"prop1": "val_1", "prop2": 10}, "reasons": ["reason_1", "reason_2"], "error": null, "created_at": "2022-06-28T15:39:42Z", "updated_at": "2022-07-28T15:40:42Z", "link": { "completed_redirect_url": "https://example.onfido.com", "expired_redirect_url": "https://example.onfido.com", "expires_at": "2022-10-17T14:40:50Z", "language": "en_US", "url": "https://eu.onfido.app/l/<WORKFLOW_RUN_ID>" }, }
Create Workflow Run
Creates and starts a Workflow Run. Returns a Workflow Run object.
A Workflow must exist and be activated before you can create a Workflow Run. You can create and activate your Workflow
in your Studio via Onfido Dashboard. An Applicant ID is mandatory for creating a Workflow Run.
Any data that you want to provide to be used in the Workflow Run can be passed in two ways at its creation:
Request body parameters
Parameter | Description |
---|---|
workflow_id | required string (UUID) The unique identifier for the Workflow. |
applicant_id | required string (UUID) The unique identifier for the Applicant. |
custom_data | optional custom data object Object with Custom Input Data to be used in the Workflow Run. |
link | optional link object Link object to configure the Workflow Run link. |
Applicant Data
The Workflow Run requires an Applicant ID, meaning that the Workflow is able to access information stored in the Applicant.
Before being able to use that data within the Workflow Run, you must specify which Applicant fields you intend to use by configuring the Input Data via Studio. The additional Applicant fields you decide to use become mandatory and the Workflow Run create endpoint will validate if they are present before creating the Workflow Run. You can manage the Applicant using the create and update endpoints.
Custom Input Data
If you have business-specific data that you want to use during your workflow, you can configure Custom Input Data
using the Studio via the Onfido Dashboard.
If Custom Input Data is configured, then it becomes mandatory when creating a Workflow Run.
Link object
Object for the configuration of the Workflow Run link.
Attribute | Description |
---|---|
completed_redirect_url | optional string When the interactive section of the Workflow Run has completed successfully, the user will be redirected to this URL instead of seeing the default Onfido "thank you" page. |
expired_redirect_url | optional string When the Link has expired, the user will be immediately redirected to this URL instead of seeing the default Onfido error message. |
expires_at | optional string (ISO-8601) Date and time when the link will expire. Additional details. |
language | optional string (enum) The code for the language when the Workflow Run is acessed using the link. The supported languages are listed below. Defaults to en_US if not specified. |
Supported languages
Code | Language |
---|---|
en_US | English (default) |
de_DE | German |
es_ES | Spanish |
fr_FR | French |
it_IT | Italian |
pt_PT | Portuguese |
nl_NL | Dutch |
Link expiration
When the link expires, the Applicant won't be able to use it anymore to access the Workflow Run journey. If no expiration date and time is set, the link will be acessible
until the Workflow Run reaches an end state (abandoned
, error
, approved
, review
and declined
).
POST /v3.6/workflow_runs HTTP/1.1 Host: api.eu.onfido.com Authorization: Token token=<YOUR_API_TOKEN> Content-Type: application/json { "workflow_id": "<WORKFLOW_ID>", "applicant_id": "<APPLICANT_ID" }
List Workflow Runs
Retrieves the Workflow Runs of the client. Returns a list of Workflow Run objects. The page size is 20 objects.
Query String parameters
page
(optional): The number of the page to be retrieved. If not specified, defaults to 1.
status
(optional): a list of comma separated status values to filter the results.
created_at_gt
(optional): a ISO-8601 date to filter results with a created date greater than (after) the one provided.
created_at_lt
(optional): a ISO-8601 date to filter results with a created date less than (before) the one provided.
sort
(optional): a string with the value desc
or asc
that allows to sort the returned list by the completed datetime either descending or ascending, respectively.
If not specified, defaults to desc
.
GET /v3.6/workflow_runs HTTP/1.1 Host: api.eu.onfido.com Authorization: Token token=<YOUR_API_TOKEN>
Retrieve Workflow Run
Retrieves a Workflow Run. Returns a Workflow Run object.
Path parameters
workflow_run_id
(required): the unique identifier of the Workflow Run you want to retrieve.
GET /v3.6/workflow_runs/<WORKFLOW_RUN_ID> HTTP/1.1 Host: api.eu.onfido.com Authorization: Token token=<YOUR_API_TOKEN>
Tasks
Tasks are the individual steps that make up a Workflow Run. Tasks may require Task input data in order to execute,
and will return Task output data on completion. Task input data can be managed by selecting a Task and configuring it
in the input tab in Studio. The Task endpoints are designed to enable auditability and transparency of Workflow Runs
by providing Task input and output.
Tasks are versioned using unique Task Definitions so that each time enhancements, new features or bugs are released,
the functioning of these Tasks remains unchanged, preserving the integrity of the previous version of the Workflow.
Task inputs and outputs may change between Task versions.
The Task input and output information is accessible directly in Studio and should be used to configure an applicant's
verification journey using the condition tasks. For example, Tasks output data can be used to decide the next Tasks to
perform, or the end state of the Applicant verification journey directly within Studio.
Despite this data being available and accessible through these endpoints, it also comes with some drawbacks. If changes
are made to the Workflow, or individual Tasks are updated (new features, bug fixing, for example), the schemas may change,
which could break previous integrations.
As such, Task endpoints are not recommended to be used as an integration method to retrieve data, please use the Output object in Workflow Run.
Task object
Attribute | Description |
---|---|
id | string The identifier for the Task. |
task_def_id | string The identifier for the Task Definition. |
workflow_run_id | string (UUID) The identifier for the Workflow Run to which the task belongs. |
input | object Input object with the fields used by the Task to execute. |
output | object Output object with the fields produced by the Task execution. |
created_at | datetime (ISO-8601) The date and time when the Task was created. |
updated_at | datetime (ISO-8601) The date and time when the Task was last updated. |
HTTP/1.1 201 Created Content-Type: application/json { "id": "<TASK_ID>", "task_def_id": "<TASK_DEF_ID>", "workflow_run_id": "<WORKFLOW_RUN_ID>", "input": {"document_ids":["dd1a606c-787f-4203-8e71-7d4c9adb090d"]}, "output": {"extracted_data": {"first_name": "Jane", "last_name": "Doe"}}, "created_at": "2022-06-28T15:39:42Z", "updated_at": "2022-07-28T15:40:42Z", }
List Tasks
Retrieves the Tasks of a Workflow Run. Returns a subset of the Task
object.
The response contains only Tasks that were already started or completed, ordered by the created_at
field, in ascending order.
Path parameters
workflow_run_id
(required): the unique identifier of the Workflow Run to which the Tasks belong.
Example response
[ { "id": "<TASK_ID>", "task_def_id": "<TASK_DEF_ID>", "workflow_run_id": "<WORKFLOW_RUN_ID>", "created_at": "2022-06-28T15:39:42Z", "updated_at": "2022-07-28T15:39:52Z", }, { "id": "<TASK_ID>", "task_def_id": "<TASK_DEF_ID>", "workflow_run_id": "<WORKFLOW_RUN_ID>", "created_at": "2022-06-28T15:40:42Z", "updated_at": "2022-07-28T15:40:52Z", } ... ]
GET /v3.6/workflow_runs/<WORKFLOW_RUN_ID>/tasks HTTP/1.1 Host: api.eu.onfido.com Authorization: Token token=<YOUR_API_TOKEN>
Retrieve Task
Retrieves a Task. Returns a Task object.
Path parameters
workflow_run_id
(required): the unique identifier of the Workflow Run to which the Task belongs.
task_id
(required): the identifier of the Task you want to retrieve.
GET /v3.6/workflow_runs/<WORKFLOW_RUN_ID>/tasks/<TASK_ID> HTTP/1.1 Host: api.eu.onfido.com Authorization: Token token=<YOUR_API_TOKEN>
Complete Task
Completes a Send / Receive Data Task.
Path parameters
workflow_run_id
(required): the unique identifier of the Workflow Run to which the Task belongs.
task_id
(required): the identifier of the Task you want to complete.
Request body parameters
Parameter | Description |
---|---|
data | required object The Task completion payload. More details below. |
Send / Receive Data Tasks
Send / Receive Data Tasks are a special type of Task that allow you to create custom actions that can be executed anywhere in a workflow.
You can send data out of the system mid workflow and pass data back in to be used in more logic tasks.
You can configure a Send / Receive Data Task in the Workflow Builder, while defining your Workflow. When configuring a Send / Receive Data Task, you should
define the input and output data it expects. The logic necessary to process the inputs and produce the outputs is up to the service being called.
The recommended way of integrating a Send / Receive Data Task is configuring a workflow_task.started
Webhook, so you can be notified when the task is ready
to execute. The payload of this Webhook contains all the inputs you have defined for your Task.
Once notified by our Webhook, your system can asynchronously run any custom action you want to produce the desired outputs. Once ready, you should
invoke the Complete Task endpoint, providing as data
parameter an object with the outputs you have defined. Our system will validate the provided data against
the output schema you have defined when configuring the Send / Receive Data Task and return an HTTP 422 error if they don't match.
If the submission of the data is successful, the Send / Receive Data Task will be completed and the Workflow will proceed. All data received back into the Workflow Run will be able to be used in our condition logic tasks.
You can configure as many Send / Receive Data Tasks as you want in your Workflow.
POST /v3.6/workflow_runs/<WORKFLOW_RUN_ID>/tasks/<TASK_ID>/complete HTTP/1.1 Host: api.eu.onfido.com Authorization: Token token=<YOUR_API_TOKEN> Content-Type: application/json { "data":{ "field_1": "value_1", "field_2": "value_2" } }
Document report
This API documentation offers detailed information about the structure of a Document report, including an example of the report's result and its breakdowns.
For a more general introduction to the Document report, you may wish to read our product documentation.
After you've familiarised yourself with the information here, you may also wish to read our guide on suggested client actions for different result scenarios.
There are 5 different types of Document reports:
Document (almost all use cases require this "primary" type)
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"] | In beta |
Document with Address Information, Document Video with Address Information and Document with Driving Licence Information are in beta. They are supersets of the Document report which add functionality for specific use cases. Contact your account manager for more information about the features in these beta reports.
By default, the most recently uploaded document will be used.
To specify which uploaded document to run the Document
report against in the API, or specify document IDs extracted from the Onfido SDK callback, use the document_ids
field. This takes an array
of up to 3 strings (3 document IDs):
"document_ids": ["<DOCUMENT_ID>"]
The Document report is composed of data integrity, visual authenticity and police record checks. It checks the internal and external consistency of the document provided by the applicant to identify potential discrepancies.
In addition, any data extracted from the document is returned in the properties
attribute.
The Document report combines software and an expert team to maximise fraud detection. The majority of documents will be processed instantly. However, when document analysis falls back to expert review, the report status will be delivered asynchronously via webhook notifications.
Expert review is required when we encounter images that use sophisticated counterfeiting techniques, or the image is of poor quality (blurred, low resolution, obscured, cropped, or held at an unreadable angle).
Near Field Communication (NFC)
If available, the Document report uses NFC to validate the document's chip in order to verify the document. In this case, the visual authentication, image integrity and data consistency checks will not be performed.
NFC is only available via the Onfido mobile SDKs. Please read our NFC for Document report guide for details on how to integrate and use NFC for Document reports.
You can view the full list of supported documents for NFC.
Repeat attempts
You can also use our repeat attempts endpoint to request a list of repeat attempt matches for Document reports. A repeat attempt is any previous Document report that was submitted using the same document type, with the same document number. This can indicate instances of repeat fraud where users submit multiple requests using the same document but with different personal data.
Required applicant data
For Document reports, first_name
and last_name
must be provided but can be
dummy values if you don't know an applicant's name.
Document type and issuing country
If you’re creating a check containing a Document report, we do not validate
that the properties type
and issuing_country
in the uploaded
document match extracted values (which are returned in the
Document report object).
Document report: Object
Our newly expanded OpenAPI specification, which is currently in beta, is the best resource for understanding the Document report response object structure. We welcome feedback on this beta initiative under the 'Issues' tab on GitHub, or at (openapi-feedback@onfido.com)[mailto:openapi-feedback@onfido.com].
We host a separate page which contains a detailed description of the Document report object values from an API user's perspective.
Results
The result
field indicates the overall report result. Possible values for
Document reports are clear
and consider
:
Report 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
, consider
and null.
A breakdown will have the result consider
when at least one sub-breakdown
contains a consider
or unidentified
result. For example, a consider
result
for the mrz
sub-breakdown will produce a consider
result for the
data_validation
breakdown. This will then also set the report sub_result
value to suspected
.
A breakdown will have the result null when it has not been completed, or is not available. For example, issuing_authority
will return null if NFC is not available or inconclusive.
Some breakdowns contain sub-breakdowns. For example, the image_integrity
breakdown comprises the sub-breakdowns supported_document
, image_quality
,
colour_picture
and conclusive_document_quality
.
The possible values for sub-breakdowns are clear
, consider
, null and
unidentified
.
Breakdown order priority
Breakdown sub-results have the following order of priority:
rejected
->suspected
->caution
->clear
For example, a caution
sub-result will only ever be asserted when the following
conditions are met:
- no individual breakdown has caused a
rejected
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.
Note: Some breakdowns have sub-breakdowns that are mapped to different sub-results. For example, in the Data Validation breakdown, gender
, document_numbers
, expiry_date
, date_of_birth
, mrz
and barcode
map to suspected
whereas document_expiration
maps to caution
.
Note: When a sub-breakdown mapped to a rejected
sub-result is flagged, all other breakdowns and the document properties will be omitted from the response object.
Breakdown descriptions and logic
data_comparison
:
Establishes whether the data provided by the applicant matches the data extracted from the document. This breakdown is only returned if Comparison Checks are enabled for your account. Otherwise, the breakdown and its sub-breakdowns are returned as null and will not affect the final report result. To enable Comparison Checks, please contact Client Support.
We compare the following fields:
first_name
last_name
date_of_birth
gender
first_name
and last_name
can be configured to use a fuzzy or exact mechanism for the comparison. We take into account all available names for comparison, including spouse, widow or alias names.
date_of_birth
and gender
will always be compared using an exact mechanism.
Fuzzy comparison 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
barcode
- 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 16 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
:
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 as null and have no impact on the sub-result.
police_record
:
Asserts whether the document has been identified as lost, stolen or otherwise compromised. Applies to all documents that have been reported as stolen or fraudulent to the UK Metropolitan Police.
This breakdown is only returned if Police Record Checks are enabled for your account. Otherwise, the breakdown and its sub-breakdowns are returned as null and will not affect the final report result. To enable Police Record Checks, please contact Client Support.
compromised_document
:
Asserts whether the image of the document has been found in our internal database.
document_database
:Asserts whether the document is publicly available as compromised.
repeat_attempts
:Asserts whether the document has been reused in a suspicious way.
issuing_authority
:
Asserts whether data on the document matches the issuing authority data. Uses the following sub-breakdowns:
nfc_active_authentication
:Asserts whether the document NFC chip is original or cloned.
nfc_passive_authentication
:Asserts whether the document NFC chip data was tampered.
If NFC is completed, the visual authentication, image integrity and data consistency checks will not be performed and the breakdowns will be null.1
- You can configure your account to always trigger Visual Document Verification if
nfc_active_authentication
is returned as null (even ifnfc_passive_authentication
isclear
). In this case, the visual authentication, image integrity and data consistency checks will be performed and the results returned in the breakdowns.
Document report: Breakdown reasoning
We will return a reason whenever a report flags for one of the following breakdowns:
visual_authenticity
:original_document_present
image_integrity
:conclusive_document_quality
image_integrity
:image_quality
This works by returning the contributing reason and corresponding fail result (a consider
result) in the breakdown properties.
There can be more than one reason per breakdown, as they aren’t mutually exclusive.
All other signals and potential reasons will be omitted.
The following diagram illustrates this logic:
Original Document Present reasons:
photo_of_screen
- When we can see that the applicant's document is on a physical screen or device, e.g. when the device is visible, software applications are seen, a computer cursor is present, or the pixels on the image appearing to have a different texture than expected
screenshot
- When the applicant has used their mobile phone, tablet, or computer to take a photo within the device, e.g. when software applications are seen, the time and mobile provider are visible, or any digitally added component that wouldn't be seen on a physical document, such as an upload icon
document_on_printed_paper
- when the applicant has previously captured an image of the document, printed it out, and has now taken a photo of this print out to upload, e.g. when the edges of the paper are visible, when there are fold creases on the paper, or the document's edges blending into the background and appearing flat
scan
- When the document has clearly been captured using a scanner and there are visible indicators of this, e.g. unusual shadows on the edges of the document, or written text around the document
Conclusive Document Quality reasons:
obscured_data_points
- This refers to when data points are obscured to the point that we cannot confirm if the fonts match the expected ones
obscured_security_features
- This refers to whenever a critical security feature is obscured. This can also refer to when the holder's wet signature, necessary for the document to be valid, is not present
abnormal_document_features
- One of 3 reasons: (1) OCR Assisted Scans (i.e. when you're able to move the mouse and highlight part of text), (2) Severely Washed out Background, (3) Overlapping Text
watermarks_digital_text_overlay
- Any digital text or electronic watermarks on the document
corner_removed
- If the corner has been physically cut off. This can be found on some documents that are no longer valid
punctured_document
- A punched hole is present. This can be found on DLs that are no longer valid, for example
missing_back
- When the back of a document is needed for processing (e.g. for key data points to extract), but is not available (e.g. if the same front was uploaded twice)
digital_document
- When a document has been published digitally, there aren’t enough security features to review so we cannot perform a full fraud assessment
Image Quality reasons:
dark_photo
- When an image of the document is too dark to be able to see data points
glare_on_photo
- When there is light reflecting on the document causing glare to obstruct data points
blurred_photo
- When data points are blurred and no reference can be made elsewhere in the document or if the data points are too blurry and 'they could be something else' (e.g. "I" could be "1", "B" could be "8")
covered_photo
- When data points have been covered either by the applicant or by another object such as a sticker
other_photo_issue
- Any other reason not listed, such as when holograms are obscuring data points
damaged_document
- When a document is damaged and we are unable to make out data points
incorrect_side
- When the incorrect side of a document has been uploaded, and we have not received the front
cut_off_document
- When data points are not included in the image due to the document being cut off (i.e. out of the frame of the image)
no_document_in_image
- If no document has been uploaded or there is a blank image
two_documents_uploaded
- When 2 different documents are submitted in the same check
HTTP/1.1 201 Created Content-Type: application/json { "breakdown": { "age_validation": { "breakdown": { "minimum_accepted_age": { "properties": {}, "result": "clear" } }, "result": "clear" }, "compromised_document": { "breakdown": { "document_database": { "properties": {}, "result": "clear" }, "repeat_attempts": { "properties": {}, "result": "clear" } }, "result": "clear" }, "data_comparison": { "breakdown": { "date_of_birth": { "properties": {}, "result": "clear" }, "date_of_expiry": { "properties": {}, "result": null }, "document_numbers": { "properties": {}, "result": null }, "document_type": { "properties": {}, "result": null }, "first_name": { "properties": {}, "result": "clear" }, "gender": { "properties": {}, "result": null }, "issuing_country": { "properties": {}, "result": null }, "last_name": { "properties": {}, "result": "clear" } }, "result": "clear" }, "data_consistency": { "breakdown": { "date_of_birth": { "properties": {}, "result": "clear" }, "date_of_expiry": { "properties": {}, "result": "clear" }, "document_numbers": { "properties": {}, "result": "clear" }, "document_type": { "properties": {}, "result": "clear" }, "first_name": { "properties": {}, "result": "clear" }, "gender": { "properties": {}, "result": "clear" }, "issuing_country": { "properties": {}, "result": "clear" }, "last_name": { "properties": {}, "result": "clear" }, "multiple_data_sources_present": { "properties": {}, "result": "clear" }, "nationality": { "properties": {}, "result": "clear" } }, "result": "clear" }, "data_validation": { "breakdown": { "date_of_birth": { "properties": {}, "result": "clear" }, "document_expiration": { "properties": {}, "result": "clear" }, "document_numbers": { "properties": {}, "result": "clear" }, "expiry_date": { "properties": {}, "result": "clear" }, "gender": { "properties": {}, "result": "clear" }, "mrz": { "properties": {}, "result": "clear" }, "barcode": { "properties": {}, "result": "clear" } }, "result": "clear" }, "image_integrity": { "breakdown": { "colour_picture": { "properties": {}, "result": "clear" }, "conclusive_document_quality": { "properties": {}, "result": "clear" }, "image_quality": { "properties": {}, "result": "clear" }, "supported_document": { "properties": {}, "result": "clear" } }, "result": "clear" }, "police_record": { "result": "clear" }, "visual_authenticity": { "breakdown": { "digital_tampering": { "properties": {}, "result": "clear" }, "face_detection": { "properties": {}, "result": "clear" }, "fonts": { "properties": {}, "result": "clear" }, "original_document_present": { "properties": {}, "result": "clear" }, "other": { "properties": {}, "result": "clear" }, "picture_face_integrity": { "properties": {}, "result": "clear" }, "security_features": { "properties": {}, "result": "clear" }, "template": { "properties": {}, "result": "clear" } }, "result": "clear" }, "issuing_authority": { "breakdown": { "nfc_active_authentication": { "properties": {}, "result": null }, "nfc_passive_authentication": { "properties": {}, "result": null } }, "result": null } }, "check_id": "<CHECK_ID>", "created_at": "2021-03-22T17:13:12Z", "documents": [ { "id": "<DOCUMENT_ID>" } ], "href": "/v3.6/reports/<REPORT_ID>", "id": "<REPORT_ID>", "name": "document", "properties": { "date_of_birth": "1990-01-01", "date_of_expiry": "2030-01-01", "document_numbers": [ { "type": "document_number", "value": "999999999" } ], "document_type": "passport", "first_name": "Jane", "gender": "", "issuing_country": "GBR", "last_name": "Doe", "nationality": "" }, "result": "clear", "status": "complete", "sub_result": "clear" }
Document video report
For a general introduction to the Document Video Report, you may wish to read our product documentation.
To request a Document Video Report as part of a check in the API, use the report_names
field (which takes an array of strings):
"report_names": ["document_video"]
Document video report: Breakdown reasoning
The image_integrity
breakdown of the Document Video Report response includes a video_document_presence
sub-breakdown, which has the results clear
and unidentified
.
video_document_presence
also has a property, called invalid_signature
. If the media signature of a recorded video is not valid, the property will return consider
, and the sub-breakdown will return unidentified
. In this case, the Document Video Report will be rejected
.
With a clear
report result, the following snippet is an example showing what is added to the Document report response object:
"image_integrity": { "breakdown": { "video_document_presence": { "properties": {}, "result": "clear" } }, "result": "clear" },
BETA Document report options
Document with Address Information
This report is in beta. Contact your account manager for more information about the features in this report.
To request a Document with Address Information report as part of a check in
the API, use the report_names
field (which takes an array of strings):
"report_names": ["document_with_address_information"]
By default, the most recently uploaded document will be used.
If you use this report, Onfido will use a third-party subprocessor for address cleansing after the address has been extracted.
To specify which uploaded document to run the Document
with Address Information report against in the API, use the document_ids
field. This takes an array
of up to 2 strings (2 document IDs):
"document_ids": ["<DOCUMENT_ID>"]
For a clear
result, the following snippet is an example showing what is added to the Document report response object:
... "address_lines": { "city": "EDINBURGH", "country": "United Kingdom (UK)", "postal_code": "EH1 9GP", "state": "", "street_address": "122 BURNS CRESCENT", "country_code": "GBR" }, "address": "<ADDRESS_STRING>", ...
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:
... "address_lines": { "city": "EDINBURGH", "country": "United Kingdom (UK)", "postal_code": "EH1 9GP", "state": "", "street_address": "122 BURNS CRESCENT", "country_code": "GBR" }, "address": "<ADDRESS_STRING>", ...
Contact your account manager for more information about the features in the Document Video with Address Information report.
Document with Driving Licence Information
This report is in beta. Contact your account manager for more information about the features in this report.
To request a Document with Driving Licence Information report as part of a
check in the API, use the report_names
field (which takes an array of
strings):
"report_names": ["document_with_driving_licence_information"]
By default, the most recently uploaded document will be used.
To specify which uploaded document to run the Document
with Driving Licence Information report against in the API, use the document_ids
field. This takes an array of up to 2 strings (2 document IDs):
"document_ids": ["<DOCUMENT_ID>"]
For a clear
result, the following snippet is an example showing what is added to the Document report response object:
... "driving_licence_information": [ { "category": "A", "codes": "79.03,79.04", "expiry_date": "<YYYY-MM-DD>", "obtainment_date": "<YYYY-MM-DD>" }, { "category": "A1", "codes": "79.03,79.04", "expiry_date": "<YYYY-MM-DD>", "obtainment_date": "<YYYY-MM-DD>" }, { "category": "AM", "codes": "", "expiry_date": "<YYYY-MM-DD>", "obtainment_date": "<YYYY-MM-DD>" }, { "category": "B", "codes": "", "expiry_date": "<YYYY-MM-DD>", "obtainment_date": "<YYYY-MM-DD>" } ], ...
Contact your account manager for more information about the features in the Document with Driving Licence Information report.
Facial Similarity reports
This API documentation offers detailed information about the structure of a Facial Similarity report, including an example of the report's result and its breakdowns.
For a more general introduction to the Facial Similarity report, you may wish to read our product documentation.
After you've familiarised yourself with the information here, you may wish to read our guide on suggested client actions for different result scenarios.
Creating a check with a Facial Similarity report will cause you to process facial biometric personal data. Always make sure you inform your users about this and obtain any necessary permissions. For more information on how Onfido uses personal data, view our Privacy Policy.
There are 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 or NFC media provided during check creation in the document_ids
field.
"document_ids": ["<DOCUMENT_ID>"]
By default, the most recently uploaded document specified will be used. If unspecified, the most recently uploaded document will be used.
Where the document has two sides, we will search both sides of the document for a face. Where the document has been scanned using NFC, we will use the face extracted from the document's NFC chip.
When document IDs are associated with a Facial Similarity report, the document IDs of the documents used will be returned under the documents
attribute of the report object.
When side
is not specified, it will take a default value of front
. We
recommend that all documents contain the side
attribute, as this minimises
the cases where the back of the document is used for comparison and thus
failed as no face is detected.
Required applicant data
For all Facial Similarity report types, first_name
and last_name
must
be provided but can be dummy values if you don't know an applicant's name.
Facial Similarity Photo
If applicant_provides_data
is true
,
the Facial Similarity Photo report needs to be paired with a Document
report.
Facial Similarity Photo: Object
The following table describes the unique fields returned in this version of the Onfido API for a completed Facial Similarity Photo report:
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 and document_id
unique identifier under the properties
bag (see Facial Similarity Photo: Face Match properties)
3: spoofing_detection
contains a score
value under the properties
bag (see Facial Similarity Photo: Spoofing Detection Score)
A breakdown or sub-breakdown will have the result null
when it has not been completed. This occurs when it is not available, or has failed to process the media due to a timeout or an internal error. In this case, the report will go to manual review.
Facial Similarity Photo: Breakdowns
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 and document_id unique identifier for the matched document under the properties bag (see Facial Similarity Photo: Match properties). |
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 usedpayload_integrity
- when evidence is found that the payload was tampered withreasons
- additional comma separated details such as the exact digital tampering software used, or the name of the fake webcam
Facial Similarity Photo: Face Match properties
The face_match
breakdown contains a properties
object with a score
value and document_id
unique identifier.
The
score
value is a floating point number between 0 and 1 that expresses how similar the two faces are, where 1 is a perfect match.If the face matching algorithm fails to detect a face, the
score
property will not be present and the face matching task will be done manually. The score only measures how similar the faces are, and does not make an assessment of the nature of the photo. If spoofing (such as photos of printed photos or photos of digital screens) is detected the applicant will be rejected independently of the face match score.document_id
returns the UUID for the document containing the extracted face that was used for face matching.If no face is detected, no document is recorded and the property is returned as
null
.
Facial Similarity Photo: Spoofing Detection Score
The spoofing_detection
breakdown contains a properties
object with a score
value. This score is a floating point number between 0 and 1. The closer the
score is to 0, the more likely it is to be a spoof (i.e. photos of printed
photos, or photos of digital screens). Conversely, the closer it is to 1, the
less likely it is to be a spoof.
HTTP/1.1 201 Created Content-Type: application/json { "created_at": "2019-12-11T09:39:05Z", "href": "/v3.6/reports/<REPORT_ID>", "id": "<REPORT_ID>", "name": "facial_similarity_photo", "properties": {}, "result": "clear", "status": "complete", "sub_result": null, "breakdown": { "face_comparison": { "result": "clear", "breakdown": { "face_match": { "result": "clear", "properties": { "score": 0.6512, "document_id": "<DOCUMENT_ID>" } } } }, "image_integrity": { "result": "clear", "breakdown": { "face_detected": { "result": "clear", "properties": {} }, "source_integrity": { "result": "clear", "properties": {} } } }, "visual_authenticity": { "result": "clear", "breakdown": { "spoofing_detection": { "result": "clear", "properties": { "score": 0.9512 } } } } }, "check_id": "<CHECK_ID>", "documents": [] }
Photo Fully Auto
If applicant_provides_data
is true
,
the Photo Fully Auto report needs to be paired with a Document
report.
Photo Fully Auto: Object
The following table describes the unique fields returned in this version of the Onfido API for a completed Photo Fully Auto report:
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 and document_id
unique identifier under the properties
bag (see Face Match properties for Photo Fully Auto)
3: spoofing_detection
contains a score
value under the properties
bag (see Spoofing Detection Score for Photo Fully Auto)
Photo Fully Auto: Breakdowns
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 and document_id unique identifier for the matched document under the properties bag (see Face Match properties 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 usedpayload_integrity
- when evidence is found that the payload was tampered withreasons
- additional comma separated details such as the exact digital tampering software used, or the name of the fake webcam
Photo Fully Auto: Face Match properties
The face_match
breakdown contains a properties
object with a score
value and document_id
unique identifier.
The
score
value is a floating point number between 0 and 1 that expresses how similar the two faces are, where 1 is a perfect match.If the face matching algorithm fails to detect a face, the
score
property will not be present. The score only measures how similar the faces are, and does not make an assessment of the nature of the photo. If spoofing (such as photos of printed photos or photos of digital screens) is detected the applicant will be rejected independently of the face match score.document_id
returns the UUID for the document containing the extracted face that was used for face matching.If no face is detected, no document is recorded and the property is returned as
null
.
Photo Fully Auto: Spoofing Detection Score
The spoofing_detection
breakdown contains a properties
object with a score
value. This score is a floating point number between 0 and 1. The closer the
score is to 0, the more likely it is to be a spoof (i.e. photos of printed
photos, or photos of digital screens). Conversely, the closer it is to 1, the
less likely it is to be a spoof.
If the anti-spoofing algorithm fails to detect a face, the score
property will
not be present.
HTTP/1.1 201 Created Content-Type: application/json { "created_at": "2020-01-01T14:16:21Z", "href": "/v3.6/reports/<REPORT_ID>", "id": "<REPORT_ID>", "name": "facial_similarity_photo_fully_auto", "result": "clear", "status": "complete", "sub_result": null, "breakdown": { "visual_authenticity": { "result": "clear", "breakdown": { "spoofing_detection": { "result": "clear", "properties": { "score": 0.9901 } } } }, "image_integrity": { "result": "clear", "breakdown": { "face_detected": { "result": "clear", "properties": {} }, "source_integrity": { "result": "clear", "properties": {} } } }, "face_comparison": { "result": "consider", "breakdown": { "face_match": { "result": "consider", "properties": { "score": 0.2097, "document_id": "<DOCUMENT_ID>" } } } } }, "check_id": "<CHECK_ID>" }
Facial Similarity Video
In the Facial Similarity Video report, live videos are collected and uploaded by one of the Onfido SDKs (iOS, Android or JS).
Checks where applicant_provides_data
is true
are not
compatible with Facial Similarity Video reports.
In addition to confirming the two faces match, Facial Similarity Video
assesses active liveness by asking users to repeat randomly generated numbers
and perform a random head movement. This prevents impersonation - for example
masks, and deep fakes displayed on digital screens. This process is reflected
in visual_authenticity
, which is composed of the sub-breakdowns
spoofing_detection
and liveness_detected
. See Facial
Similarity Video Object and Facial
Similarity Video Breakdowns.
In order for a Facial Similarity Video report to complete automatically, the user needs to turn their head in the correct direction and correctly say the 3 randomly generated digits in one of our supported languages (see table below).
Language 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 and document_id
unique identifier under the properties
bag (see Facial Similarity Video: Face Match properties)
3: spoofing_detection
contains a score
value under the properties
bag (see Facial Similarity Video: Spoofing Detection Score)
Facial Similarity Video: Breakdowns
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 and document_id unique identifier for the matched document under the properties bag (see Facial Similarity Video: Face Match properties). |
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 usedpayload_integrity
- when evidence is found that the payload was tampered withchallenge_reuse
- when evidence is found that the video was uploaded in an attempt to circumvent the randomness of the speaking and head turn challengesreasons
- additional comma separated details, such as the name of the fake webcam
Facial Similarity Video: Face Match properties
The face_match
breakdown contains a properties
object with a score
value and document_id
unique identifier.
The
score
value is a floating point number between 0 and 1 that expresses how similar the two faces are, where 1 is a perfect match.If the face matching algorithm fails to detect a face, the
score
property will not be present and the face matching task will be done manually. The score only measures how similar the faces are, and does not make an assessment of the nature of the live video. If spoofing (such as videos of digital screens, masks or print-outs) is detected the applicant will be rejected independently of the face match score.document_id
returns the UUID for the document containing the extracted face that was used for face matching.If no face is detected, no document is recorded and the property is returned as
null
.
Facial Similarity Video: Spoofing Detection Score
The spoofing_detection
breakdown contains a properties
object with a
score
value. This score is a floating point number between 0 and 1. The
closer the score is to 0, the more likely it is to be a spoof (i.e. videos of
digital screens, masks or print-outs). Conversely, the closer it is to 1, the
less likely it is to be a spoof.
The score
value is based on passive facial information only, regardless of
whether or not the user said the expected digits or turned their head in the
correct direction. For example, a user who performs no action but is a real
person should receive a score close to 1.
HTTP/1.1 201 Created Content-Type: application/json { "created_at": "2019-12-11T10:06:38Z", "href": "/v3.6/reports/<REPORT_ID>", "id": "<REPORT_ID>", "name": "facial_similarity_video", "properties": {}, "result": "clear", "status": "complete", "sub_result": null, "breakdown": { "face_comparison": { "result": "clear", "breakdown": { "face_match": { "result": "clear", "properties": { "score": 0.6512, "document_id": "<DOCUMENT_ID>" } } } }, "image_integrity": { "result": "clear", "breakdown": { "face_detected": { "result": "clear", "properties": {} }, "source_integrity": { "result": "clear", "properties": {} } } }, "visual_authenticity": { "result": "clear", "breakdown": { "liveness_detected": { "result": "clear", "properties": {} }, "spoofing_detection": { "result": "clear", "properties": { "score": 0.9512 } } } } }, "check_id": "<CHECK_ID>", "documents": [] }
Facial Similarity Motion
In the Facial Similarity Motion report, motion captures are collected and uploaded by one of the Onfido SDKs (iOS, Android or JS).
Checks where applicant_provides_data
is true
are not
compatible with Facial Similarity 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 and document_id
unique identifier under the properties
bag (see Facial Similarity Motion: Face Match properties)
3: spoofing_detection
contains a score
value under the properties
bag (see Facial Similarity Motion: Spoofing Detection Score)
Facial Similarity Motion: Breakdowns
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 and document_id unique identifier for the matched document under the properties bag (see Facial Similarity Motion: Face Match properties). |
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 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 withreasons
- additional comma separated details, such as the name of the fake webcam
Facial Similarity Motion: Face Match Score
The face_match
breakdown contains a properties
object with a score
value and document_id
unique identifier.
The
score
value is a floating point number between 0 and 1 that expresses how similar the two faces are, where 1 is a perfect match.The score only measures how similar the faces are, and does not make an assessment of the nature of the motion capture. If spoofing (such as videos of digital screens, masks or print-outs) is detected the applicant will be rejected independently of the face match score.
document_id
returns the UUID for the document containing the extracted face that was used for face matching.If no face is detected, no document is recorded and the property is returned as
null
.
Facial Similarity Motion: Spoofing Detection Score
The spoofing_detection
breakdown contains a properties
object with a
score
value. This score is a floating point number between 0 and 1. The
closer the score is to 0, the more likely it is to be a spoof (i.e. videos of
digital screens, masks or print-outs). Conversely, the closer it is to 1, the
less likely it is to be a spoof.
The score
value is based on passive facial information only, regardless of
whether or not the user performed the head turn. For example, a user who performs
no action but is a real person should receive a score close to 1.
HTTP/1.1 201 Created Content-Type: application/json { "check_id": "<CHECK_ID>", "created_at": "2022-12-11T15:14:58Z", "documents": [ { "id": "<DOCUMENT_ID>" } ], "href": "/v3.6/reports/<REPORT_ID>", "id": "<REPORT_ID>", "name": "facial_similarity_motion", "properties": {}, "result": "clear", "status": "complete", "sub_result": null, "breakdown": { "face_comparison": { "result": "clear", "breakdown": { "face_match": { "result": "clear", "properties": { "score": 0.6512, "document_id": "<DOCUMENT_ID>" } } } }, "image_integrity": { "result": "clear", "breakdown": { "face_detected": { "result": "clear", "properties": {} }, "source_integrity": { "result": "clear", "properties": {} } } }, "visual_authenticity": { "result": "clear", "breakdown": { "liveness_detected": { "result": "clear", "properties": {} }, "spoofing_detection": { "result": "clear", "properties": { "score": 0.9512 } } } } } }
Suggested client actions
We host a guide on our Developer Hub for suggested client actions in specific scenarios for clients using our Facial Similarity reports.
Known Faces report
This API documentation offers detailed information about the structure of a Known Faces report, including an example of the report's result and its breakdowns.
For a more general introduction to the Known Faces report, you may wish to read our product documentation.
Creating a check with a Known Faces report will create a database of facial biometric identifiers (personal data) so that individuals can be identified in future checks. Always make sure you inform your users about this and obtain any necessary permissions. For more information on how Onfido uses personal data, view our Privacy Policy.
Each applicant you run a Known Faces report against must have an uploaded live photo, 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:
"properties":{ "reason": "Report withdrawn due to missing media (photo, video or motion capture) required for processing." }
You can run Known Faces as a standalone report, but we recommend that you combine it with a Document and Facial Similarity report in the same check.
No matches will be returned against any permanently deleted applicants.
To request a Known Faces report as part of a check in the API, use
the report_names
field (which takes an array of strings):
"report_names": ["known_faces"]
Required applicant data
For Known Face reports, first_name
and last_name
must be provided but can be dummy values if you don't know an applicant's name.
Known Faces: Object
The following table describes the unique fields returned in this version of the Onfido API for a completed Known Faces report:
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. Only matches where the suspected field is true will be considered. |
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: Properties
The Known Faces response will return any matching applicant IDs as entries
inside a matches
array under a properties
bag. Each applicant ID has a
corresponding score
and the media type (for example live_photos
,
live_videos
), as well as the corresponding UUID for that media type. For example, the live photo or live video ID.
Only matches where the suspected
field is true
should be considered as possible fraud. This
is determined by fuzzy matching the report's applicant name and matched applicants' names.
This can have a value of false
only if the fuzzy name matching feature for Known Faces reports is enabled in your account.
The score
attribute is a floating point number between 0 and 1 that expresses how
similar the two faces are, where 1 is a perfect match.
"matches": [ { "applicant_id": "NTH_MATCHED_APPLICANT_ID", "score": 0.9915, "media_id": "LIVE_PHOTO_ID", "media_type": "live_photos", "suspected": true } ]
If matches are found and any of them is suspected, the result will be consider
.
Conversely, if none of the matches are suspected, the result will be clear
.
HTTP/1.1 201 Created Content-Type: application/json { "created_at": "2020-06-19T09:44:14Z", "documents": [], "href": "/v3.6/reports/<REPORT_ID>", "id": "<REPORT_ID>", "name": "known_faces", "properties": { "matches": [ { "applicant_id": "<1ST_MATCHED_APPLICANT_ID>", "score": 1, "media_id": "<1ST_MEDIA_ID>", "media_type": "live_photos", "suspected": false }, { "applicant_id": "<2ND_MATCHED_APPLICANT_ID>", "score": 1, "media_id": "<2ND_MEDIA_ID>", "media_type": "live_videos", "suspected": true }, { "applicant_id": "<3RD_MATCHED_APPLICANT_ID>", "score": 0.8903, "media_id": "<3RD_MEDIA_ID>", "media_type": "live_photos", "suspected": false }, { "applicant_id": "<4TH_MATCHED_APPLICANT_ID>", "score": 0.8903, "media_id": "<4TH_MEDIA_ID>", "media_type": "live_photos", "suspected": false }, { "applicant_id": "<5TH_MATCHED_APPLICANT_ID>", "score": 0.8903, "media_id": "<5TH_MEDIA_ID>", "media_type": "motion", "suspected": false } ] }, "result": "consider", "status": "complete", "sub_result": null, "breakdown": { "previously_seen_faces": { "result": "consider" }, "image_integrity": { "result": "clear" } }, "check_id": "<CHECK_ID>" }
Identity Enhanced report
This API documentation offers detailed information about the structure of a Identity Enhanced report, including an example of the report's result and its breakdowns.
For a more general introduction to the Identity Enhanced report, you may wish to read our product documentation.
For verification checks containing Identity Enhanced reports, the applicant's last name must have at least 2 characters.
Required applicant data
For Identity Enhanced reports, the following applicant data must be provided:
first_name
last_name
dob
address.building_number
address.street
address.town
address.state
(state is mandatory in the US only. In some other countries, province or region may be required to access certain data sources)address.postcode
(ZIP code in US)address.country
(must be a 3-letter ISO code e.g. "GBR")id_numbers
(selected countries only, please check full list of supported countries with required and recommended data)phone_number
(selected countries only, please check full list of supported countries with required and recommended data)
The applicant address object is nested inside the applicant object. You must provide full address information in the request. The address field will not return a match if only address.postcode
is provided.
Alternatively, you can provide addresses in the form line1
, line2
and line3
. If you provide address data in this form, Onfido uses a third-party subprocessor for address cleansing.
For more details, you can review the full list of supported countries with required and recommended data.
If you don't provide date of birth or address information in the request, a consider
response with no breakdown information is returned. This is an invalid response and should be interpreted as a failed report.
Supported countries for Identity Enhanced
You can review the full list of supported countries for Identity Enhanced reports.
This is not a list of documents that Onfido supports: you can review that list separately.
Identity Enhanced: Report object
The report object varies depending on the applicant's address country
field.
United Kingdom
Example report object where the applicant's address is in the United Kingdom.
Sources (credit_agencies
, voting_register
, telephone_database
) are displayed as breakdowns with their own result
value.
HTTP/1.1 201 Created Content-Type: application/json { "created_at": "2019-10-03T15:54:20Z", "href": "/v3.6/reports/<REPORT_ID>", "id": "<REPORT_ID>", "name": "identity_enhanced", "properties": { "matched_address": 19099121, "matched_addresses": [ { "id": 19099121, "match_types": [ "credit_agencies", "voting_register" ] } ] }, "result": "clear", "status": "complete", "sub_result": null, "breakdown": { "sources": { "result": "clear", "breakdown": { "total_sources": { "result": "clear", "properties": { "total_number_of_sources": "3" } } } }, "address": { "result": "clear", "breakdown": { "credit_agencies": { "result": "clear", "properties": { "number_of_matches": "1" } }, "telephone_database": { "result": "clear", "properties": {} }, "voting_register": { "result": "clear", "properties": {} } } }, "date_of_birth": { "result": "clear", "breakdown": { "credit_agencies": { "result": "clear", "properties": {} }, "voting_register": { "result": "clear", "properties": {} } } }, "mortality": { "result": "clear" } }, "check_id": "<CHECK_ID>", "documents": [] }
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.
HTTP/1.1 201 Created Content-Type: application/json { "check_id": "<CHECK_ID>", "created_at": "2022-05-06T08:44:54Z", "documents": [], "href": "/v3.6/reports/<REPORT_ID>", "id": "<REPORT_ID>", "name": "identity_enhanced", "properties": {}, "result": "clear", "status": "complete", "sub_result": null, "breakdown": { "date_of_birth": { "result": "clear", "breakdown": { "date_of_birth_matched": { "result": "clear", "properties": { "sources": "Credit Agencies" } } } }, "address": { "result": "clear", "breakdown": { "address_matched": { "result": "clear", "properties": { "sources": "Credit Agencies, Telephone Database" } } } }, "ssn": { "result": "clear", "breakdown": { "last_4_digits_match": { "result": "clear", "properties": {} }, "full_match": { "result": "clear", "properties": {} } } } }
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
.
The report includes national_id_number_matched
for a non UK or non US applicant as an additional match under the national_id_number
breakdown. This breakdown will not be returned if a National ID Number is not provided or unsupported for the applicant's country.
HTTP/1.1 201 Created Content-Type: application/json { "check_id": "<CHECK_ID>", "created_at": "2022-05-06T08:44:54Z", "documents": [], "href": "/v3.6/reports/<REPORT_ID>", "id": "<REPORT_ID>", "name": "identity_enhanced", "properties": {}, "result": "clear", "status": "complete", "sub_result": null, "breakdown": { "date_of_birth": { "result": "clear", "breakdown": { "date_of_birth_matched": { "result": "clear", "properties": { "sources": "Credit Agencies" } } } }, "address": { "result": "clear", "breakdown": { "address_matched": { "result": "clear", "properties": { "sources": "Credit Agencies, Telephone Database" } } } }, "national_id_number": { "result": "clear", "breakdown": { "national_id_number_matched": { "result": "clear", "properties": { "sources": "Government", "type": "Identity Card" } } } } } }
Identity Enhanced report custom logic
We've moved this content.
Watchlist reports
This API documentation offers detailed information about the structure of a Watchlist report, including an example of the report's result and its breakdowns.
For a more general introduction to the Watchlist report, you may wish to 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
.
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)
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.
Date of birth
Submitting a date_of_birth
with the name is optional but recommended, to narrow the search of the relevant individual.
More than one date of birth might be found per match due to the nature of the data sources, such as newspaper articles, which might include someone's age but not their full date of birth.
Address
Submitting an address
with the name is also optional but recommended. This will narrow the search to the country specified in the address, for all politically_exposed_person
and adverse_media
breakdown matches except Money Laundering and Terrorist related matches. This will not filter sanction
breakdown matches.
If a match is found with either Sanctions, Money Laundering or Terrorist related events, all the other events of that match will be returned, even if the other events are not related to the country specified in the address.
If a match is found but the date_of_birth
or address
fields are null
, this means there is no date_of_birth
or address
data on file associated with that match.
HTTP/1.1 201 Created Content-Type: application/json { "created_at": "2019-10-03T15:42:36Z", "href": "/v3.6/reports/<REPORT_ID>", "documents": [], "id": "<REPORT_ID>", "name": "watchlist_aml", "properties": { "records": [] }, "result": "clear", "status": "complete", "sub_result": null, "breakdown": { "sanction": { "result": "clear" }, "politically_exposed_person": { "result": "clear" }, "legal_and_regulatory_warnings": { "result": "clear" }, "adverse_media": { "result": "clear" } }, "check_id": "<CHECK_ID>" }
Watchlist Enhanced
The Watchlist Enhanced report provides a granular breakdown of any records found when screening global watchlists. These include the following breakdowns:
sanction
: Government and International Organisations Sanctions Lists.politically_exposed_person
: Proprietary database of Politically Exposed Persons sourced from government lists, websites and other media sources.monitored_lists
: Law-Enforcement and Regulatory bodies Monitored Lists (including Terrorism, Money Laundering and Most Wanted lists).adverse_media
: Negative events reported by publicly and generally available media sources.
Records
If no match is found against the subject, the records
field will read []
and the overall result
will be clear
.
If one or more matches are found, each match will be returned under records
and the overall result
will be consider
. Each event will correspond to a relevant category of list, which drives one of the breakdowns.
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)
The applicant address object is nested inside the applicant object. If you create an applicant object with an address, you must provide postcode and country, and state for US addresses.
Date of birth
Submitting a date_of_birth
with the name is optional but recommended, to narrow the search of the relevant individual.
More than one date of birth might be found per match due to the nature of the data sources, such as newspaper articles, which might include someone's age but not their full date of birth.
Address
Submitting an address
with the name is also optional but recommended. This will narrow the search to the country specified in the address, for all politically_exposed_person
and adverse_media
breakdown matches except Money Laundering and Terrorist related matches. This will not filter sanction
breakdown matches.
If a match is found with either Sanctions, Money Laundering or Terrorist related events, all the other events of that match will be returned, even if the other events are not related to the country specified in the address.
If a match is found but the date_of_birth
or address
fields are null
, this means there is no date_of_birth
or address
data on file associated with that match.
HTTP/1.1 201 Created Content-Type: application/json { "created_at": "2019-10-03T15:37:03Z", "href": "/v3.6/reports/<REPORT_ID>", "id": "<REPORT_ID>", "name": "watchlist_enhanced", "properties": { "records": [] }, "result": "clear", "status": "complete", "sub_result": null, "breakdown": { "politically_exposed_person": { "result": "clear" }, "sanction": { "result": "clear" }, "adverse_media": { "result": "clear" }, "monitored_lists": { "result": "clear" } }, "check_id": "<CHECK_ID>", "documents": [] }
Watchlist Standard
The Watchlist Standard report provides a granular breakdown of any records found when screening global watchlists. These include:
sanction
: Government and International Organisations Sanctions Lists.politically_exposed_person
: Proprietary database of Politically Exposed Persons sourced from government lists, websites and other media sources.legal_and_regulatory_warnings
: Law-Enforcement and Regulatory bodies Monitored Lists (including Terrorism, Money Laundering and Most Wanted lists).
You can use a Watchlist PEPs Only report to search only PEPs lists, or a Watchlist Sanctions Only report to search only sanctions and warnings lists. The Watchlist Standard report will search all types.
Records
If no match is found against the subject, the records
field will read []
and the overall result
will be clear
.
If one or more matches are found, each match will be returned under records
and the overall result
will be consider
.
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.
HTTP/1.1 201 Created Content-Type: application/json { "created_at": "2019-10-03T15:42:36Z", "href": "/v3.6/reports/<REPORT_ID>", "id": "<REPORT_ID>", "name": "watchlist_standard", "properties": { "records": [] }, "result": "clear", "status": "complete", "sub_result": null, "breakdown": { "sanction": { "result": "clear" }, "politically_exposed_person": { "result": "clear" }, "legal_and_regulatory_warnings": { "result": "clear" } }, "check_id": "<CHECK_ID>", "documents": [] }
Watchlist PEPs Only
The Watchlist PEPs Only report is a subset of the Watchlist Standard report. It provides a granular breakdown of politically_exposed_person
breakdown matches.
Each match will be returned under records
and includes, but is not limited
to: name of match, associates, date of birth, related keywords, type of list,
name of list, and when the entry was last updated. When available, URLs to
data sources are provided, as well as pictures of the individual found in the
match. This allows you to quickly assess the relevancy of the match and
eliminate false positives. See Watchlist 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 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.
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 API documentation offers detailed information about the structure of a Proof of Address report, including an example of the report's result and its breakdowns.
For a more general introduction to the Proof of Address report, you may wish to read our product documentation.
Supported issuing countries
Documents issued by the following countries are supported for a PoA report:
- Group A:
- United Kingdom
- Isle of Man
- Jersey
- Gibraltar
- San Marino
- Andorra
- Switzerland
- Monaco
- Group B:
- European Economic Area (excluding Greece, Cyprus and Bulgaria)
- Canada
- New Zealand
- Group C:
- United States of America
- Australia
- Hong Kong
- Singapore
- Philippines
- Indonesia
- Vietnam
- Mexico
- Brazil
- Colombia
- Argentina
- Ghana
- Ivory Coast
- Kenya
- Nigeria
- Senegal
- South Africa
- Tanzania
- Uganda
- Turkey
- United Arab Emirates
- Malaysia
- Ukraine
- Kuwait
- Saudi Arabia
- Algeria
- Ethiopia
- Bermuda
- Guatemala
- Panama
- British Virgin Islands
You must set the issuing_country
field to the corresponding country 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 a supported country 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, along with its issue date validity based on document issuing country:
Document | API Document type | Group A | Group B | Group C |
---|---|---|---|---|
Bank Statement or Building Society Statement | bank_building_society_statement | Last 3 months | Last 6 months | Last 3 months |
Utility Bill (electricity, water, gas, broadband, landline ) | utility_bill | Last 3 months | Last 6 months | Last 3 months |
Council Tax letter | council_tax | Last 1 year | Last 6 months | |
Benefits Letter (e.g. Job seeker allowance, House benefits, Tax credits) | benefit_letters | Last 1 year | Last 6 months | |
Mortgage statement | mortgage_statement | Last 1 year | Last 1 year | |
Mobile phone bill | mobile_phone_bill | Last 6 months | ||
General letter (financial institution/utility company) | general_letter | Last 6 months | ||
Insurance statement or brokerage statement | insurance_statement | Last 6 months | ||
Pension statement/letter or Property tax statement/letter | pension_property_statement_letter | Last 1 year | ||
Identity document with address | identity_document_with_address | Must not be expired | Must not be expired | |
Exchange House Statement | exchange_house_statement | Last 6 months |
Council Tax and Benefits Letter are only supported if issued by the UK.
Address certificates (address_certificate
) are only supported if issued in Hungary and Turkey. If dates are present, address certificates must not be expired.
When uploading documents with 2 sides (e.g. identity_document_with_address
), document_type
should be specified and both sides of the document should be uploaded as separate documents, specifying side
value for each one.
Exchange House Statements are only supported if provided from authorized issuers in the United Arab Emirates.
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 and the document has a valid date of issue |
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 |
document_source_type | This property provides the document source type |
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 |
address_parsed | object This property provides a structured address |
unsupported_document_reason | array The reasons why the document is unsupported (possible values include unsupported_doc_type , unsupported_alphabet or unsupported_country ). |
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.
Document source types
The following document source types can be returned for a PoA report:
Source type | Description |
---|---|
pdf | Document is a PDF file |
photo_of_screen | Document is a photo of a monitor, phone, tablet etc. that was taken using another device |
screenshot | Document is an image taken using the native screenshot function on a device |
paper_document | Document is a picture of the paper document |
Proof of Address: Overall Result Logic
We've moved this content.
HTTP/1.1 201 Created Content-Type: application/json { "created_at":"2021-04-27T14:51:35Z", "documents":[], "href":"/v3.6/reports/<REPORT_ID>", "id":"<REPORT_ID>", "name":"proof_of_address", "properties":{ "document_type":"council_tax", "document_source_type": "pdf", "issuer":"city of london", "issue_date":"2020-01-01", "first_names":"John", "last_names":"Smith", "address":"123 sample street london xyz 1ab gbr", "address_parsed":{ "country":"gbr", "postcode":"1ab gbr", "state":null, "town":"london" }, "unsupported_document_reason": [ "unsupported_doc_type", "unsupported_alphabet", "unsupported_country" ] }, "result":"clear", "status":"complete", "sub_result":null, "breakdown":{ "image_integrity":{ "result":"clear", "breakdown":{ "image_quality":{ "result":"clear", "properties":{} } } }, "document_classification":{ "result":"clear", "breakdown":{ "supported_document":{ "result":"clear", "properties":{} }, "valid_document_date":{ "result":"clear", "properties":{} } } }, "data_comparison":{ "result":"clear", "breakdown":{ "first_name":{ "result":"clear", "properties":{} }, "last_name":{ "result":"clear", "properties":{} }, "address":{ "result":"clear", "properties":{} } } }, "source_integrity": { "result": "clear", "breakdown": { "digital_tampering": { "result": "clear", "properties": {} }, "visible_fraud": { "result": "clear", "properties": {} } } } }, "check_id":"<CHECK_ID>" }
Driver's License Data Verification report
This API documentation offers detailed information about the structure of a Driver's License Data Verification (DLDV) report, including an example of the report's result and its breakdowns.
For a more general introduction to the DLDV report, you may wish to 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).
... "report_names": ["us_driving_licence"], "us_driving_licence":{ "id_number": "<DRIVER_LICENCE_ID>", // required "issue_state": "<TWO_LETTER_STATE_CODE>", // required ... // all other optional fields } ...
See optional document data for a table of the accepted optional fields in the us_driving_licence
object for a DLDV report.
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
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. Fuzzy matching allows capturing data variations.
DLDV: Breakdowns
Breakdowns can have a clear
or consider
result. Breakdowns will only have a clear
result when all included sub-breakdowns are clear
.
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 |
HTTP/1.1 201 Created Content-Type: application/json { "created_at": "2021-03-26T19:51:37Z", "documents": [], "href": "/v3.6/reports/<REPORT_ID>", "id": "<REPORT_ID>", "name": "us_driving_licence", "properties": {}, "result": "clear", "status": "complete", "sub_result": null, "breakdown": { "document": { "result": "clear", "breakdown": { "category": { "result": "clear", "properties": {} }, "expiration_date": { "result": "clear", "properties": {} }, "issue_date": { "result": "clear", "properties": {} }, "document_number": { "result": "clear", "properties": {} } } }, "address": { "result": "clear", "breakdown": { "city": { "result": "clear", "properties": {} }, "line_1": { "result": "clear", "properties": {} }, "line_2": { "result": "clear", "properties": {} }, "state_code": { "result": "clear", "properties": {} }, "zip4": { "result": "clear", "properties": {} }, "zip5": { "result": "clear", "properties": {} } } }, "personal": { "result": "clear", "breakdown": { "first_name": { "result": "clear", "properties": {} }, "name_suffix": { "result": "clear", "properties": {} }, "height": { "result": "clear", "properties": {} }, "weight": { "result": "clear", "properties": {} }, "sex_code": { "result": "clear", "properties": {} }, "eye_color": { "result": "clear", "properties": {} }, "date_of_birth": { "result": "clear", "properties": {} }, "last_name": { "result": "clear", "properties": {} }, "middle_name": { "result": "clear", "properties": {} }, "first_name_fuzzy": { "result": "clear", "properties": {} }, "middle_name_fuzzy": { "result": "clear", "properties": {} }, "last_name_fuzzy": { "result": "clear", "properties": {} }, "middle_initial": { "result": "clear", "properties": {} } } } }, "check_id": "<CHECK_ID>" }
Device Intelligence report
This API documentation offers detailed information about the structure of a Device Intelligence report, including an example of the report's result and its breakdowns.
For a more general introduction to the Device Intelligence report, you may wish to read our product documentation.
Device Intelligence is only available via the Onfido SDKs, not via the API directly.
You can run Device Intelligence as a standalone report, but we recommend that you combine it with a Document or Facial Similarity report in the same check.
Required applicant data
For Device Intelligence reports, the following applicant data must be provided:
first_name
andlast_name
- a document or biometric media upload via the Onfido SDKs
Raw signals collected
Signal grouping | Category | Description |
---|---|---|
Onfido check data | User | Onfido operational data required for Onfido Services: Onfido User unique identifier, check status/outcome and related tracking information, inferences and outputs from Device Intelligence (e.g. risk score, risk level.) |
User data | User | Document number and other data extracted from any associated doc and bio check. |
IP address information | IP | IP address and IP address type, including associated geo-location city/region/country level location and detection of any IP masking tools such as a VPN or Proxy. |
Device fingerprint | Device | Device identifiers including audio and video fingerprint, canvas and WebGL fingerprinting. |
Media uploaded by user | Media | Media itself, as well as any related metadata, like complete EXIF extraction and other embedded metatags in media itself. |
Camera | Device | Capture of camera feed and information like: camera name, microphone name, aspect ratio, resolution, frame rate, etc. |
Device metadata & browser headers | Device | Information about Users' device including hardware and software attributes (e.g. device type and model, manufacturer, operating system type and version (e.g. iOS or Android), browser type and version, user-agent, navigator, screen details, plugins, fonts, memory, WebGL, battery information, language, timezone, camera name, microphone name, aspect ratio, resolution, frame rate, etc.) |
Onfido Device ID | Device | Unique identifier stored by Onfido in the device and used to verify re-use of the device. |
End user interactions | Usage data | Information about an end user’s interactions with the Services, including how the end user uses the Services such as date and time stamps, forms/fields completed, pointer and touch events, timezone offset, distraction events. |
Application Authenticity | Device | Operational data related to verification flow, used to check whether the device is using stolen security tokens. |
Available for SDK versions iOS 22.4.0 +; Android 9.2.0 +; Web 5.10.0 +
Device Intelligence: Results
The result
field indicates the overall report result.
Possible values for Device Intelligence reports are clear
and consider
:
Report result | Description |
---|---|
clear | The applicant used a valid device and is not associated with suspicious behaviour, indicating they are a genuine user. |
consider | The applicant was detected to have used an invalid device or is associated with suspicious behaviour, indicating they may be a fraudulent user. |
In addition, any additional data and signals are returned in the properties
attribute.
Device Intelligence: Breakdowns
Breakdowns can have a clear
or consider
result.
Breakdown | description |
---|---|
device | object Asserts whether the device used to upload the media is trustworthy, i.e. it is a real, physical device. |
(sub-breakdown) application_authenticity | object Contains fake_network_request under the properties bag (see Device Intelligence: Application Authenticity properties). |
(sub-breakdown) device_integrity | object Contains randomized_device , emulator , single_device_used , document_capture and biometric_capture under the properties bag (see Device Intelligence: Device Integrity properties). |
(sub-breakdown) device_reputation | object Contains ip_reputation and device_fingerprint_reuse under the properties bag (see Device Intelligence: Device Reputation properties) |
Device Intelligence: Application Authenticity properties
We will return a reason whenever a report flags for application_authenticity
. The property will be returned as true
and the sub-breakdown will have a consider
result.
fake_network_request
- when the device used stolen security tokens to send the network information
Device Intelligence: Device Integrity properties
We will return a reason whenever a report flags for device_integrity
. There can be more than one reason, because they aren't mutually exclusive.
randomized_device
- when the device provided false randomized device and network information. The property will be returned astrue
and the sub-breakdown will have aconsider
result.emulator
- when evidence is found that an emulator was used. The property will be returned astrue
and the sub-breakdown will have aconsider
result.(For opted in customers only)
single_device_used
- when the associated document and biometric media weren't uploaded from the same device. The property will be returned asfalse
and the sub-breakdown will have aconsider
result.(For opted in customers only)
document_capture
- when the associated document media weren't confirmed to be live captured from the device camera. The property will not be returned aslive
and the sub-breakdown will have aconsider
result.(For opted in customers only)
biometric_capture
- when the associated biometric media weren't confirmed to be live captured from the device camera. The property will not be returned aslive
and the sub-breakdown will have aconsider
result.
Device Intelligence: Device Reputation properties
We will return a reason whenever a report flags for device_reputation
. There can be more than one reason, because they aren't mutually exclusive.
ip_reputation
- when there is highly suspicious traffic related to the IP address, the sub-breakdown will have aconsider
result.device_fingerprint_reuse
- when the same fingerprint was reused too many times, the sub-breakdown will have aconsider
result.
Device Intelligence: Properties
Data and signals collected about the device, IP, and geolocation are returned in the properties
attribute.
Note: All properties can take the value null
in addition to their corresponding list of possible values.
device
object:
Field | Description | Possible values |
---|---|---|
sdk_version | string The SDK version that was used. | - |
sdk_source | string The SDK used to upload the media. | onfido-android-sdk, onfido-ios-sdk, onfido-web-sdk |
authentication_type | string The token used to authenticate the request. | sdk_token, mobile_token, api_token |
raw_model | string The model as set by the phone manufacturer (for Android and iOS) or the browser manufacturer (for Web). The model can be presented in name or number form depending on each manufacturer implementation. | - |
os | string The operating system of the device. The value came from manufacturer implementation (for Android and iOS) or browser's user agent (for Web). | - |
browser | string (Web specific field) The browser name reported by the browser's user agent. | - |
emulator | boolean Whether the device is an emulator. | true, false |
randomized_device | boolean Whether the device is providing false randomized device and network information. | true, false |
fake_network_request | boolean Whether device is using stolen security tokens to send the network information. | true, false |
true_os | string (deprecated field) The true operating system of the device. Note: This deprecated field is always null . | - |
os_anomaly | string (deprecated field) The likelihood of an operating system anomaly between the true OS and the OS sent by the device. Note: This deprecated field is always null . | high, medium, low |
rooted | boolean (deprecated field) Whether the device is rooted. Note: This deprecated field is always null . | true, false |
remote_software | boolean (deprecated field) Whether the device is controlled via remote software. Note: This deprecated field is always null . | true, false |
ip_reputation | string Whether there is highly suspicious traffic related to the IP address. The risk depends on the overall ratio of clear checks on a given IP. In case the IP is not highly reused we return NOT_ENOUGH_DATA . | NOT_ENOUGH_DATA, HIGH_RISK, LOW_RISK |
device_fingerprint_reuse | integer The number of times the device was used to create a report for a new applicant. A value greater than 1 indicates potential device reuse. | - |
single_device_used | null and boolean Whether the document or biometric media were uploaded from a single device. | null, true, false |
document_capture | string Whether the document media were live captured from the device camera. | live, unknown_method |
biometric_capture | string Whether the biometric media were live captured from the device camera. | live, unknown_method |
ip
object:
Field | Description | Possible values |
---|---|---|
address | string The IP address that uploaded the media. | - |
vpn_detection | string (deprecated field) The likelihood of the network connection being a VPN. Note: This deprecated field is always null . | high, medium, low |
proxy_detection | string (deprecated field) The likelihood of the network connection being a Proxy. Note: This deprecated field is always null . | high, medium, low |
type | string (deprecated field) The type of organization that owns this IP address. Note: This deprecated field is always null . | - |
geolocation
object:
Field | Description | Possible values |
---|---|---|
city | string City location of the IP address. | - |
region | string Region location of the IP address. | - |
country | string Country location of the IP address in a three letter format. | - |
HTTP/1.1 201 Created Content-Type: application/json { "created_at": "2021-03-26T19:51:37Z", "documents": [], "href": "/v3.6/reports/<REPORT_ID>", "id": "<REPORT_ID>", "name": "device_intelligence", "result": "clear", "status": "complete", "sub_result": null, "breakdown": { "device": { "breakdown": { "application_authenticity": { "properties": {}, "result": "clear" }, "device_integrity": { "properties": {}, "result": "clear" }, "device_reputation": { "properties": {}, "result": "clear" } }, "result": "clear" } }, "check_id": "<CHECK_ID>", "properties": { "device": { "authentication_type": "sdk_token", "sdk_source": "onfido-android-sdk", "sdk_version": "10.3.1", "raw_model": "SM-G900P", "os": "Android", "browser": null, "emulator": false, "randomized_device": false, "fake_network_request": false, "true_os": null, "os_anomaly": null, "rooted": null, "remote_software": null, "device_fingerprint_reuse": 3, "single_device_used": null, "document_capture": "unknown_method", "biometric_capture": "live" }, "ip": { "address": "127.0.0.1",