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.
Document country
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]
Background check type. Replace custom_type_name
with the name of your custom type to perform a custom type check
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
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รบ
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
ID for Venezuelans working in Colombia
Payment day of a vehicle circulation permit (Chile only)
Professional ID card
Vehicle license plate
ID for Venezuelans working in Peru
This field also apply for PPT
(Permiso de Protecciรณn Temporal) in Colombia
National ID from the person native country. Keep in mind that you must provide the native_country
if you enter a native_national_id
ID of the vehicle owner
Company name “Don’t forget this required field to complete background checks in Brazil”
national-id, foreign-id, tax-id or passport
Diplomatic ID
Verification code registered for criminal records in Peru and Chile
Person birth certificate
National ID
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
Company ID used for tax payments
Person phone number. Required by law to notify the person their background is being checked
Driver’s license number
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.
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
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
Colombian escrow
Report ID the background check will be inserted into
Vehicle NIV number
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 foreign ID
15-digit IMEI to be validated
Document number of Chilean identity. This number is used to get some additional information about a person. Chile only
Person passport
Country of birth. Required if native_national_id
is provided
Folio for Chilean certificate search. Chile only
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
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
Criminal record 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
Traffic fines 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
Personal identity 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
Alert in media 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
International background 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
Vehicle information 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
Driving license weight for score calculation. From 0 to 1. If not provided, the dataset is skipped entirely decreasing the search time
List custom types
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
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
Criminal record 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
Taxes and financial 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
Affiliation and insurance 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
Vehicle certificate 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
Professional background 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
Driving license weight for score calculation. From 0 to 1. If not provided, the dataset is skipped entirely decreasing the search time
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
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
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
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
List Continuous Checks
Get Continuous Checks
List Continuous Check Logs
Update Continuous Checks
Time between background 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.
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.
The service for which the batch will be processed
The country of batch checks
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.
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
Get Batch
Get Batch Report
Stop Batch
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.
Identity Back
Generate Token
API key type
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
Document type for the identity verification process. Only used if grant
is set to digital-identity
List of emails to be validated during the identity verification process
Validation flow to be performed for the identity verification process. Required only 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
URL where the user is to be redirected once the verification process has ended. Required if grant
is set to digital-identity
API key version. Version 0 is used by default
Country for the identity verification process. Required only if grant
is set to digital-identity
API key name. Required only if key_type
was set to backend
List of phone numbers to be validated during the identity verification process
Get Result
This API endpoint allows you to retrieve the current state and information of a process. The status
starts in pending
. When the process finishes, it can either be success
or failure
.
-
Pending means the process is still ongoing
-
Success occurs when all the steps in the process are successful, and if the flow has validators, all
validation_status
are successful. -
Failure can occur due to an internal error, a timeout, or if the process is declined or expired.
-
Here’s a complete reference of the reasons why a process can expire. These reasons are set in the
declined_reason
field.
Reason | Explanation |
---|---|
not_used |
When the user leaves at the beginning of the process without activating any validation |
no_document_media_uploaded |
When a process expires because the user did not upload the document files for the document validation step. |
no_face_media_uploaded |
When a process expires because the user did not upload the the selfie or video for the face validation step. |
no_media_uploaded |
When a process expires because the user did not upload the required file for the step. |
process_started_late |
When the process was started 3 minutes before expiring. Most likely the client did not had enough time to finish the flow. |
not_answered_question |
When a process expires because the user did not answer a question in the WhatsApp conversation. |
manual_review_not_performed |
When the process expires and the manual review is not completed. |
abandoned_without_using_retries |
When the user abandons the process after making one or more validation attempts, but does not use all retries. |
validation_not_finished |
When the process expires with some validation pending. |
validation_expired |
When we have a validation within the flow that has expired and the process also expires. |
user_process_postponed |
Indicates when the process finished because user chooses to postpone a process. |
geolocation_denied |
Indicates when the process finished because user declines permission for geolocation services. |
vpn_detected |
Indicates when the process finished because the system detects the use of a Virtual Private Network (VPN) by the user. |
no_face_detected |
When a face can’t be detected in a document. |
If a process has any validators and the identity process times out due to some validation not finishing, but all inputs have been uploaded, the process will have an additional 5 minutes to receive the validation response with the final status. This behavior will occur up to 3 times.
In the final attempt to get the last validation response with the final status, if the validation remains with a pending
status, he identity process status will be failure
and failure_status
will be expired
.
If a process has the attributes override_status
and override_status_history
, it means that the final status of the process was modified by an authorized user.
Therefore, the new attribute to know the final status of a process should be override_status
instead of status
and, 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).
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 Identity
Create WABA subscription
Identity Back
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
Create Outbound Messages
Required If is_notification is set False, it will be the content for the cancel option in the outbound message.
[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] 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] WABA in which this outbound template will be added.
[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.
[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 if the outbound type is not text.
[Required] Contains a text specifying the name of the outbound.
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
.
Identity Back
Provider Statuses
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.
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.
Cancell Campaign
List Outbound Messages
Get Outbound Message
Read Identity
Get Inbound Flow
Get Campaign
List WABA Lines
Get WABA Line
List Inbound Flows
List Identity
This API endpoint allows to retrieve the current state and information of all identity processes.
If a process has the attributes override_status
and override_status_history
, it means that the final status of the process was modified by an authorized user.
Therefore, the new attribute to know the final status of a process should be override_status
instead of status
and, the override_status_history
attribute will contain the history of changes made to the status.
Get Process Validations
Get Result
This API endpoint allows you to retrieve the current state and information of a process. The status
starts in pending
. When the process finishes, it can either be success
or failure
.
-
Pending means the process is still ongoing
-
Success occurs when all the steps in the process are successful, and if the flow has validators, all
validation_status
are successful. -
Failure can occur due to an internal error, a timeout, or if the process is declined or expired.
-
Here’s a complete reference of the reasons why a process can expire. These reasons are set in the
declined_reason
field.
Reason | Explanation |
---|---|
not_used |
When the user leaves at the beginning of the process without activating any validation |
no_document_media_uploaded |
When a process expires because the user did not upload the document files for the document validation step. |
no_face_media_uploaded |
When a process expires because the user did not upload the the selfie or video for the face validation step. |
no_media_uploaded |
When a process expires because the user did not upload the required file for the step. |
process_started_late |
When the process was started 3 minutes before expiring. Most likely the client did not had enough time to finish the flow. |
not_answered_question |
When a process expires because the user did not answer a question in the WhatsApp conversation. |
manual_review_not_performed |
When the process expires and the manual review is not completed. |
abandoned_without_using_retries |
When the user abandons the process after making one or more validation attempts, but does not use all retries. |
validation_not_finished |
When the process expires with some validation pending. |
validation_expired |
When we have a validation within the flow that has expired and the process also expires. |
user_process_postponed |
Indicates when the process finished because user chooses to postpone a process. |
geolocation_denied |
Indicates when the process finished because user declines permission for geolocation services. |
vpn_detected |
Indicates when the process finished because the system detects the use of a Virtual Private Network (VPN) by the user. |
no_face_detected |
When a face can’t be detected in a document. |
If a process has any validators and the identity process times out due to some validation not finishing, but all inputs have been uploaded, the process will have an additional 5 minutes to receive the validation response with the final status. This behavior will occur up to 3 times.
In the final attempt to get the last validation response with the final status, if the validation remains with a pending
status, he identity process status will be failure
and failure_status
will be expired
.
If a process has the attributes override_status
and override_status_history
, it means that the final status of the process was modified by an authorized user.
Therefore, the new attribute to know the final status of a process should be override_status
instead of status
and, the override_status_history
attribute will contain the history of changes made to the status.
Put WABA Line config
Update Outbound Message
Remove Outbound Message
Remove Inbound Flow
WA Contacts
Add, search and manage your customers (end users) in a single place.
Create contact property
Create contact
Get contact properties
Get contacts
Get contact
Update 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.
Verify Step Identity
Identity Back
Download PDF
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
Read user customers metrics
Main Validator Suite API
NOTE: Truora provides a Postman collection online that includes the necessary tools to simplify the testing process.
Welcome to Truora Validators Suite API [RESTful API] reference.
Truora Validatior Suite API allows performing identity validations in a variety of ways.
Do not forget, the Account ID is a user identifier that allows you to track the validations made. It is important to generate a unique identifier for each user who performs any type of validation, in order to avoid the possibility of information being crossed between users and to guarantee adequate monitoring for each one of them.
Validation steps
Most validations are performed by following these three simple steps:
Enrollment must be used for validators except for documents. Check out our Guide on Validation steps to learn more.
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 offer an easy way to identify validator users. A single validation account can be used in as many validations as you see fit. In order to streamline the process, a validation account is automatically created on enrollment unless an existing account_id is provided. Use custom-named validation accounts in order to easily trace your validation usage since validation accounts are automatically named with a random combination of numbers and letters if a custom name is not provided.
Create validation account
Person document type
Person e-mail address
Person first name
Person last name
Person phone number
Country where this person is located
Person document issue date. RFC3339 format
Person document number
Person Facebook username
Person Twitter username
List validation accounts
Get validation account
Get Enrollments by Account
Config
The Config feature allows you to customize the behavior of your various validators. This is particularly valuable when you wish to set different decision thresholds, timeouts, enable manual reviews, and more
Get config
Fetch configuration current state.
Note: This method gets all the validators configuration state of the account.
Update config
Allows updating the timeout, threshold, manual review, retries and other properties for a specific validator. Additionally the following validators have unique properties you can configure:
Document validation
-
Country: The country of the document you want
-
Document type: The type of document for which the document validation configuration will be created.
-
Document version: The document version of the document type.
-
Validation methods: This is a group of validation methods to be applied to the document. To modify the properties of any of them in your request send the attribute
validation_method.{{method}}.{{property}}
, where {{method}} is the selected method you wish to change and {{property}} is the selected property to change.For example:
validation_method.data-consistency.status: enabled
.
For more information on available document versions and methods, please contact our Sales team.
Face recognition
- Include Face Search: Boolean flag to include Truface (Search of input face in client and global face collections)
Merged configs
When a validation is executed, these parameters override a default config we have stored for any validation performed in Truora to make sure customers have all models up to date. For example:
Client Config | Default Config | Used Config (Client+Default) | |
---|---|---|---|
Allowed Retries | 2 | 3 | 2 |
Timeout | 900 | 300 | 900 |
Retries TTL | 300 | 300 |
Validator to be configured
Correctness required to pass the validation from 0 to 1
Status of the validation method photocopy-analysis
you want to enable or disable in the document validations execution.
Status of the validation method data-consistency
you want to enable or disable in the document validations execution.
Document type for which the document validation configuration will be created
Status of the validation method photo-of-photo
you want to enable or disable in the document validations execution.
Status of the validation method image-analysis
you want to enable or disable in the document validations execution.
Number of times users will be allowed to retry the validation
Include face search subvalidation in face-recognition validator execution
Time in seconds users will have to perform the validation
Status of the validation method government-database-validation
you want to enable or disable in the document validations execution.
Status of the validation method manual-review
you want to enable or disable in the document validations execution.
Document version of the document type
Country for which the document validation configuration will be created
Delete config
Allows deleting a validator config. Deleting the config sets its value back to the default value
Note: If you leave the field โtypeโ to delete empty, all the configuration is deleted.
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.
Name of the validation config to delete.
Validations
Validations is your tool for managing various validators such as face recognition, email verification, document checks, phone number validation, and electronic signatures. This API takes care of all logic needed for these validators, providing a single service where you can manage your multiple validators
Create new validation with account
Creates a new validation for the validation account. Check out our Guide on Liveness test to learn more about this feature.
Note: You need the account_id
from the first step and If you had already created an enrollment, it is not necessary to create one again for each validation.
Account ID linked with this validation. An automatic account id is created if left blank, otherwise, an account is created with the custom account id provided. As this account_id is linked to the validation, use it to trace the validations performed by the account later on. 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.
Indicates whether the validation subject consents to be validated. Must be true for the validation to proceed.
Validation type
Minimum precision that the audio transcription obtained from the video selfie should have with the speech_token. Required if you want to perform face validation with speech_match subvalidation.
Time in seconds users will have to perform the validation. If not provided the validation will use the timeout existing in the client’s config
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.
Indicates the name of the Check Type to use for the background check linked to this validation. Keep in mind that the Check Type must exist
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.
Phrase to be read out loud in the voice sample sent as RAW data in the PUT request to the upload_link
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, we recommend giving both options to the users
Language of the email that the final user receives
Language used to perform the validation via either the SMS or voice call
Phone number to be associated with the validation account on successful validation. Required for phone-verification. The type must have been already enrolled
[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.
You can select more than one. Indicates which subvalidations you want to perform during a face recognition execution. If empty we only use similarity
value
Likeness between the picture and the video required to pass the validation. By default, the threshold is set to 0.75
Perform validation
Create validation
Validation type
Account ID linked with this validation. An automatic account id is created if left blank, otherwise, an account is created with the custom account id provided. As this account_id is linked to the validation, use it to trace the validations performed by the account later on. 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.
Indicates whether the validation subject consents to be validated. Must be true for the validation to proceed.
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.
Indicates the name of the Check Type to use for the background check linked to this validation. Keep in mind that the Check Type must exist
Minimum precision that the audio transcription obtained from the video selfie should have with the speech_token. Required if you want to perform face validation with speech_match subvalidation.
Phrase to be read out loud in the voice sample sent as RAW data in the PUT request to the upload_link
Time in seconds users will have to perform the validation. If not provided the validation will use the timeout existing in the client’s config
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.
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, we recommend giving both options to the users
Language of the email that the final user receives
Language used to perform the validation via either the SMS or voice call
Phone number to be associated with the validation account on successful validation. Required for phone-verification. The type must have been already enrolled
[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.
You can select more than one. Indicates which subvalidations you want to perform during a face recognition execution. If empty we only use similarity
value
Likeness between the picture and the video required to pass the validation. By default, the threshold is set to 0.75
Perform validation
Get account validations
Get validation
Get validations
Get validation
Enrollments
Enrollments lets you to manage the logic required to navigate a user through various validators. This capability is valuable as it enables you to register a user just once and conduct multiple validations on that user seamlessly
Create enrollment
Indicates whether the enrollment subject consents to be enrolled. Must be true for the enrollment to proceed.
Validation type to be performed alongside with this enrollment
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, we recommend giving both options to the users
Account ID linked with this enrollment. An automatic account id is created if left blank, otherwise, an account is created with the custom account id provided. As this account_id is linked to the enrollment, use it to trace the enrollments/validations performed by the account later on. 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.
Indicates if a validation is required to complete the enrollment process. Only available for face-recognition validations. Note: if left blank the enrollment status will stay pending until a success face recognition validation is performed
Phone number to be associated with the verification account on successful validation. Required for phone-verification. The type must have been already enrolled
Get Enrollments by Account
Get enrollment
Delete enrollment
Status
Status lets you check the current state of our services in real time.