Document Validation via API

Learn how to perform a document validation using our API, understanding the essential API endpoints, responses and errors.

Prerequisites

Before you begin, make sure you have the following:

1. Truora API-Key: This key grants access to our services. If you don’t have one already, set up an account and then go to Authentication to obtain your Truora API-key.

2. A valid ID: You’ll need a valid identification document to run the document validation.

3. 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.

NOTE: Truora provides a Postman collection online that includes the necessary tools to simplify the testing process.

Create Validation

Setup main Request Headers and Body

To configure the main request headers and body in Postman, follow these steps:

1. Create a POST request to https://api.validations.truora.com/v1/validations.
2. Click the Headers tab, create a new key named Truora-API-Key and set the Value to the Truora API-key you got previously.
3. Create a new key named Content-Type and set its value to application/x-www-form-urlencoded.

Setup required keys for the request

In Postman, click the Body tab and tick the x-www-form-urlencoded box. Next, set up the following keys:

1. type: [Required]. Indicates the type of validation to be performed. Set this value to document-validation
2. country: [Required]. Set the country of the document being validated:
   • CO for Colombia
   • CL for Chile
   • MX for Mexico
   • PE for Peru
   • BR for Brazil
   • CR for Costa Rica
   • VE for Venezuela
   • PA for Panama
   • ALL for passport
3. document_type: [Required]. Set this value to the type of document been validated:
   • national-id
   • passport
   • foreign-id
   • pep
   • ppt
   • driver-license
   • invoice
   • identity-card
4. user_authorized: [Required]. This indicates that you have the authorization of the person to be verified. This is mandatory in order to comply with data protection laws. Value must be set to true in order to perform the validation.
5. account_id: [Optional]. Unique user identifier for tracking validations of a user.*
6. custom_type: [Optional]. When specified, indicates the name of the custom type check when a background check linked to this validation is desired.**

*Only Account IDs following the regex pattern [a-zA-Z0-9_.-]+ are supported (for more details visit validators main concepts ). While optional, it’s recommended to provide a unique identifier for accurate monitoring and data isolation between users. Utilize a library for managing user identifiers (User ID) based on your programming language or development framework. Avoid using repetitive number sequences. If left empty, an automatic account_id will be generated.

** Every time you run a document validation our system runs a default Background check (no extra charge), which will only verify datasets related to identity and excludes criminal, legal, international or any other dataset types. If you wish customize the default behavior, use this field to conduct a Background Check with a Custom Type.

• Note 1: You must have enabled the background check (BGC) product to use Custom Type. For each document validation request with a custom background check, you will be charged for it with the BGC price.
• Note 2: If you create a Custom Type, you must add the dataset dataset_document_validation key with a value of zero.
• You will identify within the Get Validation response that a check_id has been created.

Send the POST request

After setting the keys in Postman, click Send to initiate the request. The API will respond with a status code of 200, along with a response similar to the following:

    {
        "validation_id": "VLDXXXXXXXXXXXXXXXXXXXXXXXXXX",
        "ip_address": "186.168.XXX.XXX",
        "account_id": "ACCXXXXXXXXXXXXXXXXXXXXXXXXXX",
        "type": "document-validation",
        "validation_status": "pending",
        "creation_date": "2024-04-16T15:11:21.102178964Z",
        "instructions": {
            "front_url": "https://file.upload.url/TCI70HXSXXXXXXXXXXXXXXXXXX/ACCXXXXXXXXXX/CO/national-id/DCRXXXXXXXXXXXXXXXXXXXXXX_front.png?max-size=31457280&method=PUT&retries=1&token=3f4a03ce085ca32380b8653e24c6e1f379f599fac05e2f9241411625930a36ac&Expires=1713280581&Signature=eFPiClflEer4rzLRIxPbw5Ht2-A8nbGM4pVhP3wQoafxdLLi1E-asUBHMsKwYytB3FCfIXywIVQqZ3c0THwvgtmtiI62tQXa183LdvUbSRpHPRD3FmR6nu7SnrpjHwl2oq6WnOUiwOjupcngmBKzXFgAS2QdNOL-nAj310kYzSA~OqIuIxjv6cRdwi3gVwdnbUw4UDAb2nD7GWOTROdEib8dUR3z6KJtTSi1DQUzqDP1TmYnwX~erpaWN5nVUEU3chOsxHEQfPUeKRxIEGjiTMz-XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX__&Key-Pair-Id=APKXXXXXXXXXXXXXXXXXXX",
            "reverse_url": "https://file.upload.url/TCI70HXSXXXXXXXXXXXXXXXXXX/ACCXXXXXXXXXX/CO/national-id/DCRXXXXXXXXXXXXXXXXXXXXXX_reverse.png?max-size=31457280&method=PUT&retries=1&token=XXXXXXXXXXXXXXXXXX&Expires=1713280581&Signature=HDgNSLAm-FFziWe35FepQg2iNbu2NEjRo13GQV1oTSieACJ-7jkf1ascXfZEYcHNSXUy3tJt~TO7DU9UehYkp1q8bINOP9R0886xmHk3d04lsA41J1WO7x0cf3v6~vaBwYZ-1o8jPhs2ZpFesDQ3u566UbVlDnFdk7c7vc-IvW7vwkbQn-UGudz4rh3Puz8C2FQBvFddO5yRh6SsAFkRfTvmEe4VEe8O6xs0kz8NZ31sTw1Gz3XOY0w6ER1VEVqcNCn0POplYGjkdWyiNivAEgJlXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX__&Key-Pair-Id=APKXXXXXXXXXXXXXXXXXXX"
        }
    }

