Checks API
NOTE: Truora provides a Postman collection online that includes the necessary tools to simplify the testing process.
Welcome to the Truora Check RESTful API reference. If you haven’t already, we strongly advise you to check out our Guides Section.
Truora Check API allows performing full background checks on people, vehicles and companies. There are three main types of background checks:
- Personal background check: Verifies national IDs in multiple databases of public and legal entities in the LATAM region. For every national ID, returns information on: personal identity, criminal records, international background check, and professional background.
- Vehicle background check: Verifies the vehicle documents and the owner identity in multiple databases of public and legal entities in the LATAM region. For every vehicle and owner type, returns information on: personal identity, driving records, criminal records, and vehicle information.
- Company background check: Verifies the tax ID or a company name in multiple databases of public and legal entities in the LATAM region. For every company, returns the associated: business status, legal and criminal records, and media reports.
Authentication
To access Truora’s services and perform API calls securely, you need to authenticate your requests. This is done by including a specific authentication token, known as the ”Truora-API-Key” in the header of your requests.
By providing this key in your API requests, you establish a secure and authorized connection, enabling seamless interaction with Truora’s services.
Base URL
https://api.checks.truora.com
Checks
Checks API enables you to create and retrieve background checks. It consults multiple databases and provides a comprehensive set of information to assess the reliability of a person, vehicle, or company. Explore our guide on Background Checks for further details.
Create check
Creates a background check and queues it to start collecting information. The full details of background checks can be retrieved with their respective Check IDs using getCheck endpoint. Keep in mind that, depending on the check type, input document, and country of a search, certain inputs are required. You should always provide as many inputs as possible in order to get the highest accuracy.
If your check type is not referenced in the following table, please reach out to find out the fields that apply for you.
Indicates whether the person subject to the validation authorized the validation. Must be true in order to proceed [Required for API key V1 or later]
Document country
Background check type. Replace custom_type_name with the name of your custom type to perform a custom type check
Vehicle license plate
Person birthdate. This date is used to get some additional information about a person and to filter homonyms in some cases. YYYY-MM-DD format, Required for complete background checks in Brazil and Perú
Used for the RG (Registro Geral) identification in Brazil. This identification has different formats according to the state that issues the document. It can have numbers and letters but other characters (- * , . ) are omitted, Required in order to get complete background checks in Brazil
Company name “Don’t forget this required field to complete background checks in Brazil”
Payment day of a vehicle circulation permit (Chile only)
ID for Venezuelans working in Peru
This field also apply for PPT (Permiso de Protección Temporal) in Colombia
Person birth certificate
Colombian escrow
Diplomatic ID
Person or entity first name. If the document type and number are not provided, the report might include homonyms. Required when searching by first name, Required in order to get complete background checks in Brazil
Person passport
Region where the background is to be checked in addition to the region where the person is from. By default, background checks in Brazil are performed in the person region of birth according to their CPF. Required for Brazil only. Keep in mind that a nation-wide search can take more than 24 hours to complete, whereas region-specific searches take from 2 to 20 min to complete.
Allowed values are: DF: Distrito Federal, AC: Acre, AL: Alagoas, AP: Amapá, AM: Amazonas, BA: Bahía, CE: Ceará, ES: Espírito Santo, GO: Goiás, MA: Maranhão, MT: Mato Grosso, MS: Mato Grosso do Sul, MG: Minas Gerais, PA: Pará, PB: Paraíba, PR: Paraná, PE: Pernambuco, PI: Piauí, RJ: Río de Janeiro, RN: Río Grande do Norte, RS: Río Grande do Sul, RO: Rondônia, RR: Roraima, SC: Santa Catarina, SP: São Paulo, SE: Sergipe, TO : Tocantins, ALL: nation-wide search
Defines the behavior of the API when creating a background check with the same input values used for a recently created background check.
When true, forces the creation of a new background check; otherwise, it returns the result of the background check created earlier.
Person or entity last name. If the document type and number are not provided, the report might include homonyms. Required when searching by last name. Required in order to get complete background checks in Brazil
15-digit IMEI to be validated
Person document issue date in “YYYY-mm-dd” format (e.g. 2008-12-31) . This date is used to get some additional information about a person in some cases
Indicates whether the check score is to be periodically revised and its frequency. It can be daily, weekly, monthly, yearly or have a custom frequency written as a number accompanied by d: day, w: week, m: month, y: year for instance: 3d: every three days, 2w: every two weeks. Ignore this field if the check is only to be performed once
Driver’s license number
Person foreign ID
Verification code registered for criminal records in Peru and Chile
National ID from the person native country. Keep in mind that you must provide the native_country if you enter a native_national_id
Report ID the background check will be inserted into
Company ID used for tax payments
national-id, foreign-id, tax-id or passport
Vehicle NIV number
Folio for Chilean certificate search. Chile only
Document number of Chilean identity. This number is used to get some additional information about a person. Chile only
ID for Venezuelans working in Colombia
Professional ID card
ID of the vehicle owner
National ID
Country of birth. Required if native_national_id is provided
Person phone number. Required by law to notify the person their background is being checked
List checks
Get check
Returns the results of the check that matches the ID provided, complete with a set of scores explained below.
Scores:
- Global Score: Average risk associated with a person, company or vehicle, according to the background check results. The global score considers results that are validated with the ID number provided. The score ranges from 0 to 1, where 0 represents high risk and 1 low risk.
- ID Score: Average risk associated with a person according to the background check results. The ID score considers the results that are validated with a person identity document. The score ranges from 0 to 1, where 0 represents high risk and 1 low risk.
- Name Score: Average risk associated with a person according to the background check results. The name score considers results that are validated against the name of a person and could not be validated with their ID number. These results might have homonyms associated with them. The score ranges from 0 to 1, where 0 represents high risk and 1 low risk.
In order to calculate these scores, a weighted average is considered with different weights allocated to each dataset. Scores can be customized using the config endpoints by assigning a weight to each dataset according to its relevance.
Keep in mind that results from the API vary depending on the country, check type and the inputs entered on check creation.
Get Check Attachments
List Check Details
Summarize
Get the status of a database
Delete check
Custom-Type
The Custom Type API enables the creation of custom searches, allowing you to include only the desired datasets in background checks, thus enhancing the check efficiency. Moreover, you can customize the impact of each dataset on the global score by assigning it a weight value between 0 and 1. It’s important to note that the sum of all weights must equal 1.
You can use custom types in your checks to perform custom-type checks. For detailed information, refer to our Custom Type guide.
Create custom type
typeCountry where this set of rules applies. Use “all” if the check type searches by name by relying on international databases
Custom type name. It cannot be person, vehicle, or company. Use this type in your checks to perform custom-type checks
Criminal record weight for score calculation. From 0 to 1. If not provided, the dataset is skipped entirely decreasing the search time
Alert in media weight for score calculation. From 0 to 1. If not provided, the dataset is skipped entirely decreasing the search time
Driving license weight for score calculation. From 0 to 1. If not provided, the dataset is skipped entirely decreasing the search time
Taxes and financial background weight for score calculation. From 0 to 1. If not provided, the dataset is skipped entirely decreasing the search time
Affiliation and insurance weight for score calculation. From 0 to 1. If not provided, the dataset is skipped entirely decreasing the search time
International background weight for score calculation. From 0 to 1. If not provided, the dataset is skipped entirely decreasing the search time
Business background weight for score calculation. From 0 to 1. If not provided, the dataset is skipped entirely decreasing the search time
Legal background weight for score calculation. From 0 to 1. If not provided, the dataset is skipped entirely decreasing the search time
Personal identity weight for score calculation. From 0 to 1. If not provided, the dataset is skipped entirely decreasing the search time
Vehicle information weight for score calculation. From 0 to 1. If not provided, the dataset is skipped entirely decreasing the search time
Professional background weight for score calculation. From 0 to 1. If not provided, the dataset is skipped entirely decreasing the search time
Traffic fines weight for score calculation. From 0 to 1. If not provided, the dataset is skipped entirely decreasing the search time
Vehicle certificate background weight for score calculation. From 0 to 1. If not provided, the dataset is skipped entirely decreasing the search time
Update custom type
Country where this set of rules applies. Use “all” if the check type searches by name by relying on international databases
Custom type name. It cannot be person, vehicle, or company. Use this type in your checks to perform custom-type checks
Alert in media weight for score calculation. From 0 to 1. If not provided, the dataset is skipped entirely decreasing the search time
Professional background weight for score calculation. From 0 to 1. If not provided, the dataset is skipped entirely decreasing the search time
International background weight for score calculation. From 0 to 1. If not provided, the dataset is skipped entirely decreasing the search time
Affiliation and insurance weight for score calculation. From 0 to 1. If not provided, the dataset is skipped entirely decreasing the search time
Criminal record weight for score calculation. From 0 to 1. If not provided, the dataset is skipped entirely decreasing the search time
Driving license weight for score calculation. From 0 to 1. If not provided, the dataset is skipped entirely decreasing the search time
Taxes and financial background weight for score calculation. From 0 to 1. If not provided, the dataset is skipped entirely decreasing the search time
Vehicle certificate background weight for score calculation. From 0 to 1. If not provided, the dataset is skipped entirely decreasing the search time
Traffic fines weight for score calculation. From 0 to 1. If not provided, the dataset is skipped entirely decreasing the search time
Business background weight for score calculation. From 0 to 1. If not provided, the dataset is skipped entirely decreasing the search time
Legal background weight for score calculation. From 0 to 1. If not provided, the dataset is skipped entirely decreasing the search time
Personal identity weight for score calculation. From 0 to 1. If not provided, the dataset is skipped entirely decreasing the search time
Vehicle information weight for score calculation. From 0 to 1. If not provided, the dataset is skipped entirely decreasing the search time
List custom types
Delete custom type
Allows deleting a custom type. Please note that person, vehicle, and company custom types can not be deleted.
After deletion, the response will display the remaining custom types associated with the country of the deleted custom type.
Settings
Allows the configuration of parameters such as names matching type, retries and max duration.
Create setting
Indicates the maximum amount of time a check can take to fetch responses. It follows the following format "xt" where x is a number and t is a letter ( m for minutes or h for hours). Example 25m indicates 25 minutes, 2h indicates 2 hours. This value must be between 15 minutes and 7 days (168 hours). When not configured, it is set to default. If retries is enabled, the default max duration is set to 48 hours; otherwise, it is set to 3 hours for Colombia, Mexico, Peru, and Brazil; 48 hours for Chile and International searches; and 72 hours for Costa Rica
Defines the matching type between the names retrieved from the identity databases and the names found in the criminal, legal and international databases to determine whether a record should be included in the check or not. soft (used by default) means matching names when they are similar enough to be considered the same person (e.g., Maria Alejandra Gomez would match Alejandra Gomez). exact means the names must perfectly match. Keep in mind that this feature is a configuration at a Client level, so it will affect all your check types
Indicates whether or not database queries must be retried until they successfully return a response or until the max_duration time is reached
Continuous
Enables the creation of recurring checks with customizable frequency, providing notifications whenever there are changes in check scores.
Create Continuous Check
Time between background checks. It can be daily, weekly, monthly, yearly or have a custom frequency written as a number accompanied by a letter d: day, w: week, m: month, y: year. For instance: 3d: every three days, 2w: every two weeks
Date on which background checks will stop. YYYY-MM-DD format. For the date to be valid, it must allow at least one check to be run according to the frequency.
Background checks to be processed recurrently
Update Continuous Checks
Indicates whether the background checks must be processed recurrently
API Key version to be used for the continuous check hooks. This version must match API key version you use. Version 0 is used by default.
Time between background checks
List Continuous Checks
Get Continuous Checks
List Continuous Check Logs
Enables the export of a comprehensive PDF containing the obtained information, Truora’s assigned score, and consulted datasets. For more details, refer to Background Checks: PDF, Variables and Attachments guide.
Create PDF
Get PDF
Batch
Given a valid xlsx file, this endpoint takes the information from the file and starts creating the checks and associating it to the specified report object. For a step-by-step explanation of all methods and required fields for submitting a batch, please refer to the Background Checks Batch via API guide.
Create Batch
This endpoint facilitates the creation of batches of different types. This endpoint does not include input file uploading or batch start logic.
The check inputs to be uploaded in the file can be manually mapped using columns_mapping.{input_name} body params, by default the inputs accepted by the check type will be mapped. The request will return a columns array with the order in which the inputs should be in the xlsx file.
The batch creation request returns a temporary URL in the file_upload_link field. This URL must be used to make a PUT request with the file containing the mapped batch data. It is crucial to note that the URL has a limited expiration time (30min) and will only allow the first submitted file to be uploaded. Therefore, it is highly recommended to carefully review the information before uploading.
Type of the batch checks. Replace custom_type_name with the name of your custom type to perform a batch of custom type checks. In case you want to create a custom type please visit How to Create a Custom Type for Background Check guide for more information.
The service for which the batch will be processed
The country of batch checks
Columns mapping of the xlsx file. This body parameter must be sent for each column you want to upload in the xlsx file, replacing the input_name with the name of the input (e.g. columns_mapping.national_id). The value must be the index of the column in the file, being 0 for column A, 1 for column B and so on. If no column mapping is sent, all inputs for the selected custom type will be automatically mapped.
Date on which background checks will stop to create a batch of continuous checks. YYYY-MM-DD format. For the date to be valid, it must allow at least one check to be run according to the frequency.
Time between background checks to create a batch of continuous checks. It can be daily, weekly, monthly, yearly or have a custom frequency written as a number accompanied by a letter d: day, w: week, m: month, y: year. For instance: 3d: every three days, 2w: every two weeks
Request Batch Report Generation
Batch report file format
Start Batch
Stop Batch
Get Batch
Get Batch Report
Digital Identity
NOTE: Truora provides a Postman collection online that includes the necessary tools to simplify the testing process.
Truora Digital Identity (Truora DI) is a versatile platform that allows you to create a personalized process for authenticating your users. It enables you to utilize a range of Validators in a single process to simplify user identity verification. The Validators enable diverse actions, ranging from verifying that a phone or email belongs to the user, to matching users´ biometrics against government sources. The platform offers the flexibility to create the processes securely and without introducing complexity to the user experience, ensuring your new users can promptly access and enjoy your services.
Authentication
To access Truora’s services and perform API calls securely, you need to authenticate your requests. This is done by including a specific authentication token, known as the ”Truora-API-Key” in the header of your requests.
By providing this key in your API requests, you establish a secure and authorized connection, enabling seamless interaction with Truora’s services.
Base URL
https://api.connect.truora.com
Web
Digital Identity Web is a versatile platform that allows you to create a customized process to authenticate your users. It allows you to use a number of validators in a unique process to simplify user identity verification.
Here you will find the endpoints you need to create process links and get results. If you need to create process flows please see the Documentation.
Generate Token
API key type
Country for the identity verification process. Required only if grant is set to digital-identity
Document type for the identity verification process. Only used if grant is set to digital-identity
Indicates which service this API key grants access to. Required if key_type is set to web or sdk
API key name. Required only if key_type was set to backend
URL where the user is to be redirected once the verification process has ended. Required if grant is set to digital-identity
User identifier for the person who will perform digital-identity validation. Only used if grant is set to digital-identity. If not sent it is generated automatically. Note that only Account IDs following the regex pattern [a-zA-Z0-9_.-]+ are supported. Please go to Create an Account ID to learn more about it.
Billing hubs allow for separated counters and billing. Required if the customer uses billing hubs
Validation flow to be performed for the identity verification process. Required only if grant is set to digital-identity
List of phone numbers to be validated during the identity verification process
API key version. Version 0 is used by default
List of emails to be validated during the identity verification process
Get Result
Allows you to retrieve the current status and details of a process. The status begins as pending and updates to either success or failure when the process completes.
- Pending: The process is still ongoing.
- Success: All steps in the process have been successfully completed. If the flow includes validators, all
validation_statusvalues must also be successful. - Failure: Occurs due to an internal error, timeout, or if the process is declined or expired.
Here’s a comprehensive list of reasons why a process or validation might be declined or expired, as recorded in the declined_reason and expired_reason fields:
If a process includes validators and the identity process times out because a validation did not complete, but all inputs have been uploaded, the system grants an additional 5 minutes to receive a validation response with the final status. This behavior occurs up to 3 times.
On the final attempt to retrieve the validation response, if the validation remains in the pending status, the identity process status will update to failure, with failure_status set to expired.
If a process includes the attributes override_status and override_status_history, it means the final status was modified by an authorized user. In this case, use the override_status attribute instead of status to determine the final status of the process. The override_status_history attribute will contain the history of changes made to the status.
WhatsApp can be used as a channel to reach users through flows. Using WhatsApp Business Account (WABA), you would be able to send and receive messages through the WhatsApp Business API for your business processes, interactions with your users or create validation processes, accounts as a document, document + face, email, phone number, electronic signature, and background. There are two different types of messages that can be used through WhatsApp Business, incoming messages (inbound) and outgoing messages (outbound).
Update Inbound Flow
Allows updating an inbound flow.
Note: Do not forget that if you already have a whatsapp link created and you update it, you must generate a new link.
Identifier of the Flow previously created.
Unique message the users will be sending to the business WhatsApp (WABA) in order to begin the Flow.
Phone number of the WABA that interacts with the users. Must include the country code. Example 14080001111.
Create WABA subscription
Provider Statuses
Send Outbound Message
status needs to be APPROVED before it can be sent.[Required] ID of an approved Outbound Message. Example: OTB123
[Required] Phone number without the country code of the user that will receive the message. Example: 0001234567
[Required] Must be true for starting the conversation.
User has authorized to be contacted through WhatsApp.
[Required] If the outbound message has variables like hello {{.name}} {{.lastname}}. The value must be the desired value of the variable.
It is important to send as many key-value pairs as variables present in the message.
Example: for the first variable var.name: Roger and for the second variable var.lastname: Federer.
This field is used as a unique identifier for your user in the Truora’ system. If you send it, outbound messages sent to each user will be linked through this. Note that only Account IDs following the regex pattern [a-zA-Z0-9_.-]+ are supported. Please go to Create an Account ID to learn more about it.
[Required] Country code for the user phone number. Example: +57
[Required] If the Outbound Message is_notification field is false. Contains the FlowID of the flow that will start when the Outbound message is accepted by the user.
Example: IPF123
Cancell Campaign
Create Inbound Flows
Set up inbound message that triggers a specific flow. All inputs are required for inbound creation.
To finish the inbound creation process, you must access the following link, by adding the PhoneNumber and the activating message. when you need to put a space in the activation message write this code %20
https://api.whatsapp.com/send/?phone=PhoneNumber&text=activatingmessage
Example https://api.whatsapp.com/send/?phone=57317770000&text=Hola%20Truora
Phone number of the WABA that interacts with the users. Must include the country code. Example 14080001111.
Identifier of the Flow previously created.
Unique message the users will be sending to the business WhatsApp (WABA) in order to begin the Flow.
Create Outbound Messages
[Required] Type of the outbound message.
supported content Image: image/jpeg, image/png maximum size 5mb. Video: video/mp4, video/3gpp maximum size 16mb. Document: any valid MIME type maximum size 100mb.
Required if the outbound message has variables like hello {{.name}} {{.lastname}}. The value must be an example of the variable.
It is important to send as many key-value pairs as variables present in the message.
Example: for the first variable var.name: Jhon and for the second variable var.lastname: Doe.
[Required] Indicates if the Outbound Message is a notification (true) or will start a flow (false).
[Required] Code of the language the message is in.
[Required] The message to be sent to the user.
Example: “Hello, ¿are you ready to start the process?”
If the message will include variables, they should be specified between double brackets like {{.<variable_name>}}.
Example: “Hello {{.name}}, ¿are you ready to start the process?”
Required If is_notification is set to False, it will be the content for the continue option in the outbound message.
Required if the outbound type is not text.
[Required] Contains a text specifying the name of the outbound.
[Required] WABA in which this outbound template will be added.
Required If is_notification is set False, it will be the content for the cancel option in the outbound message.
[Required] Enum defined by WhatsApp of the category for the outbound. OTP is for One Time Passwords, MARKETING is for marketing campaigns and TRANSACTIONAL is for any other topic of the Outbound.
Update Outbound Message
Put WABA Line config
List WABA Lines
Get Result
Allows you to retrieve the current status and details of a process. The status begins as pending and updates to either success or failure when the process completes.
- Pending: The process is still ongoing.
- Success: All steps in the process have been successfully completed. If the flow includes validators, all
validation_statusvalues must also be successful. - Failure: Occurs due to an internal error, timeout, or if the process is declined or expired.
Here’s a comprehensive list of reasons why a process or validation might be declined or expired, as recorded in the declined_reason and expired_reason fields:
If a process includes validators and the identity process times out because a validation did not complete, but all inputs have been uploaded, the system grants an additional 5 minutes to receive a validation response with the final status. This behavior occurs up to 3 times.
On the final attempt to retrieve the validation response, if the validation remains in the pending status, the identity process status will update to failure, with failure_status set to expired.
If a process includes the attributes override_status and override_status_history, it means the final status was modified by an authorized user. In this case, use the override_status attribute instead of status to determine the final status of the process. The override_status_history attribute will contain the history of changes made to the status.
Get WABA Line
Get Inbound Flow
List Outbound Messages
Get Outbound Message
List Inbound Flows
Get Campaign
Get Process Validations
List WABAs
Remove Inbound Flow
Remove Outbound Message
WA Engagement
Increase your customer engagement by automating your customer service, marketing and sales process in WhatsApp.
Get Chat
Search Chat Activities
Search Chats
WA Contacts
Add, search and manage your customers (end users) in a single place.
Create contact property
Indicates the type of the custom property.
Indicates the name of the custom property.
Required only if type is enum. Add the list of personalized values separated by comma, example: value1, value2, value3.
When set to true, this setting hides the property being created, ensuring it does not appear in a contact’s details. NOTE: A maximum of 25 visible (non-hidden) properties can exist simultaneously.
Create contact
Indicates the Phone number of the contact that you want to register. Must include the country code (e.g., +570000000000).
Indicates the name of the contact that you want to register.
Indicates the custom property. You must replace the variable {{property_id}}, with the id of the property you want to set for the contact. (e.g., custom_property_values.CCP12345).
Indicates the email address you want to register (e.g., email@yourdomain.com).
Update contact
Indicates the custom property. You must replace the variable {{property_id}}, with the id of the property you want to update for the contact. (e.g., custom_property_values.CCP12345).
Indicates the email address you want to update (e.g., email@yourdomain.com).
Indicates the name of the contact that you want to update.
Get contact properties
Get all contacts
Get contact
Delete contact
DI Processes
Configure and order the validations you want to do in your process. Try and start validating your users by sending a link.
Create Identity
This endpoint allows you to initiate an identity validation process for a specific user. Before using this endpoint, you must create a Flow and generate a temporary api_key linked to the corresponding flow_id. Follow the Web Integration Token Guide to complete this setup. The response will include a process_id, which you’ll use in subsequent process requests.
Important Notes
Token:
You must generate a unique token (api_key) for each identity validation process, even if performed by the same user.
Header Setup:
Set the Truora-API-Key header to the value of the generated token (api_key) required before making this request.
Identity Back
Send Process Link
This request sends a short link to the user’s phone number via the specified messaging channel and in the specified language. The link directs the user to a secure URL to perform or continue their identity validation process.
Header Setup:
Set the Truora-API-Key header to the same api_key value used when creating the process_id (via the Create Identity request).
The country code for the recipient’s phone number, including the + symbol (e.g., +57 for Colombia). Refer to this list of country codes.
The channel through which the message will be sent.
The language of the redirection/recovery message.
The recipient’s phone number, excluding the country code.
List Identity
Retrieves the current status and details of all identity processes. Query parameters can be used to filter results based on specific criteria. When a date range is defined, the search is limited to 2 months. The response includes up to 20 processes per query.
Note: If a process includes the attributes override_status and override_status_history, it means the final status was modified by an authorized user. In this case, use the override_status attribute instead of status to determine the final status of the process. The override_status_history attribute will contain the history of changes made to the status.
start_date and end_date cannot exceed 2 months. Both start_date and end_date are required for date range filtering.
start_date and end_date cannot exceed 2 months. Both start_date and end_date are required for date range filtering.
Read Identity
Download PDF
Get Result
Allows you to retrieve the current status and details of a process. The status begins as pending and updates to either success or failure when the process completes.
- Pending: The process is still ongoing.
- Success: All steps in the process have been successfully completed. If the flow includes validators, all
validation_statusvalues must also be successful. - Failure: Occurs due to an internal error, timeout, or if the process is declined or expired.
Here’s a comprehensive list of reasons why a process or validation might be declined or expired, as recorded in the declined_reason and expired_reason fields:
If a process includes validators and the identity process times out because a validation did not complete, but all inputs have been uploaded, the system grants an additional 5 minutes to receive a validation response with the final status. This behavior occurs up to 3 times.
On the final attempt to retrieve the validation response, if the validation remains in the pending status, the identity process status will update to failure, with failure_status set to expired.
If a process includes the attributes override_status and override_status_history, it means the final status was modified by an authorized user. In this case, use the override_status attribute instead of status to determine the final status of the process. The override_status_history attribute will contain the history of changes made to the status.
Read Variables
Customers
Customers is a centralized solution that allows you to visualize and analyze the data generated by the transactions made by your users along different business funnels.
List Customers
Get Customer
List Customers Transactions
Product that originated the transaction.
Read Customer Transaction
Main Validator Suite API
NOTE: Truora provides a Postman collection online that includes the necessary tools to simplify the testing process.
Welcome to the Truora Validators Suite RESTful API Reference. If you haven’t already, we strongly advise you to check out our Validators API Documentation.
Here, you’ll find detailed technical information about our Validators API endpoints, including parameters, request and response formats, error codes, and supported methods for seamless integration.
The Validators Suite supports various use cases, such as document validation, phone and email verification, facial recognition, and more.
A validation process may include some or all of the following steps, depending on the validator:
-
Create Enrollment: Required to associate user data for validators requiring prior information, such as face, email, and phone.
-
Create Validation: Required for all validators; you must specify the validator type and relevant validation parameters.
-
Perform Validation: Executes asynchronous validations, such as email or phone, by verifying tokens received by the user.
-
Get Validation: Retrieves the final status, results, and details of any validation.
Please keep in mind that in our validation processes, the Account ID serves as a unique user identifier, allowing you to track the validations performed. It is important to generate a distinct identifier for each user undergoing validation to prevent data overlap between users and ensure proper monitoring for each one.
For conceptual overviews, implementation guides for each validator, and additional resources to enhance your integration experience, please visit our Validators API Documentation.
Authentication
To access Truora’s services and perform API calls securely, you need to authenticate your requests. This is done by including a specific authentication token, known as the ”Truora-API-Key” in the header of your requests.
By providing this key in your API requests, you establish a secure and authorized connection, enabling seamless interaction with Truora’s services.
Base URL
https://api.validations.truora.com
Accounts
Validation accounts simplify user identification across multiple Truora validators, enabling a single user to undergo various validation methods using the same account. For better user tracking, it is recommended to create custom-named validation accounts and use them during the validation or enrollment processes; otherwise , if a custom account_id is not specified during these processes, validators will automatically assign a random alphanumeric name.
Create Validation Account
Phone number of the person associated with the account.
X (formerly Twitter) username of the person associated with the account.
Customized ID for the validation account being created. Only account IDs matching the pattern [a-zA-Z0-9_.-]+ are supported. If omitted, a random alphanumeric account ID is automatically created.
Country where the person associated with the account is located, specified in ISO 3166 Alpha-2 format (e.g., CO for Colombia). See the full list of ISO Country Codes.
Issue date of the person’s document, formatted in RFC3339 (e.g., 2000-05-24).
Type of document for the person associated with the account.
Email address of the person associated with the account.
Facebook username of the person associated with the account.
Document number of the person associated with the account.
First name of the person associated with the account.
Last name of the person associated with the account.
Create Validation for an Account
Creates a new validation for the specified account_id.
Note: Ensure you have the account_id from previous steps. If an enrollment has already been created, it is not necessary to create a new one for each validation.
Account ID linked to the validation.
For document-validation, an account ID is automatically created if omitted; otherwise, the custom account ID provided is used.
For other validations, use the same account ID from the enrollment process.
The account ID helps trace validations linked to the account. Only account IDs matching the pattern [a-zA-Z0-9_.-]+ are supported. Learn more at Create an Account ID.
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.
Indicates the type of validation to be performed.
[Required for speech_match subvalidation] Minimum precision that the audio transcription obtained from the video selfie should have with the speech_token.
[Required for phone-verification] Language used to perform the validation via the selected verification channel.
[Required if you have active retries] Refers to the validation_id of the failed validation. Remember that it is also necessary to send the same account ID (even if it is the automatically generated one) of the failed validation.
Note: When type is face-recognition, only available if passive liveness is enabled.
For document-validation, when specified, indicates the name of the Custom Type check to be used when a background check linked to this validation is desired. Keep in mind that the Custom Type check must already exist.
For email-verification, specifies the language of the email that the final user receives.
Evaluates the availability for manual review according to the review schedule. If unavailable, the manual review will be skipped without affecting the validation status, and the manual review status will be marked as unavailable.
[Required for document-validation] Set this value to the type of document been validated. For ppt please ask sales team.
Refer to Supported Document Types for a complete reference of supported document types, applicable countries and document front/reverse picture requirements.
[Required for phone-verification] Specifies the label of the phone number to be associated with the validation account upon successful validation. The phone type must have already been enrolled.
Indicates which subvalidations you want to perform during the face-recognition validation execution. If omitted, only similarity will be used. You can select more than one.
Determines the required similarity between the provided picture and video or selfie to pass the face-recognition validation, ranging from 0 to 1. By default, the threshold is set to 0.65.
The time, in seconds, users will have to complete the validation. If omitted, the timeout from the client’s config will be used.
- Default: 300 (5 minutes) for all validators.
- Max: 600 (10 minutes) for phone-verification and email-verification;
21600 (6 hours) for document-validation, face-recognition and face-search.
[Required for document-validation] Set the country of the document being validated. Use ALL when document_type is set to passport.
For BR,CR, please ask sales team.
- Allowed: CO | CL | MX | PE | BR | CR | ALL
[Required for face-search] Country of the face to be searched in reported lists (TruFace).
Use ALL when using TruFace (face-search) as a Face Validation compliment.
- Allowed: ALL | BR | CL | CO | CR | EC | MX | PE
[Required for phone-verification] Indicates the channel used to perform the verification. Some problems may occur when receiving the SMS due to external protocols of the mobile service providers, so we recommend giving an additional option to the users.
If you set whatsapp as the verify_channel value, you must have your own WABA line and Activate it. Then, create your Outbound message of type OTP and Contact Support to provide your Outbound ID for inclusion in your process.
List Validation Accounts
start_key query parameter. The response includes a list of each validation account and its details.Get Validation Account
Get Enrollments by Account
Retrieves all enrollments linked to a specific account_id. Each enrollment object includes its status and other relevant details. Enrollment status begins as pending and can ultimately result in either success or failure.
For more information about declined enrollment reasons, please refer to the Declined Reasons Guide.
Get Account Validations
Retrieves all validations linked to a specific account_id. Each validation object includes its validation status, expired reason, failure reason and other relevant details. Validation status begins as pending and can ultimately result in either success or failure.
For more information on failure reasons, please refer to the following guides:
Get Validation from Account
Retrieves the detailed information of a specific validation using an account_id and validation_id. This object is useful for understanding the exact status of the validation process. You can retrieve the current status and results of a validation, where the validation_status begins as pending and can either be success or failure upon completion.
To obtain details such as the inputs or uploaded media for the validation, you can include the query parameter show_details with the value of true.
To learn more about the reasons for failure, please refer to the following guides:
true, retrieves additional validation details, including links to user-uploaded files that remain valid for 15 minutes.
Enrollments
The enrollment step is crucial in our system, as it connects an account with a specific validation type. This process allows you to register a user once and perform multiple validations seamlessly. The required fields for an enrollment vary depending on the validation type. Note that enrollment is mandatory for all validators except document validation.
Create Enrollment
Indicates the type of validation to be performed along with this enrollment.
This indicates that you have the authorization of the person to be enrolled. This is mandatory in order to comply with data protection laws. Value must be set to true in order to perform the enrollment.
[Required for email-verification] Email to be associated with the user account.
[Required for face-search] Indicates the reason to block a face. Set one of the following:
-
manipulated_document: Indicates that this person is known to use manipulated documents to pass identity validations. -
manipulated_photo: Indicates that this person is known to manipulate photos to pass identity validations. -
non_payment: Indicates that this person has incomplete payments and refuses to pay. -
criminal_records_in_company: Indicates that this person has some sort of criminal history with your company, or an ally. -
fraudster: Indicates you know this person to be a fraudster for reasons different from the above.
[Required for phone-verification] Phone number to be associated with the validation account on successful validation. Must include the country code (e.g., +57300XXXXXXX).
[Required for phone-verification] Specifies the label of the phone number to be associated with the validation account upon successful validation. You can associate up to three phone numbers with a user account. To do this, you must create a new enrollment by choosing a different phone_type each time.
Account ID linked to the enrollment.
An account ID is automatically created if omitted; otherwise, the custom account ID provided is used.
The account ID helps trace enrollments/validations linked to the account. Only account IDs matching the pattern [a-zA-Z0-9_.-]+ are supported. Learn more at Create an Account ID.
Only available for face-recognition validations. Used to specify the creation of enrollment that does not require an identity validation to complete. Set as none to skip the required validation. If omitted, the enrollment will require the normal validation process, and the enrollment status will remain pending until successfully validated.
Note: To use the confirmation parameter your company’s account must be authorized. To request authorization, please contact our Support Team. This authorization will affect only your Truora-API-Keys created after the approval.
[Optional* for phone-verification] Origin country of the person to be validated. *Required if it was not provided during account creation.
- Allowed: CO | CL | MX | BR | VE | PE | EC | AR | US
[Required for face-search] Country of the reported face. Use ALL when using TruFace (face-search) as a Face Validation compliment.
- Allowed: ALL | BR | CL | CO | CR | EC | MX | PE
Get Enrollments by Account
Retrieves all enrollments linked to a specific account_id. Each enrollment object includes its status and other relevant details. Enrollment status begins as pending and can ultimately result in either success or failure.
For more information about declined enrollment reasons, please refer to the Declined Reasons Guide.
Get Enrollment
Allows you to search for an enrollment to verify its progress. Using this step is optional. The enrollment status begins as pending and can ultimately result in either success or failure.
For more information about declined enrollment reasons, please refer to the Declined Reasons Guide.
Delete enrollment
Validations
Validations is your tool for managing various validators such as document validation, face recognition, face search (TruFace), email verification, and phone verification. This API handles all the necessary logic for these validators, offering a unified service to manage multiple validators efficiently.
Perform sync validation
validation_id within the specified account_id. Examples of these validators include phone and email. Not applicable to async validators such as document or face.If a previous validation attempt was unsuccessful, this will count as a retry, which could occur due to errors such as a typo in the token or other mistakes.
Indicates the type of validation to be performed.
The validation code sent to the user’s email or phone (via SMS, call, or WhatsApp) for verification.
Create Validation
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.
Account ID linked to the validation.
For document-validation, an account ID is automatically created if omitted; otherwise, the custom account ID provided is used.
For other validations, use the same account ID from the enrollment process.
The account ID helps trace validations linked to the account. Only account IDs matching the pattern [a-zA-Z0-9_.-]+ are supported. Learn more at Create an Account ID.
Indicates the type of validation to be performed.
[Required for phone-verification] Language used to perform the validation via the selected verification channel.
Evaluates the availability for manual review according to the review schedule. If unavailable, the manual review will be skipped without affecting the validation status, and the manual review status will be marked as unavailable.
[Required if you have active retries] Refers to the validation_id of the failed validation. Remember that it is also necessary to send the same account ID (even if it is the automatically generated one) of the failed validation.
Note: When type is face-recognition, only available if passive liveness is enabled.
For document-validation, when specified, indicates the name of the Custom Type check to be used when a background check linked to this validation is desired. Keep in mind that the Custom Type check must already exist.
For email-verification, specifies the language of the email that the final user receives.
[Required for speech_match subvalidation] Minimum precision that the audio transcription obtained from the video selfie should have with the speech_token.
The time, in seconds, users will have to complete the validation. If omitted, the timeout from the client’s config will be used.
- Default: 300 (5 minutes) for all validators.
- Max: 600 (10 minutes) for phone-verification and email-verification;
21600 (6 hours) for document-validation, face-recognition and face-search.
[Required for document-validation] Set this value to the type of document been validated. For ppt please ask sales team.
Refer to Supported Document Types for a complete reference of supported document types, applicable countries and document front/reverse picture requirements.
[Required for phone-verification] Indicates the channel used to perform the verification. Some problems may occur when receiving the SMS due to external protocols of the mobile service providers, so we recommend giving an additional option to the users.
If you set whatsapp as the verify_channel value, you must have your own WABA line and Activate it. Then, create your Outbound message of type OTP and Contact Support to provide your Outbound ID for inclusion in your process.
[Required for document-validation] Set the country of the document being validated. Use ALL when document_type is set to passport.
For BR,CR, please ask sales team.
- Allowed: CO | CL | MX | PE | BR | CR | ALL
[Required for face-search] Country of the face to be searched in reported lists (TruFace).
Use ALL when using TruFace (face-search) as a Face Validation compliment.
- Allowed: ALL | BR | CL | CO | CR | EC | MX | PE
[Required for phone-verification] Specifies the label of the phone number to be associated with the validation account upon successful validation. The phone type must have already been enrolled.
Indicates which subvalidations you want to perform during the face-recognition validation execution. If omitted, only similarity will be used. You can select more than one.
Determines the required similarity between the provided picture and video or selfie to pass the face-recognition validation, ranging from 0 to 1. By default, the threshold is set to 0.65.
Perform validation
validation_id. If a previous validation attempt was unsuccessful, this will count as a retry, which could occur due to errors such as a typo in the token or other mistakes.Indicates the type of validation to be performed.
The validation code sent to the user’s email or phone (via SMS, call, or WhatsApp) for verification.
File Upload
Accepts binary files such as images, videos, or other types of files, encoded in Base64 format. This input is used for uploading media or documents required in identity verification processes.
Get Account Validations
Retrieves all validations linked to a specific account_id. Each validation object includes its validation status, expired reason, failure reason and other relevant details. Validation status begins as pending and can ultimately result in either success or failure.
For more information on failure reasons, please refer to the following guides:
Get Validation from Account
Retrieves the detailed information of a specific validation using an account_id and validation_id. This object is useful for understanding the exact status of the validation process. You can retrieve the current status and results of a validation, where the validation_status begins as pending and can either be success or failure upon completion.
To obtain details such as the inputs or uploaded media for the validation, you can include the query parameter show_details with the value of true.
To learn more about the reasons for failure, please refer to the following guides:
true, retrieves additional validation details, including links to user-uploaded files that remain valid for 15 minutes.
Get all user Validations
This endpoint allows you to list all validations associated with your users, enabling effective tracking of their current statuses. The returned object provides insights into the exact status of each validation process, where the validation_status begins as pending and can ultimately result in either success or failure.
To learn more about the reasons for failure, please refer to the following guides:
Get Validation
Returns a validation object given a validation_id. This object is useful for understanding the exact status of the validation process. You can retrieve the current status and results of a validation, where the validation_status begins as pending and can either be success or failure upon completion.
To obtain details such as the inputs or uploaded media for the validation, you can include the query parameter show_details with the value of true.
To learn more about the reasons for failure, please refer to the following guides:
true, retrieves additional validation details, including links to user-uploaded files that remain valid for 15 minutes.
Config
The Config Validators feature allows for customization of various parameters to improve the behavior of the validators. This is particularly valuable when you wish to set different decision parameters like thresholds, timeouts, manual review enabling, and more. Below are the parameters that are configurable across multiple validators.
-
timeout: The amount of time, in seconds, that users will have to perform the validation before it times out. -
allowed_retries: The number of times the validation may be retried before failing. -
retry_ttl: The time to live (TTL), in seconds, for creating a retry of any validation.
Config by Validator Type
Each Validator has its own particularities and specific parameters (not listed in the table above) that you may modify to better suit your company’s needs. To learn about specific configurable parameters, default values, and special considerations, please visit the guide for the validator you want to configure:
NOTES:
-
The Config Validators parameters are global to your account and will affect all validations performed across it.
-
However, validations performed in a Flow will prioritize the configuration in the Validator Block of your flow. All other parameters, not configurable within the Flow Builder, will take the global configuration values. To learn about flows, please visit the Create your first flow guide from our Digital Identity documentation.
Update config
Allows updating the values of various parameters to improve the behavior of the validators, such as timeout, allowed retries, threshold, manual review, among other properties from our validators. For more datails about customizable parameters for each validator, please refer to the individual configuration guides:
Validator to be configured.
Analyzes the extracted data from the document for consistency in document-validation, such as date of birth and document number.
Checks for any alterations or edits in the image of the validated document in document-validation.
Analyzes if the image used for document-validation is a photocopy of a document.
When set to true, adds face_search subvalidation to the face-recognition validation. This enables the system to check if the uploaded face is reported in Truface (face-search).
Custom main title text in the email-verification validator email. For details, language options and default values, see the Email Validator Config guide.
The number of times the validation may be retried before failing.
Note: For face-recognition, retry feature is only available when passive liveness is enabled in the Face Validation process. For more information visit the Facial Recognition Methods guide.
-
For
document-validation: The default value is 0 retries, with a maximum of 3 retries. -
For
face-recognition: The default value is 0 retries, with a maximum of 2 retries. -
For
email-verificationandphone-verification: The default value is 2 retries, with a maximum of 4 retries.
Country for which the document-validation configuration will be updated.
[Required if modifying a validation_method] The type of document for which the document-validation configuration will be updated. If omitted, all supported document types will be affected.
Note: Refer to Appendix 1 tables in the Document Validator Config guide for a list of supported Document Types by Country.
Determines whether manual review will be performed upon face-recognition validation failure. You must contact Truora to activate this service. For more information about manual review, please visit the Manual Review guide.
Determines whether manual review will be performed upon validation failure in document-validation.
For more information about manual review, please visit the Manual Review guide.
Custom text appearing after the verification code in the email-verification validator email. For details, language options and default values, see the Email Validator Config guide.
Custom subject text in the email-verification validator email. For details, language options and default values, see the Email Validator Config guide.
Validates the extracted identification number against government databases in document-validation.
Available for document-validation and face-recognition.
The time to live (TTL), in seconds, for creating a retry of any validation.
-
For
document-validation: The default value is 300 seconds (5 minutes), with a maximum of 1800 seconds (30 minutes) and a minimum of 1 second. -
For
face-recognition: The default and maximum value is 300 seconds (5 minutes), with a minimum of 1 second.
Note: Forface-recognition, retry feature is only available when passive liveness is enabled in the Face Validation process. For more information visit the Facial Recognition Methods guide.
Custom support email address displayed at the bottom of the email-verification validator email. For details, language options and default values, see the Email Validator Config guide.
The time, in seconds, users will have to complete the validation.
- Default: 300 (5 minutes) for all validators.
- Max: 600 (10 minutes) for
phone-verificationandemail-verification;
21600 (6 hours) fordocument-validationandface-recognition.
Analyzes if the image used for validation is a photograph of a photograph of a document in document-validation.
Custom text within the OTP phone-verification messages, up to 30 characters. For details, language options and default values, see the Phone Validator Config guide.
The version of the document_type for which the document-validation configuration will be updated. If omitted, all supported document versions will be affected.
Note: For a complete list of Allowed document versions available by country and document type, refer to the tables in Appendix 1: Supported Document Versions. Please contact our Support Team for further assistance.
Custom text appearing before the verification code in the email-verification validator email. For details, language options and default values, see the Email Validator Config guide.
Determines the required similarity, ranging from 0 to 1, between the provided picture and the video or selfie used to pass the face-recognition validation. By default, the threshold is set to 0.65.
Get Config
Fetches the current configuration state for all validators associated with your account.
Note: Since the response includes configuration details for all validators linked to your account, please review the specific validator details you’re interested in carefully.
Delete Config
type) within the validator’s configuration. Deleting the configuration resets its values back to their defaults.Note: If you omit the
type parameter when sending the request, all configurations associated with the validator will be deleted, reverting all values to their default settings.Allowed: timeout | allowed_retries | use_manual_review | document_config | retry_ttl
If validator is face-recognition:
Allowed: threshold | timeout | enrollment_timeout | use_manual_review | include_face_search
If validator is email-verification:
Allowed: timeout | allowed_retries | email_subject | email_title | email_text_1 | email_text_2 | support_email
If validator is phone-verification:
Allowed: allowed_retries | timeout | custom_name
Configuration type to be reset. If provided, the validator reset will only affect the selected configuration; otherwise, all configurations will be reset.
Note : For
document-validation, setting the type field to document_config will reset any Document Version Config to their default values.
Name of the validator’s config to be deleted.
Status
Status lets you check the current state of our services in real time.