Quality Assurance

After your integration is complete, here are a few things to check to make sure you are off to a good start.

Check all possible output scenarios

  • Identity records returned: If your search is successful, one or more identity records will be returned to you. While we will always return a full verified name, date of birth, address, and SSN when possible, some attributes may just not be available on some users. This will result in partial records being returned.
  • No hit: In the event of no identity records being found during a search, nothing will be returned, and the “included” object will be empty. Because there is no data to work with, running an assessment will not be possible, and the dashboard will display N/A where the score would typically be found.
  • Partial returns and their impact on assessment: Overall scores are calculated by averaging the subscores of all data points you provided. If you provide an attribute, but our records don’t contain the corresponding attribute, no scoring will happen for that specific data point. (Example: You submit name + phone + DOB + SSN, but we return only name + phone + SSN + Address. You would get a score on all attributes that are in both the input and output. So while you may expect the overall score to be based on Name + Phone + DOB + SSN, it will be based on Name + Phone + SSN). This is something to be mindful of, as it will affect the weight of each attribute, and the impact they have on the overall score.
  • Request time out: Searches typically only take one or two seconds but, depending on data provider availability, in certain circumstances it can take longer. To account for this while still being fault-tolerant, if the identity search creation takes longer than 5 seconds, the search will be entered into a search queue which can be retrieved when it is complete. See our guide for verifying with phone.

Secure key management

Do not embed API keys directly in code: API keys that are embedded in code can be accidentally exposed to the public, for example, if you forget to remove the keys from code that you share. Instead of embedding your API keys in your applications, store them in environment variables or in files outside of your application’s source tree.

Do not store API keys in files inside your application’s source tree: If you store API keys in files, keep the files outside your application’s source tree to help ensure your keys do not end up in your source code control system. This is particularly important if you use a public source code management system such as GitHub.

Restrict your API keys to be used by only the IP addresses, referrer URLs, and mobile apps that need them: By restricting the IP addresses, referrer URLs, and mobile apps that can use each key, you can reduce the impact of a compromised API key.

Rate limiting

Rate limiting protects your platform from overuse by limiting how often each user can call the API. This protects you from inadvertent or malicious overuse. Without rate limiting, each user may request as often as they like, which can lead to spikes of requests that starve other consumers, and more importantly incur large charges. When rate limiting is enabled, users are limited to a fixed number of requests for a given time period.

Data validation

Having comprehensive data validation checks in place will ensure that your API calls are successful and will reduce the number of instances where you have to handle error messages.

This will also enable you to give real time feedback to your users on wrong inputs, which will improve their experience. It’s an easy way to maximize your match rates, and ultimately your conversion rates.

We recommend testing with invalid SSNs or phone numbers, to make sure that you properly handle validation errors we return.

Here are some validation checks we recommend having in place:

  1. Name: It is best to explicitly ask your users to input their legal name, as to avoid the risk of a failed verification due to nicknames being entered for example.
  2. Date of birth: These simple checks will allow you to immediately filter out invalid dates of birth:
    • 1 =< Day =< 31
    • 1 =< Month =< 12
    • 1900 =< Year =< Current year
  3. Address: Addresses should be standardized according to the USPS standards
  4. Phone number: Phone numbers should be properly formatted, according to the E.164 standard.

Proper profile use

Profile IDs are meant to create a logical link between all searches and assessments that relate to a unique individual. A unique ID should be created through the /profiles endpoint for each new individual you are looking to verify.

Proper use of Profile IDs will allow for calculation of metrics such as your “true hit rate”, which reflects the percentage of applicants for which at least one search resulted in identity records being returned. This is helpful since calculating the percentage of overall searches that resulted in a hit, will not accurately reflect the performance of Cognito (It can take more than one search attempt to get a hit on a person).

Importance of assessment

The /identity_searches endpoint is meant to search for, and return a list of records that match the input attributes provided by the user. After running a search and retrieving records, no comparison analysis has been done yet, and the first record returned cannot be considered to be the highest matching, or best record. It is important to use the /identity_assessments endpoint, to compare the data provided by the user against the data Cognito has access to and returns. This will result in each identity record and their individual attributes, being scored, making it easy to surface the best match.

Data logging

We recommend that you store every profile ID created on your end, along with the corresponding user information, and any associated identity search ID and assessment ID. This will allow you to later retrieve any identity search or identity assessment from the Cognito API with a simple GET request.

GET https://api.cognitohq.com/identity_searches/idnsch_

GET https://api.cognitohq.com/identity_assessments/idnasm_

Alternatively, you can also retrieve all identity searches associated with a given profile ID this way:

GET https://api.cognitohq.com/profiles/prf_kj7G7uh0aQ23/identity_searches

Limit the number of test searches

Mock the test API responses Cognito returns,  so you don’t need to run sandbox requests whenever you run your test suite.

Data access and handling controls

Make sure you have the proper internal controls in place, to ensure that you and all employees only use the data we returned for its intended and allowed use.

If you have any questions, or need additional support, please reach out to support@cognitohq.com and we’ll be happy to help.