Configuring Onfido v1 and 2
Note
Passfort supports Onfido Classic. Onfido Studio is not yet supported.
Onfido is a data provider you can use to run these checks:
Electronic identity check
ID verification (Passfort collects documents)
ID verification (service collects documents)
Passfort also supports Onfido v1 and v2, however, we recommend that you migrate to Onfido v3 as soon as possible in order to take advantage of the additional features that v3 brings. These include:
Additional configuration options
Improved MRZ verification
Learn more about configuring Onfido v3.
Electronic identity check
How it works
This is the default behavior for a variant of the Electronic identity check with Onfido as the data provider.
The check is performed by searching for the individual’s details (name, date of birth, address, and, in some cases, national identity number) in the sources supplied by Onfido.
The check passes when a 2+2 result is achieved, which happens when either of these conditions are true:
The individual’s full name and address are matched in one source. and the individual’s full name and are matched in a second source.
The individual’s full name and address are matched in two distinct sources.
If a 2+2 result cannot be achieved, the check looks for a 1+1 result.
The check returns a partial match when a 1+1 result is achieved, which happens when either of these conditions are true:
The individual’s full name, date of birth, and address are matched in one source.
The individual’s full name and address are matched in one source.
If the conditions are not met for a 2+2 result or a 1+1 result, the check fails.
If the individual’s profile doesn’t have data for the required fields, an error is displayed.
If the country of address in the individual’s profile isn’t covered by Onfido, an error is displayed.
Although the individual's national identity number can be used to search the Onfido's data in some cases, this check variant does not confirm the validity of the national identity number. For more information about how Onfido handles this check variant, see Onfido’s documentation.
Configuration options
You have the following configuration options:
Configure custom matching rules: When this option is selected, you can input your own rules. Note that the custom rules that you configure here will override the data provider result and the default Passfort rules.
To configure a new custom matching rule:
Click the rule button, then click the down arrow to expand your new custom rule fields.
Give your rule a meaningful name.
Click in the field and select a result from the menu.
Fail: The individual's details were not matched.
1+1: The individual's details were matched in one source.
2+2: The individual's details were matched in at least two sources.
Enter the to search. You can start typing the name of a database type or click into the field and select from the menu that appears. Select the database types that you need.
Click into the field and select the requirements that you need from each database. For example, you can specify that Forename, Surname, and DOB are required from one database and Forename, Surname, and Address are required from another database.
Note
Note that a match in a mortality database will return a fail result.
If needed, select the checkbox. This checkbox applies when you have two or more lines of requirements. Selecting this checkbox means that each line of requirements must come from a different database.
You can add more custom rules, the first rule whose requirements are met will become the active rule. Reorder these at any time by clicking on and holding the grab bar, then, drag the rules into the order you want them.
If you are using mortality checks, Passfort recommends setting up Fail rules first in order of precedence.
Date of birth must match in one source to achieve a 1+1 or 2+2 result: When this option is selected, it’s only possible for the check to achieve a 2+2 result or a 1+1 result when the individual’s date of birth is matched in Onfido’s sources.
In other words, a 2+2 result is only achieved if the individual’s full name and address are matched in one source and the individual’s full name and date of birth are matched in a second source. A 1+1 result is only achieved when the individual’s full name, date of birth, and address are matched in one source.
Fail the check if a mortality result is found: The individual’s full name and date of birth is searched in Onfido’s mortality lists. If a match is found, the check fails.
Use the most recent previous address if the result isn’t 2+2: When this option is selected, the individual’s most recent address is used when the check is run. With this option, if the check fails or a partial match is returned, the check is run again automatically using the next most recent address. The check is only run again automatically once.
With this configuration option, any time the check is run again automatically, you are charged for a second check. If the addresses provided on the individual’s profile do not include dates, the addresses used for this check are selected at random.
What we’ll need
Let us know that you’d like to add a variant of the Electronic identity check with Onfido and which configuration options you’d like to use. We’ll set it up for you.
We’ll also need your Sandbox API token and your Live API token. Learn how to get your tokens.
Testing your configuration
Once the check variant is configured, follow these steps in your demo environment to test whether it's working as expected.
When the check variant is configured to pass on 2+2 results (default):
Does the check pass when a 2+2 result is achieved?
To run the test, create any individual profile and run the check variant. If the check passes, it’s working as expected.
Does the check return a partial match when a 1+1 result is achieved?
To run the test, create an individual profile with "1+1" as a given name or surname, such as Alex 1+1 Wheeler, and run the check variant. If the check returns a partial match, it’s working as expected.
Does the check fail when the conditions are not met for a 2+2 result or a 1+1 result?
To run the test, create an individual profile with FAIL as a given name or surname, such as Alex FAIL Wheeler, and run the check variant. If the check fails, it’s working as expected.
When the check variant is configured to pass on 1+1 results:
Does the check pass when a 1+1 result is achieved?
To run the test, create an individual profile with "1+1" as a given name or surname, such as Alex 1+1 Wheeler, and run the check variant. If the check passes, it’s working as expected.
Does the check fail when the conditions are not met for a 1+1 result?
To run the test, create an individual profile with FAIL as a given name or surname, such as Alex FAIL Wheeler, and run the check variant. If the check fails, it’s working as expected.
In the live environment, an error is displayed when the check variant is run on a profile with a country of address that isn't covered by Onfido. This error is not displayed in the demo environment. The test words are not case-sensitive.
Profile fields
These are the profile details searched in Onfido’s sources:
Name | Description |
|---|---|
First name(s) ( *Required | The individual’s first and, if applicable, middle names. |
Surname ( *Required | The individual’s last name. |
Date of birth ( *Required | The individual’s date of birth. Note that you must provide the full date of birth. |
Addresses ( *Required | The individual’s address history. |
National identity number ( Optional (US social security numbers only) | The individual’s national identity number for their registered country. |
ID verification (Passfort collects documents)
How it works
This is the default behavior for a variant of the ID verification (Passfort collects documents) check with Onfido as the data provider.
You upload the individual's document to Passfort. Passfort submits the document to Onfido who checks for signs of forgery and extracts the customer’s name, date of birth, and, where possible, nationality from the document.
You can upload these documents for the Verify identity task:
Biometric state ID
Driver's license
National health insurance card
Passport (including the Irish Passport Card)
Residence permit
State ID
Tax ID
Visa
Voter ID
The document must be between 32KB and 10MB. The following file types are accepted: JPG, PNG, and PDF.
Onfido performs image quality checks and the following security checks on documents:
Age validation
Police record
Compromised document
Visual authenticity
To see the checks performed on selfies, see the description of the Check facial similarity configuration option.
Passfort cross-references the details recorded in the individual’s profile, such as name, date of birth, and, if available, nationality, with the extracted data provided by Onfido.
An image of the document is displayed in the check results.
The check passes when all three criteria are met:
The document details obtained from Onfido match the details in the profile.
Onfido confirms the document is authentic by confirming the status of the check is Clear.
Onfido confirms that any additional checks have passed, such as police checks or selfie checks.
If the individual’s details do not match Onfido's data, the check fails.
Because cross-referencing the individual’s details is an action performed in Passfort and not in Onfido, it’s possible for the check to pass in Onfido but fail in Passfort.
Note that Onfido may set the status of the check to Consider, with a sub-status of Caution, Suspected, or Rejected, even if the individual components of the check, like Image Integrity, Data Validation, have passed. If Onfido sets the status to Consider, Passfort fails the check.
For more information about how Onfido determines the status, see their help documentation.
When you view the Full results of the check, you can see a result under Document type called Found document of correct type in image. This is a Passfort-specific result that indicates whether the document type you've selected when running the check matches the document type that was submitted.
If the individual’s profile doesn’t have data for the required fields, an error is displayed.
This check variant is supported for all countries.
This check variant cannot be run on the Verify address task. Onfido does not extract the individual’s address from the document so it’s not possible to use this check to confirm proof of address. For more information about how Onfido handles this check, see Onfido’s documentation. To get step-by-step instructions for running this check, see Verify a document.
Configuration options
Check facial similarity?: When this option is selected, Onfido compares a selfie provided by the individual to the photo in the individual’s identity document. An image of the selfie is displayed in the check results so you can see it. Onfido performs image quality checks and the following security checks for selfies: Face comparison; Visual authenticity.
With ID verification (Passfort collects documents), only selfie checks are supported. To enable liveness checks, you must use ID verification (service collects documents). For more information about how Onfido handles this configuration option, see Onfido’s documentation.
What we’ll need
Let us know that you’d like to add a variant of the ID verification (Passfort collects documents) check with Onfido and which configuration options you’d like to use. We’ll set it up for you.
We’ll need your Sandbox API token, Live API token and Webhook token. Learn how to get your tokens.
Testing your configuration
Once the check variant is configured, follow these steps in your demo environment to test whether it's working as expected.
Does the check pass when the identification document is authentic and the extracted document details obtained from Onfido match the details in the profile?
To run the test, use the following image as the image of the identification document and run the check variant. If the check passes, it’s working as expected.
Does the check fail when the identification document is not authentic or the extracted document details obtained from Onfido do not match the details in the profile?
To run the test, use the following image as the image of the identification document and run the check variant. If the check fails, it’s working as expected.
Profile fields
These are the profile details matched with the document details extracted by Onfido:
Name | Description |
|---|---|
First name(s) ( *Required | The individual’s first and, if applicable, middle names. |
Surname ( *Required | The individual’s last name. |
Date of birth ( *Required | The individual’s date of birth. |
Email address ( Optional | The individual's email address. |
If you’re running the check via the API, the ID verification check also uses the following field from the ID check’s documents:
Key name | Description |
|---|---|
*Required | The document’s unique identifier in Passfort. |
ID verification (service collects documents)
When you're using versions 1 or 2 of Onfido's API, the check behavior is as follows.
How it works
This is the default behavior for a variant of the ID verification (service collects documents) check with Onfido (API v1 or v2) as the data provider.
The individual submits their documents to Onfido who checks for signs of forgery and extracts the individual’s name, date of birth, and, where possible, nationality from the documents.
When Onfido collects the customer's documents, they create an applicant ID. This can be used to retrieve any previous checks.
You can use this check for these document types:
Biometric state ID
Driver's license
National health insurance card
Passport (including the Irish Passport Card)
Residence permit
State ID
Tax ID
Visa
Voter ID
Onfido performs image quality checks and the following security checks on documents:
Age validation
Police record
Compromised document
Visual authenticity
To see the checks performed on selfies and liveness videos, see the description of the Facial similarity check option.
Passfort cross-references the details recorded in the individual’s profile, such as name, date of birth, and, if available, nationality, with the extracted data provided by Onfido.
An image of the document is displayed in the check results.
The check passes when all three criteria are met:
The document details obtained from Onfido match the details in the profile.
Onfido confirms the document is authentic by confirming the status of the check is Clear.
Onfido confirms that any additional checks have passed, such as police checks or selfie checks.
If the individual’s details do not match Onfido's data, the check fails.
Because cross-referencing the individual’s details is an action performed in Passfort and not in Onfido, it’s possible for the check to pass in Onfido but fail in Passfort.
Note that Onfido may set the status of the check to Consider, with a sub-status of Caution, Suspected, or Rejected, even if the individual components of the check, like Image Integrity, Data Validation, have passed. If Onfido sets the status to Consider, Passfort fails the check.
For more information about how Onfido determines the status, see their help documentation.
When you view the Full results of the check, you can see a result under Document type called Found document of correct type in image. This is a Passfort-specific result that indicates whether the document type you've selected when running the check matches the document type that was submitted.
For the ID verification (service collects documents) check, the result will always be Valid.
If the individual’s profile doesn’t have data for the required fields, an error is displayed.
This check variant is supported for all countries.
This check variant cannot be run on the Verify address task. Onfido does not extract the individual’s address from the document so it’s not possible to use this check to confirm proof of address. For more information about how Onfido handles this check, see Onfido’s documentation. To get step-by-step instructions for running this check, see Verify a document.
Configuration options
You can use the following configuration options:
API region: Choose which Onfido region you're using. The options are: Europe and USA.
Facial similarity check: Choose Selfie, Video, or Video with fallback. Onfido compares a selfie or liveness video to the photo in the individual’s identity document. The selfie or the liveness video is displayed in the check results so you can see it. Onfido performs image quality checks and the following security checks for selfies: Face comparison; Visual authenticity.
When Selfie is selected, Onfido's
facial_similarity_photoreport type is used. When Video is selected, Onfido'sfacial_similarity_videoreport type is used. When Video with fallback is selected, Onfido'sfacial_similarity_videoreport type is used if a video is available, regardless of whether the check passes or fails; otherwise,facial_similarity_photois used.
If you have this configuration option set to Video, you should set the uploadFallback property to false in your Onfido SDK configuration. Otherwise, Onfido will try to upload a selfie when liveness is not supported by the browser, and the check will error.
What we'll need
This is the same as ID verification (Passfort collects documents) for Onfido.
Testing your configuration
Onfido is not contacted in a demo environment. Once the check variant is configured, follow these steps in your staging environment with an Onfido sandbox token to test whether it's working as expected.
Does the check pass when the ID is authentic and the extracted document details obtained from Onfido match the details in the profile?
To run the test, first create an individual profile with these details:
Any first name and last name.
1 January 1900 as the date of birth.
Next, initiate the check variant with Onfido using these details:
The same first name and last name you used on the profile.
1 January 1900 as the date of birth.
For any other details required by Onfido, use any data. For example, you can use any image as the image of the ID.
If the check passes, it’s working as expected.
Does the check fail when the ID is authentic but the extracted document details obtained from Onfido do not match the details in the profile?
To run the test, first create an individual profile with these details:
Any first name and last name.
Any date of birth.
Next, initiate the check with Onfido using these details:
Any first name and last name that is not what you used on the profile.
Any date of birth.
For any other details required by Onfido, use any data. For example, you can use any image as the image of the ID.
If the check fails, it’s working as expected.
Does the check fail when the ID is not authentic, even if the extracted document details obtained from Onfido match the details in the profile?
To run the test, first create an individual profile with these details:
Any first name.
consider as the last name.
Any date of birth.
Next, initiate the check with Onfido using these details:
The same first name you used on the profile.
consider as the last name.
The same first name you used on the profile.
For any other details required by Onfido, use any data. For example, you can use any image as the image of the ID.
When you use "consider" as the individual’s last name, it must be in lowercase, such as Alex consider.
Required profile fields
These are the required profile details matched with the document details extracted by Onfido:
Name | Description |
|---|---|
First name(s) ( | The individual’s first and, if applicable, middle names. |
Surname ( | The individual’s last name. |
Date of birth ( | The individual’s date of birth. |
Getting your Onfido tokens
To get your Sandbox API token and Live API token:
Go to https://dashboard.onfido.com/api/tokens.
Copy the token for the Live environment.
Copy the token for the Sandbox environment.
Send us the Live token from Step 2 and the Sandbox token from Step 3.
Only one Live token and Sandbox token can be used in your Passfort configuration. If you have multiple Live or Sandbox tokens, choose one from each type.
To get your webhook token:
Go to https://onfido.com/dashboard/v2/#/api/webhook_management
Click .
In the URL field, add: https://api.passfort.com/callback/onfido
Under Receive data from, select .
Leave all event notifications enabled.
Click . The new webhook is created.
Copy the for the new webhook and send it to us.