Creating a Background Check

Let’s make our first background check to help illustrate the usage of our API.

Prerequisites

To create a check, the following elements are needed:

• Truora API-Key: Grants access to our services. If you don’t have one already go to Set up an account to learn how to get your Truora API-key.
• A valid ID: from the person, vehicle, or company to run the background check.
• Postman: Use Postman or any other collaboration tool for API development. Although it is not required to perform the integration, it will help perform tests along the way.

Create a Check - Using an API Platform like Postman

Follow these steps to perform your first background check for a person:

1. Create a POST request to https://api.checks.truora.com/v1/checks in Postman.
2. Click the Headers tab. Create a new key named Truora-API-Key.
3. Set the Value for Truora-API-Key as your Truora API-key.
4. Create a new key named Content-Type.
5. Set the value for Content-Type as application/x-www-form-urlencoded.
6. Click the Body tab. Tick the x-www-form-urlencoded box.
7. Create a new key named national_id.
8. Set the value for national_id as your ID card number (numbers only, CC for Colombia, CURP for Mexico, DNI for Peru and so on).
9. Create a new key named country and set its value to your country:
   • ALL for International Lists
   • BR for Brazil
   • CO for Colombia
   • CL for Chile
   • CR for Costa Rica
   • MX for Mexico
   • PE for Peru
10. Create a new key named type and set its value to person (when you create a Custom Type check and want to use it, you must set the value to the name of your Custom Type instead).
11. For background checks in Brazil, create a new key named date_of_birth and set its value to the date of birth of the person to be checked in format yyyy-mm-dd.
12. Create a new key named user_authorized and set its value to true. This indicates that you have the authorization of the person to be checked. This is mandatory in order to comply with data protection laws.
13. Create a new key named force_creation and set its value to true. This forces the creation of a new check rather than searching for a previous performed check.
14. Click Send. The API returns a response in JSON format. Copy the check_id from the response.
15. Create a GET request to https://api.checks.truora.com/v1/checks/{{check_id}}.
16. Replace {{check_id}} with the check_id from the response.
17. Click Send. The API returns a response in JSON format containing the check result.
18. Click Send again to refresh the response in case some results are missing. The time it takes for results to be ready varies between countries and depends on the availability of the databases we use.
19. Additionally, You can look at the check details by creating a GET request to https://api.checks.truora.com/v1/checks/{check_id}/details and replacing {{check_id}} with the check_id from the response.

Create a Check - Using an example Script (Javascript or Python)

Calling the endpoint

In the following example, we will run a background check of the type person for the country CO (Colombia).

• We will make a POST call to the https://api.checks.truora.com/v1/checks endpoint to create the check (More info in the API reference).
• Then we will poll the result by making GET requests to https://api.checks.truora.com/v1/checks/{{check_id}}, replacing {{check_id}} with the check_id from the previous POST response.

Lets start:

You can copy the following script (select Javascript or Python) to test the use of this endpoint:

• Remember: The api_key value must be set with the Truora API-key you got in the first steps of this guide.

const axios = require('axios');

const api_url = 'https://api.checks.truora.com/v1/checks';
const api_key = 'YOUR_TRUORA_API_KEY'; // Replace with your actual Truora API key

const headers = {
  'Truora-API-Key': api_key,
  'Content-Type': 'application/x-www-form-urlencoded',
};

const params = new URLSearchParams({
  user_authorized: 'true',
  force_creation: 'true',
  type: 'person',
  national_id: '10000000',
  country: 'CO',
});

axios
  .post(api_url, params.toString(), { headers })
  .then((response) => {
    if (response.status === 200) {
      console.log('POST request successful.');
      console.log('Response data:');
      console.log(response.data);
    } else {
      console.log(`POST request failed with status code: ${response.status}`);
      console.log('Response data:');
      console.log(response.data);
    }
  })
  .catch((error) => {
    console.error(`Error: ${error.message}`);
  });

import requests

api_url = "https://api.checks.truora.com/v1/checks"
api_key = "YOUR_TRUORA_API_KEY"   # Replace with your actual Truora API key

