Skip to main content

Configuring Trulioo GlobalGateway eIDV

Trulioo is a data provider that offers the GlobalGateway eIDV service, which you can use to run the Electronic identity check.

How it works

When no configuration options are applied, this is the default behavior for a variant of the Electronic identity check with Trulioo GlobalGateway eIDV.

The check is performed by sending the individual’s details, such as name, date of birth, address to Trulioo GlobalGateway eIDV, who attempts to verify the individual's identity.

If Trulioo is able to verify the individual's identity:

  • The check passes when a 2+2 result is achieved.

  • The check returns a partial when a 1+1 result is achieved.

If Trulioo can't verify the individual's identity using their sources, the check fails.

An error is displayed if either of the following is true:

  • The individual’s profile doesn’t have data for the fields required by Passfort or the fields required by Trulioo.

  • The country of address in the individual’s profile isn’t covered by your agreement with Trulioo GlobalGateway eIDV.

See Trulioo's Identity verification documentation to learn more about how they verify individuals. Passfort is unable to capture the rules Trulioo has used to verify the individual's identity. You can see what rules you're using with Trulioo's Get Fields endpoint. To improve the accuracy of the results, provide the customer’s middle name.

How Passfort calculates 1+1 and 2+2 results

2+2 results are achieved if either of these conditions are met:

  • 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.

  • The individual's full name and address are matched in two distinct sources.

1+1 results are achieved when a 2+2 result cannot be achieved and either of these conditions are met:

  • 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.

You can disable 1+1 and 2+2 results with the Use provider result configuration option. We recommend using this configuration option if you have ultra-customized configuration options in Trulioo.

Configuration options

  • 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 to achieve a 2+2 result or a 1+1 result when the individual's date of birth is matched in Trulioo'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.

  • Date of birth must match in two sources to achieve a 2+2 result :When this option is selected, it's only possible to achieve a 2+2 result when the individual's date of birth is matched in two of Trulioo's sources. In other words, a 2+2 result is only achieved if the individual's full name and date of birth are matched in one source and the individual's full name, date of birth, and address are matched in a second source.

    Note

    It's not possible to use the Date of birth must match in our source to achieve a 1+1 or 2+2 result configuration option in conjunction with Date of birth must match in two sources to achieve a 2+2 result because they produce two conflicting behaviors.

  • Validate address if either city or state matches, even if other fields are flagged as mismatched: When this option is selected, the address is considered validated when the province or locality matches, even if other address fields do not match.

  • Match on first initial instead of forename: When this option is selected, a first name match, which contributes to the full name match, is achieved when the first initial matches. For example, Trulioo could return Alex Wheeler or Alexandra Wheeler as full name match for a profile named A Wheeler.

  • Use provider result: When this option is selected, the overall status in the check result is mapped directly to the RecordStatus returned from Trulioo GlobalGateway eIDV. Passfort's 1+1 and 2+2 results are disabled. If the RecordStatus is match, the overall result is Pass; if the RecordStatus is nomatch, the overall result is Fail; and if the RecordStatus is error, an error is returned. Additionally, rather than showing a list of Trulioo's sources in the check results, a link to the profile in Trulioo's portal is displayed where users can see this information. Note that users must have their own Trulioo portal credentials to access this profile page.

    The result metrics in the Check report will show Pass and Fail, rather than 1+1 and 2+2.

    If the Trulioo check variant is used as the second variant in a waterfall, it will only be run if the first provider's result does not include an address or date of birth.

  • Address Data Settings: When this option is used, you can choose your preferred address format to send to Trulioo. From the Address Data Settings drop-down, choose one of the following options:

    • Send in separate fields: This is the default option. Use this setting to send address data in separate fields.

      • Use Address1 for these countries: You can also specify which countries to exclude from this option. These countries are sent Address1 instead.

    • Send in Address1: Select this option to send the address data as part of the Address1 field. Address1 is made up of the following fields:

      subpremise + street_number + route , postal_code + locality

      Trulioo calls this Address1, PostalCode + City

    To learn more about Address1, see How Passfort's address fields map to Trulioo's Location fields.

What we’ll need

Let us know that you’d like to run a variant of the Electronic identity check with Trulioo GlobalGateway eIDVand which configuration options you’d like to use. We’ll set it up for you.

We’ll also need your Trulioo GlobalGateway eIDV username and password. For help getting your username and password, please contact your Trulioo GlobalGateway eIDV account manager.

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):

  1. 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.

  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, such as Alex 1+1 Wheeler, and run the check variant. 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, 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:

  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, such as Alex 1+1 Wheeler, and run the check variant. 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, 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 use the provider result (meaning 1+1 and 2+2 results are disabled):

  1. Does the check pass when Trulioo's RecordStatus is match?

    To run the test, create an individual profile with "PASS" as a given name or surname, such as Alex PASS Wheeler, and run the check variant. If the check passes, it’s working as expected.

  2. Does the check fail when Trulioo's RecordStatus is nomatch?

    To run the test, create any individual profile and run the check variant. If the check fails, it’s working as expected.

In the demo environment, the Go to full results link is displayed when the Use provider result configuration is switched on and takes you to Trulioo's portal, but does not take you to a specific profile.

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 Trulioo GlobalGateway eIDV. 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 Trulioo GlobalGateway eIDV’s sources:

