Configuring Onfido

Onfido is a data provider that enables you to run three checks:

Electronic identity check

How it works

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.

By default, the check passes when a 2+2 result is achieved, the check returns a partial match if a 1+1 result is achieved. By default, the conditions for each result are as follows.

A 2+2 result is achieved when either of these conditions are true:

  1. 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.
  2. The individual’s full name and address are matched in two distinct sources.

If a 2+2 result cannot be achieved, a 1+1 result is achieved when either of these conditions are true:

  1. The individual’s full name, date of birth, and address are matched in one source.
  2. 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, the check returns an error.

If the country of address in the individual’s profile isn’t covered by Onfido, the check returns an error.

For more information about how Onfido handles this check, see Onfido’s documentation.
This check is more likely to succeed on older addresses. To improve match rates, you may want to ask customers if they moved in the last 6 months and, if so, request a previous address.

Configuration options

You have the following configuration options :

  • Pass check on 1+1 result (optional): The check passes when a 1+1 result is achieved. When this configuration is used, partial matches are never returned.
  • DOB is one of the required fields (optional): It’s only possible 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 this case, 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.
  • Use the most recent previous address if the result isn’t a 2+2 (optional): When the check is run, the individual’s most recent address is used. With this option, if the check fails or, in the case of 2+2 matches, 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, 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.
  • Check mortality list (optional): The individual’s full name and date of birth is searched in Onfido’s mortality lists. If a match is found, the check fails.

What we’ll need

Let us know that you’d like to run this check with Onfido and which configuration options you’d like to use, and we’ll set it up.

If you have a direct agreement with Onfido, 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 is configured, follow these steps in your demo environment to test whether the check is working as expected.

When the check is configured to pass on 2+2 results (default):

  1. Does the check pass when a 2+2 result is achieved?
    To run the test, create any individual profile and run the check. If the check passes, it’s working as expected.
  2. 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 (e.g. ‘Alex 1+1 Wheeler’) and run the check. If the check returns a partial match, it’s working as expected.
  3. 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 (e.g. ‘Alex FAIL Wheeler’) and run the check. If the check fails, it’s working as expected.

When the check is configured to pass on 1+1 results:

  1. 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 (e.g. ‘Alex 1+1 Wheeler’) and run the check. If the check passes, it’s working as expected.
  2. 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 (e.g. ‘Alex FAIL Wheeler’) and run the check. If the check fails, it’s working as expected.
The test words are not case-sensitive.

These are the individual’s profile details searched in Onfido’s sources:

Field name

Description

Notes

Portal: First name(s)

API:personal_details.name.given_names

The individual’s first and, if applicable, middle names.

Required

Portal: Surname

API:personal_details.name.family_name

The individual’s last name.

Required

Portal: Date of birth

API:personal_details.dob

The individual’s date of birth.

Required

Portal: Addresses

API:address_history

The individual’s address history.

Required

Portal: National identity number

API:personal_details.national_identity_number

The individual’s national identity number for their registered country.

Optional.

Only available for United States social security numbers.

ID verification (PassFort collects documents)

How it works

You upload the individual's documents to PassFort. PassFort submits the documents to Onfido who checks for signs of forgery and extracts the customer’s name, date of birth, and, where possible, nationality from the documents.

If you are using the Check facial similarity configuration option, Onfido also performs a selfie check.

It’s only possible to upload selfies via the API.

PassFort cross-references the details recorded in the individual’s profile (name, date of birth, and, if available, nationality) with the extracted data provided by Onfido.

PassFort imports an image of the documents to the task on the profile.

The check passes when all three criteria are met:

  1. The document details obtained from Onfido match the details in the profile.
  2. Onfido confirms the documents are authentic.
  3. Onfido confirms that any additional checks have passed (e.g. police checks or selfie checks).

If the individual’s details do not match the data in Onfido’s sources, 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.

If the individual’s profile doesn’t have data for the required fields, the check returns an error.

This check is supported for all countries.

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.

Configuration options

Check facial similarity (optional): Onfido compares a selfie provided by the individual to the photo in the individual’s identity document. PassFort imports an image of the selfie to the task on the profile so you can see it.