headers = {
    "Truora-API-Key": api_key,
    "Content-Type": "application/x-www-form-urlencoded"
}

params = {
        "user_authorized": "true",
        "force_creation": "true",
        "type": "person",
        "national_id": "10000000",
        "country": "CO",
}

response = requests.post(api_url, data=params, headers=headers)

if response.status_code == 200:
    print("POST request successful.")
    print("Response data:")
    print(response.text)
else:
    print(f"POST request failed with status code: {response.status_code}")
    print("Response data:")
    print(response.text)

After the Check is created, you will receive a response similar to the following, in JSON format:

{
    "check": {
        "check_id": "CHK3815eafb4ec7yd4cd3i3b5f4093f7a2c",
        "country": "CO",
        "creation_date": "2023-09-11T16:49:11.903834331Z",
        "name_score": 0,
        "id_score": 0,
        "score": -1,
        "status": "not_started",
        "update_date": "2023-09-11T16:49:11.944670023Z",
        "billing_hub": "hub",
        "national_id": "10000000",
        "type": "person"
    },
    "details": "/v1/checks/CHK3815eafb4ec7yd4cd3i3b5f4093f7a2c/details",
    "self": "/v1/checks/CHK3815eafb4ec7yd4cd3i3b5f4093f7a2c"
}

• Note: Copy the check_id value from your response as you will need it in the next step.

Polling the result

The most important field in the Checks response is status. It’ll always return not_started upon creation but as the checks moves to the different stages of its lifecycle, it will be updated accordingly. It is important then to poll the result of the Check so you can verify when the Check has finished according to the status value.

The following sample script will poll the request until the status is completed, but keep in mind that other final statuses are also possible. Refer to the “Check Statuses” section in this guide for more information.

• Remember:
  • The api_key value must be set with the Truora API-key you got in the first steps of this guide.
  • The check_id value must be set with the check_id you got in the response of the previous step.

const axios = require('axios');
const { sleep } = require('sleep');

const api_url = 'https://api.checks.truora.com/v1/checks/';
const api_key = 'YOUR_TRUORA_API_KEY'; // Replace with your actual Truora API key
const checkId = 'CHK3815eafb4ec7yd4cd3i3b5f4093f7a2c'; // Replace with your check ID

const headers = {
  'Truora-API-Key': api_key,
  'Content-Type': 'application/x-www-form-urlencoded',
};

let duration = 0;

async function checkStatus() {
  while (true) {
    try {
      const response = await axios.get(api_url + checkId, { headers });

      if (response.status !== 200) {
        console.log(`GET request failed with status code: ${response.status}`);
        console.log('Response data:');
        break;
      }

      const check = response.data;

      if (check.check.status === 'completed') {
        console.log('Check finished');
        break;
      }

      if (duration > 60 * 5) {
        console.log('Check timeout after 5 minutes');
        break;
      }

      console.log('Check not completed, retrying in 5 seconds');
      await sleep(5);
      duration += 5;
    } catch (error) {
      console.error(`Error: ${error.message}`);
      break;
    }
  }
}

checkStatus();

import requests
import time

api_url = "https://api.checks.truora.com/v1/checks/"
api_key = "YOUR_TRUORA_API_KEY"   # replace this variable with your api key
check_id = "CHK3815eafb4ec7yd4cd3i3b5f4093f7a2c"

headers = {
    "Truora-API-Key": api_key
}

duration = 0

while True:
    response = requests.get(api_url+check_id, headers=headers)
    if response.status_code != 200:
        print(f"POST request failed with status code: {response.status_code}")
        print("Response data:")
        break

    check = response.json()
    if check['check']['status'] == 'completed':
        print("Check finished")
        break

    if duration > 60*5:
        print("Check timeout after 5 minutes")
        break

    print("Check not completed, retrying in 5 seconds")
    time.sleep(5)
    duration += 5

Once the Check has completed now you can use the score of your Check Response to make a decision.