API Integration

This page will walk you through the process of verifying your first individual through the Trulioo GlobalGateway API. It includes recipes and steps that are required for the integration of this solution. The first set of recipe is common to all Trulioo Solutions, while the next steps are for the integration. The final recipe is to carry out a Verify request.


Identity Verification Integration

The integration of Identity Verification Solution is a 5 step process. The first 2 steps confirm if you are connected and can communicate with our servers, while the additional 2 steps assist in the Verify Request and Verify Response.

Steps 1 & 2

Click on the Recipe below to begin with the first 2 steps of the integration:

Once you are connected and authenticated, the next step is to check which countries your account is configured for, the list of fields that you need for identifying someone and finally, you may need some additional consents from your customers. We have explained each of these steps below with the Request and Response for integrating the solution.


Step 3: Countries configured for your account

The GlobalGateway API is structured to make calls by country. Your organization's contract with Trulioo will outline what countries are available. If you're not sure what countries are configured for your account, use the GlobalGateway Get Country Codes endpoint to retrieve this information at any time. Simply call the endpoint and you will receive the full list of country codes available for your account. To know more about this topic, click here.

🚧

Important:

Trulioo provides multiple global and regional endpoints. Please choose the correct endpoint based on your business use case and your regulatory and compliance requirements. See the full list here.

Request

GET <<endpoint>>/v3/configuration/countrycodes/{packageID}
Authorization: OAuth
//Example Username: JoeNapoli_API_Demo, Example Password: 05uZuPRCyPi!6
var truliooClient = new TruliooApiClient("JoeNapoli_API_Demo", "05uZuPRCyPi!6");
IEnumerable<string> e = await truliooClient.Configuration
    .GetCountryCodesAsync("Identity Verification");
//Example Username: JoeNapoli_API_Demo, Example Password: 05uZuPRCyPi!6
ApiClient apiClient = new ApiClient();
apiClient.setUsername("JoeNapoli_API_Demo");
apiClient.setPassword("05uZuPRCyPi!6");
ConfigurationApi configurationClient = new ConfigurationApi(apiClient);

//getCountryCodes
List<String> countryCodes = configurationClient.getCountryCodes("Identity Verification");

//getCountryCodesAsync
configurationClient.getCountryCodesAsync("Identity Verification", new ApiCallback<List<String>>() {
    @Override
    public void onFailure(ApiException e, int statusCode, Map<String, List<String>> responseHeaders) {
        Logger.getLogger(SdkJavaV1Sample.class.getName()).log(Level.SEVERE, null, e);
    }
    @Override
    public void onSuccess(List<String> result, int statusCode, Map<String, List<String>> responseHeaders) {
        System.out.println(result); //To change body of generated methods, choose Tools | Templates.
    }
    @Override
    public void onUploadProgress(long bytesWritten, long contentLength, boolean done) {
        //To change body of generated methods, choose Tools | Templates.
    }
    @Override
    public void onDownloadProgress(long bytesRead, long contentLength, boolean done) {
        //To change body of generated methods, choose Tools | Templates.
    }
});

Response

[
  "AU",
  "CA",
  "CN",
  "IN",
  "US",
  "GB",
  "IT",
  "MY",
  "NZ",
  "BE"
]

Step 4: Map your Fields

Now that you know what country codes are valid for your account, you will be able to make a Get Fields request. This will return a detailed list of all of the fields that you need to provide to verify an identity in a given country. These fields will vary based on country, the datasources, and your organization's global account configuration. To know more about this topic, click here.

Request

GET <<endpoint>>/v3/configuration/fields/{packageID}/{countryCode}
Authorization: OAuth
//Example Username: JoeNapoli_API_Demo, Example Password: 05uZuPRCyPi!6
var truliooClient = new TruliooApiClient("JoeNapoli_API_Demo", "05uZuPRCyPi!6");
Dictionary<string, dynamic> e = await truliooClient
    .Configuration.GetFieldsAsync("AU", "Identity Verification");
//Example Username: JoeNapoli_API_Demo, Example Password: 05uZuPRCyPi!6
ApiClient apiClient = new ApiClient();
apiClient.setUsername("JoeNapoli_API_Demo");
apiClient.setPassword("05uZuPRCyPi!6");
ConfigurationApi configurationClient = new ConfigurationApi(apiClient);

//getFields
Object o = configurationClient.getFields("AU", "Identity Verification");

//getFieldsAsync
configurationClient.getFieldsAsync("AU", "Identity Verification", new ApiCallback<Object>() {
    @Override
    public void onFailure(ApiException e, int statusCode, Map<String, List<String>> responseHeaders) {
        Logger.getLogger(SdkJavaV1Sample.class.getName()).log(Level.SEVERE, null, e);
    }
    @Override
    public void onSuccess(Object result, int statusCode, Map<String, List<String>> responseHeaders) {
        System.out.println(result); //To change body of generated methods, choose Tools | Templates.
    }
    @Override
    public void onUploadProgress(long bytesWritten, long contentLength, boolean done) {
        //To change body of generated methods, choose Tools | Templates.
    }
    @Override
    public void onDownloadProgress(long bytesRead, long contentLength, boolean done) {
        //To change body of generated methods, choose Tools | Templates.
    }
});

Response

