Document report

Start here

This guide presents a technical overview of Onfido's Document report.

Introduction

The Document report employs data integrity, visual authenticity and database record checks to verify identity documents such as passports, national ID cards and driver's licences. The report can also compare the data extracted from the document with data provided by the end user in other capture tasks or in the workflow input data, as an additional way of identifying potential discrepancies and fraudulent documents.

The majority of Document reports are automated and processed in seconds. If, however, Onfido encounters document images that use sophisticated counterfeiting techniques, or the capture is of poor quality (blurred, low resolution, obscured, cropped, or held at an unreadable angle), our software is supported by an expert manual review team to ensure an identity verification is subject to a thorough analysis in order to maximise fraud detection. Manual review can also be configured to be applied to all document verifications.

When document analysis falls back to manual review, the report results will be delivered asynchronously via webhook notifications. You can read more about webhooks in our API reference documentation.

During document capture, the Document report uses Near Field Communication (NFC) to validate the document's chip in order to verify the document. If NFC was successful, the visual authentication, image integrity and data consistency checks will not be performed. In addition, any data extracted from the document is returned in the properties attribute of the report. Please read our NFC for Document report guide for details on how to integrate and use NFC for Document reports.

The Document report breakdown tree

The results of Document reports are generated in the form of breakdowns and sub-breakdowns. A Document report can have an overall result of clear or consider.

The Document report uses the sub_result property to provide a more specific description of the overall report result. These sub-results and their meanings are described in the table below:

Sub-result
Clear	If all underlying verifications pass.
Rejected	If the report has returned information where the check cannot be processed further (for example, poor image quality or unsupported document).
Suspected	The analysed document is suspected to be fraudulent.
Caution	If any other underlying verifications fail, but they don't necessarily point to a fraudulent document (for example, the name provided by the applicant doesn't match the one on the document).

Breakdowns are made up of sub-breakdowns. A breakdown will have a consider result when at least one of its sub-breakdowns contains a consider or unidentified result.

Breakdowns and sub-breakdowns are mapped to particular sub-results. Certain mappings can be changed, depending on your configuration. You can use the Document report breakdown tree diagram below to understand the mapping of different sub-breakdowns and breakdowns to a sub-result, and the options for configuration. You can also read how individual breakdowns contribute to the overall sub_result value in the Document report in our API reference documentation.

Note: The following diagram illustrates the options available in v2 and v3 of the Onfido API.

Document report breakdown tree 1

The following diagram shows the reasons which can lead to specific sub-breakdowns and therefore sub-results other than clear in v2 and v3 of the Onfido API:

Document report breakdown tree 2

More details regarding the structure of the Document report and an example result can be found in our API reference documentation.

For how to proceed with an applicant based on the various results, please refer to the suggested client actions section below.

Breakdown descriptions

Breakdown	Sub-breakdown	Description
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 age is 16 years old, but you can request to have this changed.
	Minimum accepted age	The minimum accepted age, configureable at account level.
Data comparison		Establishes whether the information points extracted from the document match the information supplied when creating an applicant through the API.
	Date of birth	A comparison of the document's `date_of_birth` field.
	First name	A comparison of the document's `first_name` field.
	Last name	A comparison of the document's `last_name` field.
	Gender	A comparison of the document's `gender` field.
Data validation		Asserts whether the format and length of the fields are correct for the document type.
	Gender	Determines whether the document's `gender` field is the expected length and format for this document type.
	Date of birth	Determines whether the document's `date_of_birth` field is the expected length and format for this document type.
	Document numbers	Determines whether the `document_numbers` field is the expected length and format for this document type.
	Document expiration	Validates the expiry date extracted from a document, flagging if a document's expiry date has passed.
	Expiry date	Validates whether the expiration date has the incorrect format, or whether the date is in the past.
	Machine Readable Zone (MRZ)	A validation of the document's `mrz`.
	Barcode	Validates the `barcode` against the defined standard for this document type (only available from API v3.2 onwards).
Image integrity		Asserts whether the document is of sufficient quality to verify.
	Conclusive document quality	Measures the ability to make a fraud assessment based on the quality of the applicant's document. Applied by our expert manual review team when documents are unclassifiable as fraudulent or genuine.
	Colour picture	Flags if the image is black and white. This is because black and white documents prevent a full fraud assessment as the majority of security features are colour.
	Image quality	Flags if there is a low-resolution image where the document information is not readable, the MRZ is obscured or unreadable or vital data points are obscured or unreadable.
	Supported document	Indicates whether the submitted document type is supported by Onfido and by the customer, or whether the document is issued by a country subject to comprehensive US sanctions.
	Video document presence	Asserts whether there is at least a document with video and none of the documents has a video whose signature was checked and is invalid.
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.
	Date of expiry	Asserts the consistency of the data in the document's `date_of_expiry` field.
	Document type	Asserts the consistency of the document type.
	Nationality	Asserts the consistency of the data in the document's `nationality` field.
	Issuing country	Asserts the consistency of the data in the document's `issuing_country` field.
	Document numbers	Asserts the consistency of the `document_numbers` field.
	Gender	Asserts the consistency of the data in the document's `gender` field.
	First name	Asserts the consistency of the data in the document's `first_name` field.
	Last name	Asserts the consistency of the data in the document's `last_name` field.
	Date of birth	Asserts the consistency of the data in the document's `date_of_birth` field.
	Multiple data sources present	`multiple_data_sources_present` is for cases where we don't obtain a US barcode because it wasn't extracted, wasn't decoded, or wasn't there at all (e.g. if the back of the document wasn't available). It acts as a validation for the `data_consistency` breakdown: if 2 sources are present, then data consistency is possible and the other sub-breakdowns are enabled. `multiple_data_sources_present` can be disabled if needed. In this case, it will be returned as null and have no impact on the sub-result.
Visual authenticity		Asserts whether visual (non-textual) elements are correct given the document type.
	Face detection	Indicates whether a face was detected on the document.
	Original Document Present (ODP)	Indicates whether the provided image is an image of the original document or, for example, a photo of a photo of a document or a photo of a computer screen.
	Fonts	Indicates whether fonts in the document match the expected ones.
	Picture face integrity	Flags if the pictures of the person identified on the document show signs of tampering or alteration.
	Digital tampering	Flags when the image of the document is suspected to have been digitally tampered with.
	Security features	Flags if security features expected on the document are missing or wrong.
	Template	Indicates whether the document matched the expected template for the document type and country it is from.
	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`.
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.
Police record		Indicates whether a document has been reported as lost, stolen or compromised to the UK Metropolitan Police.
Issuing Authority		Asserts whether data on the document matches the issuing authority data.
	NFC passive authentication	Asserts whether the document's NFC chip data was tampered with (only available from API v3.2 onwards).
	NFC active authentication	Asserts whether the document's NFC chip is original or cloned (only available from API v3.2 onwards).

Document Report task

Similar to other Onfido reports, to run a Document report, a Document Report task should be added to a Studio workflow from the Workflow Builder.

When constructing a Studio workflow, a Document Report task must always follow the route of a Document Capture task in order to extract the appropriate input data. Input data for this task can also be received from the workflow input data, an Autofill task or a Profile Data Capture task.

Below you will find an illustrated example of a Studio workflow running a Document report:

Document report workflow

More information about report tasks can be found in our Studio Product Guide.

Document Report task results

If you want to obtain the specific outputs from the Document Report task via the Onfido API (for example, the overall report result or breakdown results), you can manage this by configuring the Workflow Output in the Studio Workflow Builder. You can also retrieve all associated output data from a Document report.

You can refer to our Studio product guide for more information on Workflow Output configuration. Once set up, the output can be consumed by making a Retrieve Workflow Run call to the Onfido API. Report results are found in the output property.

Workflow Run results can also be accessed on the "Results" tab of your Studio Dashboard.

Suggested client actions

In this section, we explore a range of specific scenarios for the Document Report by examining individual sub_results from the report breakdown and describe some common suggested actions.

The details of the Document Report breakdown structure are described above in this guide, and are also documented in our API reference.

The following scenarios are provided as examples, and are based on default configurations. Where breakdowns can be configured to map to alternative sub_results, this is noted. To discuss such configuration changes, please ask your contact at Onfido or email our Client Support team.

'rejected' sub_result scenarios

Potential contributing breakdown and sub-breakdown(s)	Potential client action(s)
`image_integrity`: `supported_document`	Verify that the document is supported.

You can review the full list of documents Onfido supports.

Potential contributing breakdown and sub-breakdown(s)	Potential client action(s)
`image_integrity`: `image_quality`	Request an additional image of the same document

The most common reason for a document to be deemed “unprocessable”, is the fact that key data points might be obstructed, cropped, or not visible. Such documents are rejected for poor image quality.

Potential contributing breakdown and sub-breakdown(s)	Potential client action(s)
`age_validation`: `minimum_accepted_age`	Block

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

'suspected' sub_result scenarios

Potential contributing breakdown and sub-breakdown(s)	Potential client action(s)
`visual_authenticity`: `original_document_present` (can be configured to map to `caution` sub-result)	a. Ignore b. Refer to manual team for review c. Request an additional document

Onfido deploys a number of texture analysis algorithms to detect whether or not an image contains any of the following:

screenshots
pictures of pictures
printouts

Original document scanning presents a difficult challenge that in our experience is best solved via the combination of tech and human expertise. If our algorithms fail to produce a result beyond a certain degree of certainty, documents will be referred to manual analysts to supplement the engine's decision.

Potential contributing breakdown and sub-breakdown(s)	Potential client action(s)
`visual_authenticity`: `picture_face_integrity`	a. Block b. Refer to manual team for review

Onfido deploys a number of algorithms designed to analyse whether the picture in a document image may be a physical insertion or otherwise digitally tampered.