Filter

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. Optionally, you can create the key called custom_input. This field accepts a string of up to 128 characters and can be used to send additional information in the Background Check. You can use it to send any relevant information for your operation or use case.
  15. Click Send. The API returns a response in JSON format. Copy the check_id from the response.
  16. Create a GET request to https://api.checks.truora.com/v1/checks/{{check_id}}.
  17. Replace {{check_id}} with the check_id from the response.
  18. Click Send. The API returns a response in JSON format containing the check result.
  19. 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.
  20. 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.
Create Check

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

Check response

{
    "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.
Poll Check

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