• validation_id: Unique identifier of the validation.

• account_id: Unique identifier of the user.

• type: Type of validation performed.

• validation_status: The current status of the validation will be pending until the images are submitted. After performing the validation, the status could change to:
  
  - success: Indicates a successful validation.
  - failure: Indicates an unsuccessful validation or may also occur due to an internal error.
  
  

• creation_date: Date and time of validation creation.

• front_url: URL where the image of the front side of the identification document should be sent.

• reverse_url: URL where the image of the reverse side of the identification document should be sent.

Upload document picture

Images must be submitted through a PUT request to the URLs generated in the previous step, selecting the Binary type in the Body. Make the following requests to upload the front and back of the document:

1. PUT /{front_url}: Upload the front document picture by making a PUT request using the URL returned from the Create validation step.
2. PUT /{reverse_url}: Upload the reverse document picture by making a PUT request using the URL returned from the Create validation step.

NOTE: It si recommended to upload the document photo horizontally. JPEG, JPG and PNG are the only supported formats and the max allowed size is 30MB. For more information on how to take a good picture of the document, please visit the Tips for document photo* section.

Once successfully uploaded, the response code for each of these requests should be 200, as follows:

{
    "code": 10200,
    "http_code": 200,
    "message": "Successfully uploaded"
}

Get Validation

This API endpoint allows you to retrieve the current status and information of a validation. The validation_status begins as pending. Upon completion, the validation can either be success or failure.

To obtain the validation results, send a GET request to the endpoint https://api.validations.truora.com/v1/validations/{{validation_id}}, where validation_id is the identifier returned in the Create validation request.

Once executed, if the validation is still processing, validation_status will be pending and you will receive a response similar to the following:

{
    "validation_id": "VLDXXXXXXXXXXXXXXXXXXXXXXX",
    "ip_address": "186.168.XXX.XXX",
    "account_id": "ACCXXXXXXXXXXXXXXXXXXXXXXXXX",
    "type": "document-validation",
    "validation_status": "pending",
    "creation_date": "2024-04-16T19:40:38.133594051Z",
    "attachment_status": "pending"
}

When the validation is completed successfully, validation_status will be success and you will receive a response similar to the following:

{
    "validation_id": "VLDXXXXXXXXXXXXXXXXXXXXX",
    "ip_address": "186.168.XXX.XXX",
    "account_id": "ACCXXXXXXXXXXXXXXXXXXXXXXXX",
    "type": "document-validation",
    "validation_status": "success",
    "creation_date": "2024-04-16T19:43:36.6234554Z",
    "details": {
        "background_check": {
            "check_id": "CHKXXXXXXXXXXXXXXXXXXXXX",
            "check_url": "https://api.checks.truora.com/v1/checks/CHKXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
        },
        "document_details": {
            "birth_place": "CALI (VALLE)",
            "client_id": "TCI70HXSXXXXXXXXXXXXXXXXXX",
            "country": "CO",
            "creation_date": "2024-04-16T19:43:36.566657559Z",
            "date_of_birth": "1992-10-20T00:00:00Z",
            "doc_id": "DCRXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
            "document_number": "16XXXXXX",
            "document_type": "national-id",
            "expedition_place": "CALI",
            "gender": "male",
            "height": "1.70",
            "issue_date": "2010-10-29T00:00:00Z",
            "last_name": "DOE",
            "mime_type": "image/jpeg",
            "name": "JHON",
            "national_registrar": "XXXXXXXX XXXXX XXXXXX",
            "production_data": "P-310xxx-651xxxxx-M-001xxxxxx-200xxxxxx",
            "rh": "O-",
            "update_date": "2024-04-16T19:43:53.667096216Z"
        },
        "document_validations": {
            "data_consistency": [
                {
                    "validation_name": "Validation of date of birth",
                    "result": "valid",
                    "validation_type": "date-of-birth-validation",
                    "message": "The date of birth is valid",
                    "manually_reviewed": false,
                    "created_at": "2024-04-16T19:43:53.919936469Z"
                },
                {
                    "validation_name": "Validation of Document Number",
                    "result": "valid",
                    "validation_type": "document-number-validation",
                    "message": "The document has a valid document number or NUIP",
                    "manually_reviewed": false,
                    "created_at": "2024-04-16T19:43:53.919932949Z"
                }
            ],
            "government_database": [
                {
                    "validation_name": "Validation of Government Database - Registraduría",
                    "result": "valid",
                    "validation_type": "government-database-digital-validation-certificate-cedula",
                    "message": "Document is current and registered in main identity database",
                    "manually_reviewed": false,
                    "created_at": "2024-04-16T19:43:55.813688116Z"
                }
            ],
            "image_analysis": [
                {
                    "validation_name": "Validation of document picture alterations",
                    "result": "valid",
                    "validation_type": "fake-picture-validation",
                    "message": "Picture alterations were not found",
                    "manually_reviewed": false,
                    "created_at": "2024-04-16T19:43:57.352571532Z"
                },
                {
                    "validation_name": "Validation of document text alterations",
                    "result": "valid",
                    "validation_type": "fake-text-validation",
                    "message": "Text alterations were not found in picture",
                    "manually_reviewed": false,
                    "created_at": "2024-04-16T19:43:59.574334117Z"
                }
            ],
            "photocopy_analysis": [
                {
                    "validation_name": "Validation of Photocopy Analysis",
                    "result": "valid",
                    "validation_type": "photocopy-validation",
                    "message": "The document is not a photocopy",
                    "manually_reviewed": false,
                    "created_at": "2024-04-16T19:43:56.868477206Z"
                },
                {
                    "validation_name": "Validation of color photocopy",
                    "result": "valid",
                    "validation_type": "photocopy-validation-color",
                    "message": "The document is not a color photocopy",
                    "manually_reviewed": false,
                    "created_at": "2024-04-16T19:43:54.40342551Z"
                }
            ],
            "photo_of_photo": [
                {
                    "validation_name": "Validation of photo of photo",
                    "result": "valid",
                    "validation_type": "photo-of-photo-validation",
                    "message": "The document is not a photo of photo",
                    "manually_reviewed": false,
                    "created_at": "2024-04-16T19:43:54.286366479Z"
                }
            ]
        }
    },
    "attachment_status": "valid"
}

You can identify the following information in the response:

Main validation data:

• validation_id: Unique identifier of the validation.
• ip_address: IP address of the device from which the validation was performed.
• account_id: Unique identifier of the user.
• type: Type of validation performed.
• validation_status: The current status of the validation will be pending until the images are submitted. After performing the validation, the status could change to:
  
  - success: Indicates a successful validation.
  - failure: Indicates an unsuccessful validation or may also occur due to an internal error.
  
  
• creation_date: Date and time of validation creation.

Background check: Information related to the default or custom background check conducted to validate the document:

• check_id: Identifier of the performed checks.
• check_url: URL to access the details of the background check.

Document details: Extracted document information through OCR.

Declined and Expired reasons

Whenever a validation fails due to inconsistencies in the validation process or expires in the validation process, the API provides a reason to indicate why the validation was declined or expired:

• To learn more about the possible declined reasons, please visit the Declined Reasons section.
• To learn more about the possible expired reason, please visit Expired Reasons section.

Additional configurations

You can configure other parameters to improve the behavior of the validators and the user experience. Please see Config Validator section for more information on customization.

Getting results automatically (Webhooks)

To get validation results automatically, you must subscribe webhooks. For more information, please see Webhooks section.