Configuring Trulioo Global Gateway

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 (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 match when a 1+1 result is achieved.

If Trulioo cannot 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 documented below. We recommend using this configuration option if you have ultra-customized configuration options in Trulioo.

Configuration options

Pass check on 1+1 result: When this option is selected, the check passes when a 1+1 result is achieved. When this configuration option is used, partial matches are never returned.
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.
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.
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.

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.

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 dropdown, 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, scroll to 'How PassFort's address fields map to Trulioo's Location fields' at the end of this article.

What we’ll need

Let us know that you’d like to run a variant of the Electronic identity check with Trulioo GlobalGateway eIDV and 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):

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 (e.g. "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 (e.g. "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 (e.g. "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 (e.g. "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):

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 (e.g. "Alex PASS Wheeler") and run the check variant. If the check passes, it’s working as expected.
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 (displayed when the Use provider result configuration is switched on) 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 the section below called 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 r equired 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 Required and optional profile fields section above.
`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 will not validate the address, regardless of which other fields match.

In this section:

Using PassFort