This simple tutorial guides you through some basic steps to test your connectivity, authenticate, request some data, and verify your first individual through the Qual-ID API. Each step is simple, building upon the one before it, letting you get up and running with a full identity verification solution in no time.

If you would like to test the API calls yourself, you will find a Postman collection under the downloads tab. After importing the collection into Postman, edit the collection to insert your Qual-ID credentials in the Variables associated with the collection. You should then be able to run all he calls.

Table of contents

• Prerequisites
• Step 1 - Say Hello
• Step 2 - Test Authentication
• Step 3 - Get Country Codes
• Step 4 - Get Fields
• Step 5 - Get Consents
• Step 6 - Verify
  • Understanding a Verify Response

Prerequisites

Credentials

Qual-ID requires product specific credentials, i.e. a Qual-ID username and password. The only action you can execute without credentials is step 1.

As of step 2 credentials are required. If you do not have any, please contact your local Refinitiv account manager.

Step 1 - Say Hello

In order to test your connectivity to the service, you can simply call the sayhello endpoint:

You should receive a successful response with the value you sent in the request echoed back to you:

You can try sending a different string instead of "Joe Napoli" to see what happens.

If you receive an error message, first check the syntax of the endpoint and try again. If that does not work then test your internet connectivity, check that DNS resolution works for the globaldatacompany.com domain name, and ensure your firewalls or proxies do not block access.

Step 2 - Test Authentication

As stated in the prerequisites section, you should have a Qual-ID user account with username and password.

All API calls require an Authorization header, containing your ACCESS_TOKEN, as illustrated below. To generate the ACCESS_TOKEN portion of the header, combine your username and password into username:password and run the resulting string through Base64 encryption. Alternatively, you can use a program such as SOAPUI or Postman to construct the authorization header for you.

You can use the testauthentication endpoint to check that they are working. The only thing you need to provide in this request is the authorization header:

Request

Response

You should receive a response containing your username:

Troubleshooting

Here are the most common reasons for an error response:

• The Authorization header isn't set properly. It should be a Base64 -encrypted Basic Authentication header.
• The spelling is incorrect.
• Invalid credentials were used.

Check for typos, and ensure that you are setting the Authorization header correctly, using a Qual-ID specific username and password (Base64 encrypted).

For more details on error handling, refer to the separate tutorial on Troubleshooting.

Step 3 - Get Country Codes

The Qual-ID API is structured to make calls by country. Your organization's contract with Qual-ID defines what countries are available. If you are not sure what countries are configured for your account, you can use an endpoint to retrieve this information at any time. Simply run the following request to receive the full list of country codes available to your account:

Request

Note: the authorization header must be present in all API calls. It is described under Step 2.

Response

If successful, the response contains a JSON Array of 2 letter country codes following ISO 3166.

Step 4 - Get Fields

Once you know what country codes are valid for your account, you can make a Get Fields request. This returns a detailed list of all of the fields that you need to provide to verify an identity in a given country. These fields vary based on country, as well as your organization's global account configuration:

Request

Response

In the JSON response you see each and every field available for the verification of an individual in Australia (ISO 2 code: AU). The response lists the required fields, with a short description of each, and the associated data type. In Step 6 - Verify, we shall use the values obtained here to create a successful verification request.

Step 5 - Get 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 3. This will give you a list of datasources requiring additionalconsents 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.

Request

Response

The returned JSON array of strings contains the names of the datasources requiring additional consent. Once consent is given from your customer for these datasources, it must be provided in the Verify request so that the datasource can be called.

Step 6 - Verify

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 a Verify request.

Note on Sandbox Accounts: if you are configured for a sandbox account, make sure to call Get Test Entities to get test data for a country you want to try:

Sandbox accounts only use these test entities, trying to verify with any other data will result in no matches being found.

Request

In Step 4 we retrieved the list of fields required for our request.  A few more fields need to be added:

• AcceptTruliooTermsAndConditions: this flag indicates that you accept our terms and conditions. The verification request will be executed only if the value of this field is passed as 'true'. 
• CleansedAddress: Qual-ID provides 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 you local account manager if you are interested in configuring address cleansing for your account. Once address cleansing is configured, set this field to true to receive address cleanse information. 
• ConfigurationName: for now this should be hard-coded to "Identity Verification".

Request body:

Response

There is a lot of information provided in the JSON response, which will be broken down in full detail in the next section Understanding a Verify Response. For now, the first things to pay attention to are:

• 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 is easy to parse results from many sources at once.

By following a few simple set up steps, you are now able to send a verification request for any identity and receive a set of rich, detailed results. Qual-ID 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.

Understanding a Verify Response

There is a lot of information in a Verify response. This section helps you understand what that information means, and how to use it so you can get the most out of your verification results.

TransactionRecordID

This is the unique ID for this particular verification. You can use this for your own reference, or in the Get Transaction Record method to review a past transaction:

You should also use it in case you need to contact MyRefinitiv about a verification result.

Datasource

Qual-ID provides you with a gateway to over 200 global datasources. Your verification response will contain an array of DatasourceResult objects for each datasource configured on your account. Each DatasourceResult contains a DatasourceName, and a DatasourceFields sub-array, which indicates the match status for each field sent to that datasource.

Some of the more common Datasources are:

• 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 consumer credit history in that country.
• Electoral Roll: government collated and issued data, for all citizens in a country, who are enrolled to vote.
• Government Issued: government collated and issued databases, or information. This includes national insurance numbers, driver’s licenses and passports.
• National ID: government collated and issued data for countries which have a singular, 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 global passport machine readable zone (MRZ), which specifies that is it valid and also includes the individual’s name and date-of-birth.

An example DatasourceResults array:

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 Datasource Field 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:

• 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, Qual-ID 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 is not 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 are trying to verify is deceased. This information is included in the AppendedFields section for that datasource (underneath the DatasourceResults object):

Errors

The DatasourceResults object contains a section called Errors, which informs you 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. An example is when a field is 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 can be ignored by the remaining datasources, which will return match signals for all other fields.

Rule

At the end of the verification results is a Rule object, which describes how Qual-ID used the match signals in the datasource result fields to evaluate whether or not the identity was verified. You can work with 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 a number of 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 will be returned as a match (see below).

Verification

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 (i.e. one or more datasources provided match signals that satisfied the verification rule). A RecordStatus of nomatch means the identity could not be verified.

Text

The rich detail provided by Qual-ID's response allows you to make your application's own 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 own field-by-field matching.