Home / Validators / Document validation API
Filter

Document Validation via API

Product: Validators

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.

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

https://www.postman.com/truora-api-docs/workspace/truora-api-docs/collection/26510995-ad2e7c71-b39a-40e4-8322-ae3316160634?ctx=documentation

1. Create validation

Setup main Request Headers and Body

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

  1. Create a POST request to the endpoint https://api.validations.truora.com/v1/validations.
  2. Set the Headers
    • Truora-API-Key: enter the value obtained in the step of get Truora API-key.
    • Content-Type: the value should be application/x-www-form-urlencoded.
  3. Set required values for the request body
    • type [Required]: Indicates the type of validation to be performed. Set this value to document-validation
    • 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.
    • country [Required]: Allowed: CO |CL | MX| PE | BR | CR | VE | PA | ALL. Set the country of the document being validated.
      Use ALL when document_type is set to passport.
      For BR,CR, VE, PA please ask sales team.
    • document_type [Required]: Allowed: national-id | foreign-id | driver-license | passport | identity-card| rut | ppt | invoice | picture-id | record | cnh . Set this value to the type of document been validated. For ppt please ask sales team.
      Refer to Appendix 1: Supported Document Types for a complete reference of supported document types, applicable countries and document front/reverse picture requirements.
    • account_id [Optional]: Unique user identifier for tracking validations of a user.*
    • custom_type [Optional]: When specified, indicates the name of the custom type check when a background check linked to this validation is desired.**
    • retry_of_id [Required if you have active retries and want to retry a previous validation]: Refers to the validation_id of the failed validation.
    • timeout [Optional]: The time, in seconds, users will have to complete the validation. If omitted, the timeout from the client’s config will be used. The default value is 300 seconds (5 minutes), with a maximum of 21600 seconds (6 hours).

*Only Account IDs following the regex pattern [a-zA-Z0-9_.-]+ are supported. 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. Please go to Create an Account ID to learn more about it.

** 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 Create validation request you just created. You will receive a response similar to the following:

POST
/v1/validations 

    {
        "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"
        }
    }
Among other details, the following information may be identified in the response:

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

2. Upload document picture

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

  • PUT {{front_url}}: Upload the front document picture by making a PUT request using the URL returned from the Create validation step.

  • PUT {{reverse_url}}: Upload the reverse document picture by making a PUT request using the URL returned from the Create validation step.

    NOTE 1: It is recommended to upload the document photo horizontally. For more information on how to take a good picture of the document, please visit the Tips for document photo section.

    • Supported formats are JPEG, JPG and PNG, with a maximum allowed size of 30MB.
    • PDF format is allowed when document_type is set to invoice (Only allowed for Mexico).

    NOTE 2: Not all document types will requiere both front and reverse pictures. Please refer to Appendix 1: Supported Document Types for a complete reference of supported document types, applicable countries and document front/reverse picture requirements.

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

PUT
{{front_url}} 

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

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

3. Get Validation

The Get validation request allows you to retrieve the current status and results 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.
  • If you want to obtain links the document pictures, use the query parameter show_details with the value of true in the request.

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

GET
/v1/validations/{{validation_id}} 

{
    "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:

GET
/v1/validations/{{validation_id}} 

{
    "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",
    "remaining_retries": 2
}

If you send the query parameter show_details with value true in the Get validation request, you will receive the response with the links of the uploaded document pictures in the field input_files. These links will be valid for 15 minutes:

GET
/v1/validations/{{validation_id}}?show_details=true 

{
    "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"
                }
            ]
        }
    },
    "validation_inputs": {
        "country": "CO",
        "document_type": "national-id"
    },
    "user_response": {
        "input_files": [
            "https://truora-files/XXXXXX",
            "https://truora-files/XXYYYY",
            "https://truora-files/XXYYZZ"
        ]
    },
    "validation_id": "VLDXXXXXXXXXXXXXXXXX",
    "ip_address": "186.168.XXX.XXX",
    "account_id": "ACCXXXXXXXXXXXXXXXXXXXX",
    "attachment_status": "valid",
    "attachment_validations": [
        {
            "validation_name": "Validation of face detection",
            "validation_type": "face-detection-validation",
            "attachment_type": "document-front",
            "result": "valid"
        },
        {
            "validation_name": "Validation of document text legibility",
            "validation_type": "ocr-validation",
            "attachment_type": "document-front",
            "result": "valid"
        },
        {
            "validation_name": "Validation of document text legibility",
            "validation_type": "ocr-validation",
            "attachment_type": "document-reverse",
            "result": "valid"
        }
    ],
    "allowed_retries": 2,
    "remaining_retries": 2
}

Among other details, the following information may be identified 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.

User response:

  • input_files: If you sent the request with the query parameter show_details with value true, the response will show the links of the uploaded document pictures in this field. These links will be valid for 15 minutes.

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

Appendix 1. Supported Document Types

Document Type Applicable Countries Doc Picture Side
national-id CL, CO, MX, PA, PE, VE, CR Front/Reverse
Front for PA, VE
foreign-id CL, CO, MX, PE, CR Front/Reverse
driver-license BR, CL, CO Front
passport ALL * Front
identity-card CO Front/Reverse
rut CO Front
ppt CO Front/Reverse
invoice MX Front
picture-id MX Front
record MX Front
cnh BR Front
NOTES:

  • Supported document picture formats are JPEG, JPG and PNG, with a maximum allowed size of 30MB.
  • PDF format is allowed when document_type is set to invoice (Only allowed for Mexico).
  • *You should set country to ALL when validating passport.