There is a lot of information in a Verify response. This page will help you understand the information, how to use it, and how to get the most out of your verification results.
TransactionRecordID
This is the unique ID used for verification. You can use this for your reference, in the Get Transaction Record method to review a past transaction, or you can contact Trulioo Support about a verification result.
"Record": {
"TransactionRecordID": "0ac8ccee-ab7a-495e-8b88-a6da1bdcb6ae",
Datasource
Trulioo provides access to over 200 global datasources. A verification response contains an array of DatasourceResult objects for each datasource configured on an account. Each DatasourceResult contains a DatasourceName, and a DatasourceFields subarray, which indicates the match status for each field sent to that datasource.
Some of the common Datasources are listed in the table below:
| Datasource | Description |
|---|---|
| Citizen | Data sourced from either a utility or government-issued database that is enhanced and updated with other source files such as public data, change of address, postal data, property data, and data pooling with other organizations. |
| Consumer | Data sourced from direct marketing campaigns. |
| Credit | Data derived from a registered credit agency, or bureau, which manages consumer credit information on individuals with a consumer credit history in that country. |
| Electoral Roll | A government collated and issued datasource, for all citizens in a country, who are enrolled to vote. |
| Government Issued | A government collated and issued databases or information. This includes national insurance numbers, driver’s licenses, and passports. |
| National ID | A government collated and issued data for countries that have a singular, a national identification system with an associated number. |
| Property Files | Data issued by the government or other accredited sources detailing ownership of property within a given country. |
| Public Data/Resident Files | Mixed source which may include utility, consumer, and other public information. |
| Utility | Data issued for a national utility provider which includes telephone, gas, electricity, or water. |
| Telephone File | An automated, telephone number verification service, which details whether a landline or mobile number is valid and hence connects, or is disconnected. |
| Watchlists (OFAC, DFAT, EU, etc.) | |
| Other Identity Validation | Validation of national identity numbers, social security numbers, national health numbers, or other key country indicators of identity. Also includes validation of the unique reference number at the bottom of the global passport machine-readable zone (MRZ), which specifies that it is valid and also includes the individual’s name and date-of-birth. |
An example DatasourceResults array:
"DatasourceResults": [
{
"DatasourceName": "Australia Citizen File",
"DatasourceFields": [
{
"FieldName": "BuildingNumber",
"Status": "match"
},
{
"FieldName": "MiddleName",
"Status": "missing"
},
{
"FieldName": "StreetName",
"Status": "match"
},
{
"FieldName": "UnitNumber",
"Status": "missing"
},
{
"FieldName": "Suburb",
"Status": "match"
},
{
"FieldName": "StreetType",
"Status": "match"
},
{
"FieldName": "Telephone",
"Status": "nomatch"
},
{
"FieldName": "DayOfBirth",
"Status": "match"
},
{
"FieldName": "FirstSurName",
"Status": "match"
},
{
"FieldName": "StateProvinceCode",
"Status": "match"
},
{
"FieldName": "MonthOfBirth",
"Status": "match"
},
{
"FieldName": "PostalCode",
"Status": "match"
},
{
"FieldName": "FirstInitial",
"Status": "match"
},
{
"FieldName": "YearOfBirth",
"Status": "match"
},
{
"FieldName": "FirstGivenName",
"Status": "match"
},
{
"FieldName": "MiddleInitial",
"Status": "missing"
}
],
"AppendedFields": [],
"Errors": [],
"FieldGroups": []
},
.
.
.
.
]
Fields and Matching Signals
As shown in the example above, each DatasourceResult contains an array of DatasourceFields, which lists the fields this particular datasource has returned. Each DatasourceField consists of FieldName and Status.
FieldName describes the type of information that has been returned from the datasource, such as StreetName or YearOfBirth. You can use the API endpoint Get Fields to see all the fields available to you in a particular country. To ensure you get a response from every datasource, it is recommended that you include each field returned by Get Fields in your verification request if possible.
Status indicates whether or not a particular field matched what was on record in the datasource. It can take on the following values:
| Values | Description |
|---|---|
| match | This field exists in the datasource and matches the value you input. |
| nomatch | This field exists in the datasource, but does not match the value you input. |
| missing | Either no data was sent in the Verify Request or no information about this field could be found in the datasource. |
| censored | Due to the nature of the datasource, Trulioo cannot display the status of this particular field, although it was used toward the verification rule result (discussed below). |
Appended Fields
On occasion, a datasource will respond with information that isn't a match signal for a specific field, but might still be useful for you to know. A common example is the "IsDeceased" appended field, which indicates whether or not the person whose identity you're trying to verify is deceased. This information is included in the AppendedFields section for that datasource (underneath the DatasourceResults object):
"AppendedFields": [
"IsDeceased": "false"
],
Errors
The DatasourceResults object contains another section called "Errors", where you are informed of any errors that occurred during the verification. Errors are returned on a per-datasource basis because even if there is an issue with one particular datasource, the rest of the transaction will continue with the other sources. For example, a field formatted incorrectly. If that field is required for one datasource, but optional for all other sources, only the first datasource will return an error. The malformed field is ignored by the remaining datasources, which return match signals for all other fields.
Review the full list of Error codes.
"Errors": [
{
"Code": "1001",
"Message": "Missing required field: FirstSurName"
},
{
"Code": "1005",
"Message": "Missing Consent"
}
]
Rules
At the end of the verification results is a Rule object. It describes how the Trulioo Platform used the match signals in the datasource result fields to evaluate the process of identity verification. You can work with Trulioo support to configure your desired verification rules on a country-by-country basis, but the most commonly used rule is the Category 3 KYC rule shown below. This states that an individual will be verified if:
- There is a match status on Family AND GivenInitial AND DOB
OR - There is a match status on Family AND GivenInitial AND FullAddress
OR - There is a match status on Family AND GivenInitial AND ID
"Family" can encompass several data fields based on country, but in many cases it simply means "surname".
If any of the criteria of the verification rule are met, then the individual is considered verified, and the overall RecordStatus returns as a match.
"Rule": {
"RuleName": "Category 3 KYC v3",
"Note": "Match(FamilyAndGivenInitial, DOB) or Match(FamilyAndGivenInitial, FullAddress) or Match(FamilyAndGivenInitial, ID) MiddleName Ignored"
}
Verification
Verification is the final portion of the Verify response. RecordStatus indicates the overall match status of the identity you provided, based on the datasource fields in combination with the verification rule discussed above. A RecordStatus of "match" means the identity was verified (one or more datasources provided match signals that satisfied the verification rule). A RecordStatus of "nomatch" means the identity could not be verified.
"RecordStatus": "match",
The details provided by the Trulioo Platform response allow you to make your application's matching logic as simple or thorough as you like. You can take the RecordStatus value and use that to determine whether or not an identity was verified, or you can dig into the specific datasource results and perform your field-by-field matching.
Secondary Rule
Customers can configure a second verification rule for a country. The secondary rule will only be executed if the primary/main rule does not return a 'match' result (ie RecordStatus = nomatch).
The secondary rule verification is computed using the data field results.
A secondary rule can be used to determine a 'partial match'. To do this, the secondary rule must be a subset of the primary rule. For example, if the primary rule is Match on Name + Address AND Name + Date of Birth, then the secondary rule could be Match on Name + Address OR Name + Date of Birth.
The secondary rule is customizable and can be configured to meet a customer's use case. Please reach out to Trulioo Customer Support at [email protected] if you're interested in this feature.
If a secondary rule is enabled the following fields will be returned in the JSON response:
- SecondaryRecordStatus
- Possible values: match, nomatch, or ""
- SecondaryRuleName
- The rule name
- SecondaryRuleNote
- The rule description
If the secondary rule passes the SecondaryRecordStatus will be set to "match". If the secondary rule fails then the SecondaryRecordStatus will be set to "nomatch". If the secondary rule is not run, this happens when the primary/main rule passes, the SecondaryRecordStatus will be set to "".
The secondary rule will not change the overall Trulioo verification result, which is dictated by the primary verification rule.
{
"TransactionID": "4b69ecc6-bf5a-40ea-8f66-c5c3fbc5d234",
"UploadedDt": "2022-11-01T21:32:11.820572",
"CompletedDt": "2022-11-01T21:32:12.206823",
"CountryCode": "US",
"ProductName": "Identity Verification",
"Record": {
"TransactionRecordID": "202d6250-4331-2252-a725-74854ba444f3",
"RecordStatus": "nomatch",
"SecondaryRecordStatus": "match",
"DatasourceResults": [...],
"AppendedFields": [],
"Errors": [],
"FieldGroups": []
}
],
"Errors": [],
"Rule": {
"RuleName": "RuleScript - NameAnd2Tokens_v41",
"Note": "2 Record Match (FN/DOB/ID)",
"SecondaryRuleName": "RuleScript - NameAndDOB_v33",
"SecondaryRuleNote": "1 Records Match (FirstName AND LastName AND DOB) AND 1 Records Match (FirstName AND LastName)"
}
},
"Errors": []
}