{
  "title": "DataFields",
  "type": "object",
  "properties": {
    "PersonInfo": {
      "title": "PersonInfo",
      "type": "object",
      "properties": {
        "FirstGivenName": {
          "type": "string"
        },
        "MiddleName": {
          "type": "string"
        },
        "FirstSurName": {
          "type": "string"
        },
        "DayOfBirth": {
          "type": "int"
        },
        "MonthOfBirth": {
          "type": "int"
        },
        "YearOfBirth": {
          "type": "int"
        },
        "Gender": {
          "type": "string"
        }
      },
      "required": [
        "DayOfBirth",
        "FirstGivenName",
        "FirstSurName",
        "MonthOfBirth",
        "YearOfBirth"
      ]
    },
    "Location": {
      "title": "Location",
      "type": "object",
      "properties": {
        "BuildingNumber": {
          "type": "string"
        },
        "UnitNumber": {
          "type": "string"
        },
        "StreetName": {
          "type": "string"
        },
        "StreetType": {
          "type": "string"
        },
        "Suburb": {
          "type": "string"
        },
        "StateProvinceCode": {
          "type": "string"
        },
        "PostalCode": {
          "type": "string"
        }
      },
      "required": [
        "BuildingNumber",
        "PostalCode",
        "StateProvinceCode",
        "StreetName"
      ]
    },
    "Communication": {
      "title": "Communication",
      "type": "object",
      "properties": {
        "MobileNumber": {
          "type": "string"
        },
        "Telephone": {
          "type": "string"
        },
        "EmailAddress": {
          "type": "string"
        }
      },
      "required": []
    },
    "CountrySpecific": {
      "title": "CountrySpecific",
      "type": "object",
      "properties": {
        "AU": {
          "title": "AU",
          "type": "object",
          "properties": {
            "AuImmiCardNumber": {
              "type": "string"
            }
          },
          "required": [
            "AuImmiCardNumber"     
          ]
        }
      }
    }
  }
}

Step 5: Check if you need additional consents

Due to the nature of some of our datasources, you may need to obtain consent from your customer for their data to be sent to that particular source. You may or may not be configured to use any of these datasources, so it is recommended to run a Get Consents request for all the countries obtained in step 1. This will give you a list of datasources requiring additional consents in each country. If applicable, you can obtain these special consents from your customer, and then provide them in the ConsentForDataSources field of the Verify request. To know more about this topic, click here.

Request

GET <<endpoint>>/v3/configuration/consents/{packageID}/{countryCode}/detail
Authorization: OAuth
//Example Username: JoeNapoli_API_Demo, Example Password: 05uZuPRCyPi!6
var truliooClient = new TruliooApiClient("JoeNapoli_API_Demo", "05uZuPRCyPi!6");
IEnumerable<string> e = await truliooClient.Configuration
    .GetConsentsAsync("AU", "Identity Verification");
//Example Username: JoeNapoli_API_Demo, Example Password: 05uZuPRCyPi!6
ApiClient apiClient = new ApiClient();
apiClient.setUsername("JoeNapoli_API_Demo");
apiClient.setPassword("05uZuPRCyPi!6");
ConfigurationApi configurationClient = new ConfigurationApi(apiClient);

//getConsents
List<String> result = configurationClient.getConsents("AU", "Identity Verification");

//getConsentsAsync
configurationClient.getConsentsAsync("AU", "Identity Verification", new ApiCallback<List<String>>() {
    @Override
    public void onFailure(ApiException e, int statusCode, Map<String, List<String>> responseHeaders) {
        Logger.getLogger(SdkJavaV1Sample.class.getName()).log(Level.SEVERE, null, e);
    }
    @Override
    public void onSuccess(List<String> result, int statusCode, Map<String, List<String>> responseHeaders) {
        System.out.println(result);
    }
    @Override
    public void onUploadProgress(long bytesWritten, long contentLength, boolean done) {
        //To change body of generated methods, choose Tools | Templates.
    }
    @Override
    public void onDownloadProgress(long bytesRead, long contentLength, boolean done) {
        //To change body of generated methods, choose Tools | Templates.
    }
});

Response

[
    "Birth Registry",
    "Visa Verification",
    "DVS ImmiCard Search",
    "DVS Citizenship Certificate Search",
    "Credit Agency"
]

Step 6: Verify Request

Once steps 1 through 5 have been completed, you should have everything needed to carry out a Verify request. Using one of the country codes from step 3, the fields from step 4, and any necessary consents from step 5, you can now run the following Request Recipe.

There's a lot of information provided in Request, which is broken down in full detail in the next section of this guide Understanding a Verify Response. For now, the first things to pay attention to are:

  • AcceptTruliooTermsAndConditions: This flag indicates that you accept Trulioo terms and conditions. The verification request will be executed only if the value of this field is passed as 'true'.

  • CleansedAddress: GlobalGateway includes a service to check address data and ensure it is correct and all necessary address fields are provided. In general, these cleansed addresses have a higher likelihood of producing a match result. Contact Trulioo Support if you are interested in configuring address cleansing for your account. Once the address cleansing is configured, set this field to true to receive address cleanse information.

  • PackageId: The Package ID to run the transaction under. This will be provided by Trulioo Support.


Step 7: Verify Response

Explanation of Response Fields

  • RecordStatus: This field is the overall value of the verification. Match means that the individual has been verified, any other value means that they have not.

  • DatasourceResults: This contains an array of results from every datasource your verification has been run against. Every datasource result has the same standard format, so it's easy to parse results from many sources at once.


By following a few simple setup steps, you are now able to send a verification request for any identity and receive a set of rich, detailed results. GlobalGateway provides the overall match signal (RecordStatus), individual match signals for each field underneath the datasource results (Status), any additional information returned from a datasource (AppendedFields), and the rule being used to judge whether an individual is verified (Rule). This gives you full transparency into the results of all your verification requests.

🚧

Need help?

Reach out to our Trulioo Support for any technical assistance.