PassFort always imports an image of the identity document to the task on the profile, whether or not you’re using the Check facial similarity option.
Only Onfido’s standard facial similarity check is supported. Video is not currently supported. 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 run this check with Onfido and which configuration options you’d like to use, and we’ll set it up.

If you have a direct agreement with Onfido, 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 is configured, follow these steps in your demo environment to test whether the check is working as expected.

  1. 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 image below as the image of the identification document and run the check. If the check passes, it’s working as expected.
  2. 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 image below as the image of the identification document and run the check. If the check fails, it’s working as expected.

These are the individual’s profile details matched with the document details extracted by Onfido:

Field name

Description

Notes

Portal: First name(s)

API:personal_details.name.given_names

The individual’s first and, if applicable, middle names.

Required

Portal: Surname

API:personal_details.name.family_name

The individual’s last name.

Required

Portal: Date of birth

API:personal_details.dob

The individual’s date of birth.

Required

If you’re running the check via the API, the ID verification check also uses the following field from the ID check’s documents:

Field name

Description

Notes

document_id

The document’s unique identifier in PassFort.

Required

ID verification (service collects documents)

How it works

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.

If you are using the Check facial similarity configuration option, Onfido also performs a selfie check.

PassFort cross-references the details recorded in the individual’s profile (name, date of birth, and, if available, nationality) with the extracted data provided by Onfido.

PassFort imports an image of the documents to the task on the profile.

The check passes when all three criteria are met:

  1. The document details obtained from Onfido match the details in the profile.
  2. Onfido confirms the documents are authentic.
  3. Onfido confirms that any additional checks have passed (e.g. police checks or selfie checks).

If the individual’s details do not match the data in Onfido’s sources, 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.

If the individual’s profile doesn’t have data for the required fields, the check returns an error.

This check is supported for all countries.

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.

Configuration options

This is the same as ID verification (PassFort collects documents). See above for details

What we’ll need

This is the same as ID verification (PassFort collects documents). See above for details

Testing your configuration

Once the check is configured, follow these steps in your demo environment to test whether the check is working as expected.

  1. 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:
    1. Any first name and last name.
    2. ‘1 January 1900’ as the date of birth.
    3. Any address.

    Next, initiate the check with Onfido using these details:
    1. The same first name and last name you used on the profile.
    2. ‘1 January 1900’ as the date of birth.
    3. 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.
  2. 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:
    1. Any first name and last name.
    2. Any date of birth.
    3. Any address.

    Next, initiate the check with Onfido using these details:
    1. Any first name and last name that is not what you used on the profile.
    2. Any date of birth.
    3. 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.
  3. Does the check fail when the identification document 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:
    1. Any first name.
    2. ‘consider’ as the last name.
    3. Any date of birth.
    4. Any address.

    Next, initiate the check with Onfido using these details:
    1. The same first name you used on the profile.
    2. ‘consider’ as the last name.
    3. The same first name you used on the profile.
    4. 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 lower case (e.g. ‘Alex consider’).

These are the individual’s profile details matched with the document details extracted by Onfido:

Field name

Description

Notes

Portal: First name(s)

API:personal_details.name.given_names

The individual’s first and, if applicable, middle names.

Required

Portal: Surname

API:personal_details.name.family_name

The individual’s last name.

Required

Portal: Date of birth

API:personal_details.dob

The individual’s date of birth.

Required

Portal: Addresses

API:address_history

The individual’s address history.

Required

This is the only field not matched with the document details extracted by Onfido.

If you’re running the check via the API, the ID verification check also uses the following field from the ID check’s documents:

Field name

Description

Notes

document_id

The document’s unique identifier in PassFort.

Required

Getting your Onfido tokens

To get your Sandbox API token and Live API token:

  1. Go to https://onfido.com/dashboard/v2/#/api/tokens
  2. Copy the token for the Live environment.
  3. Copy the token for the Sandbox environment.
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:

  1. Go to https://onfido.com/dashboard/v2/#/api/webhook_management
  2. Click Create Webhook.
  3. In the URL field, add: https://api.passfort.com/callback/onfido
  4. Under Receive data from, select Both.
  5. Leave all event notifications enabled.
  6. Click Save. The new webhook is created.
  7. Copy the Token for the new webhook.


How did we do?