Field name

Description

First name(s)

(personal_details.name.given_names)

*Required

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

Surname

(personal_details.name.family_names)

*Required

The individual’s last name.

Date of birth

(personal_details.dob)

*Required

The individual’s date of birth.

Addresses

(address_history)

*Required

The individual’s address history.

To learn which fields from address_history are used for matches, see How Passfort's address fields map to Trulioo's Location fields.

National identity number

(personal_details.national_identity_number)

Optional

The value of this field is passed to Trulioo as one of the following:

  • NationalId

  • Health

  • SocialService

  • TaxIDNumber

For more information, see How national_identity_number is passed to Trulioo.

Gender

(personal_details.gender)

Optional

The individual's gender. Leave unset for non-binary genders.

Phone number

(contact_details.phone_number)

Optional

The individual's phone number.

Email address

(contact_details.email)

Optional

The individual's email address.

documents_metadata

Optional

An array of objects where each object corresponds to one document.

Note that this array of objects can only have one object for each document type and country code combination. For example, for there can be one object with DRIVING_LICENCE and GBR, and a second object DRIVING_LICENCE and USA, but there cannot be two objects with DRIVING_LICENSE and GBR.

For an example of the documents_metadata object, see Update collected data in the Developer Resources.

Note that documents_metadata can only be updated via the API. Step-by-step instructions can be found here: Update Passfort's profile data when your system data changes.

documents_metadata.document_type

Required for objects in documents_metadata

The document's type.

The document type must be DRIVING_LICENCE for drivers licenses and VOTER_ID for Indian voter IDs.

documents_metadata.country_code

Required for objects in documents_metadata

The country that issued the individual's driving licence or voter ID.

The country must be provided as an ISO3 code.

documents_metadata.number

Required for objects in documents_metadata

The individual's driving licence number or voter ID number.

documents_metadata.issuing_state

Optional for objects in documents_metadata (US and Canada only)

The country's state, province, or territory that issued the ID.

Although a field may be optional for Passfort, if you've set it as required in your Trulioo configuration and it's not provided when you run the check, an error message is returned. To learn about the fields in your Trulioo configuration, see Trulioo's documentation.

How national_identity_number is passed to Trulioo

The individual's national_identity_number may refer to these Trulioo supported ID types:

  • NationalId

  • TaxIDNumber

  • SocialService

  • Health

Learn about Trulioo's supported ID types.

Passfort uses the individual's country of residence (taken from the individual's address) to determine which Trulioo ID type to use.

In cases where Trulioo has multiple IDs for a country, the value's length of characters determines the ID type.

The ID types are sent as follows:

Individual's country of residence (ISO3 Country Code)

Type of ID sent to Trulioo

National identity number

CAN

SocialService

Social Insurance Number (SIN)

CHN

NationalID

Resident Identity Card

ESP

NationalID

DNI or Numero de Identificacion Fiscal (NIF)

GBP

If the value has 10 characters: Health

Any other number of characters: SocialService

VAT identification number (VATIN)

HKG

NationalID

Hong Kong Identity Card (HKID)

FIN

NationalID

VAT identification number (VATIN)

FRA

NationalID

VAT identification number (VATIN)

IND

If the value has 10 characters: SocialService

Permanent Account Number (PAN)

Note that to send drivers licenses and voter IDs, you should add them to the individual's documents_metadata object. For more information, see the Profile fields section.

IRL

SocialService

Personal Public Service (PPS)

ITA

SocialService

Codice fiscale

MEX

If the value has 12 or 13 characters: SocialService

Any other number of characters: NationalID

Clave Unica de Registro de Poblacion (CURP) or Tax ID Number (RFC)

MYS

NationalID

Registration Identity Card Number (NRIC)

RUS

If the value has 12 characters: TaxIDNumber

Any other number of characters: SocialService

Taxpayer Personal Identification Number (TIN or INN) or internal Russian passport

SGP

NationalID

National Registration Identity Card (NRIC)

SWE

NationalID

Personal Identification Number (PIN)

USA

SocialService

Social Security Number (SSN)

Any other country

NationalID

-

How Passfort's address fields map to Trulioo's Location fields

Here's how the Passfort fields from the individual's address (collected_data.address_history.address) map to Trulioo's fields for Location (DataFields.Location).

Passfort address fields

Trulioo Location fields

street_number

BuildingNumber

premise

BuildingName

subpremise

UnitNumber

route

StreetName

locality

City

postal_town

Only used if locality is present

Suburb

postal_town

Only used if locality is absent

City

county

County

state_province

StateProvinceCode

postal_code

PostalCode

route + street_number + premise + subpremise

Address1

To achieve an overall address match for any country listed for Address1, the following address fields must match:

  • subpremise + street_number + route , postal_code + locality

    • Trulioo calls this Address1, PostalCode + City

For any other country, one of the following combinations of address fields must match:

  • route + postal_code + premise (Trulioo calls this StreetName + PostalCode + BuildingName)

  • route + postal_code + street_number (Trulioo calls this StreetName + PostalCode + BuildingNumber)

If any address field is reported as nomatch, Passfort doesn't validate the address, regardless of which other fields match.

In this section: