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(s)	Description
Age validation	Minimum accepted age	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 default minimum age is 16 years old but you can request to have this changed.
Data comparison	Date of birth	Indicates whether the information points extracted from the document match the information supplied when creating an applicant through the API.
	Last name
	First name
Data validation	Date of birth	Determines whether the data point is the expected length and format for this document type.
	Document numbers
	Machine Readable Zone (MRZ)
	Gender
	Expiry date
	Document expiration	Validates the expiry date extracted from a document, flagging if a document's expiry date has passed.
	Barcode	Validates the barcode against the defined standard for this document type. (Only available in v3.2 onwards)
Image integrity	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 (Machine Readable Zone) 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	Date of expiry	Indicates whether data that appears in multiple places on the document, for example in the MRZ and printed on the front, is consistent in both places.
	Document type
	Nationality
	Issuing country
	Document numbers
	Gender
	First name
	Last name
	Date of birth
	Multiple data sources present	Acts as a validation for the `data_consistency` breakdown: if 2 sources are present, then data comparison is possible. (Only available in v3.1 onwards)
Visual authenticity	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 security features expected on the document are missing or wrong and are suspected to be tampered with digitally.
	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	Flags when other sub-breakdowns under visual authenticity are flagged. Returned for backwards compatibility.
Compromised document	Document Database	Asserts whether the document is publicly available as compromised
Compromised document	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	NFC Passive Authentication	Asserts whether the document's NFC chip data was tampered with. (Only available in v3.2 onwards)
Issuing Authority	NFC Active Authentication	Asserts whether the document's NFC chip is original or cloned. (Only available in 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 wish 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. If you wish 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.