# 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](/validators/account_set_up/) and then go to [Authentication](/validators/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. {{}} ## 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](/validators/document_validation_api/#prerequisites). - ``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`` | ``SV`` | ``ALL``. Set the country of the document being validated.
Use ``ALL`` when ``document_type`` is set to ``passport``.
For ``BR`` , please ask sales team. - ``document_type`` [***Required***]: Allowed: ``national-id`` | ``foreign-id`` | ``driver-license`` | ``passport`` | ``identity-card``| ``rut`` | ``temporary-national-id`` | ``pep`` | ``ppt`` | ``invoice`` | ``picture-id`` | ``record`` | ``cnh`` | ``general-registration``. Set this value to the type of document being validated. For ``ppt`` and ``pep`` please ask sales team.
Refer to [Appendix 1: Supported Document Types](#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). - ``required_categories`` [***Optional***]: Only applicable when country is set to CO and document_type is set to driver-license. Allows you to restrict validation to specific driving license categories. Allowed values: ``A1`` | ``A2`` | ``B1`` | ``B2`` | ``B3`` | ``C1`` | ``C2`` | ``C3``. **Accepted formats:** * **Repeated parameter**: ``required_categories=A1&required_categories=B1`` * **Single value**: ``required_categories=A1`` Values are case-insensitive and automatically deduplicated. If provided, this field cannot resolve to an empty value, and any category outside the allowed list will return a validation error. For any other country/document_type combination, this parameter is ignored. Currently, ``required_categories`` is only supported for Colombian (CO) driver's licenses (``driver-license``). Sending it for other countries or document types has no effect. *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](/guides/account_id/) to learn more about it. ** In countries where available, 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**](/guides/understading_background_checks/) with a [**Custom Type**](/guides/background_check_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: {{}} { "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*](/validators/tips_doc_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**](#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: {{}} { "code": 10200, "http_code": 200, "message": "Successfully uploaded" } {{}} {{}} { "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: {{}} { "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", "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: {{}} { "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**](/validators/declined_reasons/) section. - To learn more about the possible expired reason, please visit [**Expired Reasons**](/validators/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](../config_validators/) 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**](/validators/webhook_rule/) section. ## Appendix 1. Supported Document Types {{}} | Document Type | Applicable Countries | Doc Picture Side | |-------------------------|--------------------------|---------------------| | national-id | CL, CO, MX, PE, SV | **Front/Reverse** | | foreign-id | CL, CO, MX, PE, SV | **Front/Reverse** | | driver-license | BR, CL, CO | **Front** | | passport | ALL | **Front** | | identity-card | CO | **Front/Reverse** | | temporary-national-id | CO | **Front** | | rut | CO | **Front** | | pep | CO | **Front** | | ppt | CO | **Front/Reverse** | | invoice | MX | **Front** | | picture-id | MX | **Front** | | record | MX | **Front** | | cnh | BR | **Front** | | general-registration | BR | **Front/Reverse** | {{
}} **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).