View as Markdown

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.

  • If you haven’t already, sign up for a free account here before generating your Truora-API-Key.
  • Learn how to generate your Truora-API-Key here.
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.

post

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.

CountryPerson-NationalPerson-ForeignerCompanyVehicle-NationalVehicle-Foreigner
Chile
CL		national_id*
date_of_birth
phone_number
issue_number		foreign_id*
date_of_birth*
phone_number
first_name*
last_name*
native_country*
issue_number		N/Anational_id*
license_plate*
driver_license (Santiago only)		foreign_id*
first_name*
last_name*
date_of_birth*
native_country*
license_plate*
driver_license (Santiago only)
Colombia
CO		national_id*
date_of_birth
issue_date
phone_number		foreign_id* or PPT*
date_of_birth*
phone_number
issue_date*		tax_id*
national_id		national_id*
date_of_birth
phone_number
license_plate*
owner_document_type
owner_document_id		foreign_id*
date_of_birth
phone_number
license_plate*
issue_date*
Mexico
MX		national_id*
phone_number

Alternative method: Use the following fields instead of national_id:
first_name*
last_name*
state_id*
gender*
date_of_birth*		foreign_id*tax_id*license_plate*
national_id
vehicle_id
driver_license(Estado de Mexico only)		N/A
Brazil
BR		national_id*
date_of_birth*
region*
phone_number		N/Atax_id*license_plate*N/A
Costa Rica
CR		national_id*
phone_number		foreign_id*
phone_number		N/Alicense_plate*N/A
Peru
PE		national_id*
date_of_birth*
phone_number		foreign_id*
ptp
date_of_birth
phone_number*		N/Anational_id*
date_of_birth*
license_plate*		foreign_id*
ptp
date_of_birth*
license_plate*
International
ALL		name*name*company_name*N/AN/A
(*) Required field

Request example
curl --request POST \
  --url 'https://api.checks.truora.com/v1/checks' \
  --header 'Truora-API-Key: {api_key}' \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data '{"country":"ALL","type":"person","user_authorized":true}'
Request body
application/x-www-form-urlencoded
country enum required
Allowed: ALL BR CO CL MX PE CR

Document country

user_authorized boolean required

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]

type enum required
Allowed: person vehicle company custom_type_name

Background check type. Replace custom_type_name with the name of your custom type to perform a custom type check

ptp string

ID for Venezuelans working in Peru

This field also apply for PPT (Permiso de Protección Temporal) in Colombia

birth_certificate string

Person birth certificate

custom_input string

Optional external identifier stored in the database along with the main structure. Used for reference purposes only, without affecting processing or logic. (Maximum length: 128 characters).

foreign_id string

Person foreign ID

gender enum
Allowed: male masculino hombre h female femenino mujer m

Person gender. Used for the Renapo (Registro Nacional de Poblacion) Alternative method in Mexico. Required in order to get complete background checks in Mexico instead national_id using Alternative method.

native_country enum
Allowed: CO MX PE BR EC CL VE

Country of birth. Required if native_national_id is provided

driver_license string

Driver’s license number

issue_date string

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

national_id string

National ID

owner_document_type string

national-id, foreign-id, tax-id or passport

professional_card string

Professional ID card

certificate_folio string

Folio for Chilean certificate search. Chile only

escrow string

Colombian escrow

imei string

15-digit IMEI to be validated

passport string

Person passport

issue_number string

Document number of Chilean identity. This number is used to get some additional information about a person. Chile only

verification_code string

Verification code registered for criminal records in Peru and Chile

report_id string

Report ID the background check will be inserted into

diplomatic_id string

Diplomatic ID

first_name string

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 and Mexico if alternative method for Renapo is used.

vehicle_id string

Vehicle NIV number

company_name string

Company name “Don’t forget this required field to complete background checks in Brazil”

date_of_birth string

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ú and Mexico if alternative method for Renapo is used.

native_national_id string

National ID from the person native country. Keep in mind that you must provide the native_country if you enter a native_national_id

pep string

ID for Venezuelans working in Colombia

watch string

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

owner_document_id string

ID of the vehicle owner

license_plate string

Vehicle license plate

payment_date string

Payment day of a vehicle circulation permit (Chile only)

region enum
Allowed: DF AC AL AP AM BA CE ES GO MA MT MS MG PA PB PR PE PI RJ RN RS RO RR SC SP SE TO ALL

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

state_id string

Used for the RG (Registro Geral) identification in Brazil, and Renapo (Registro Nacional de Personas) identification in Mexico. 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 and Mexico if alternative method for Renapo is used.

tax_id string

Company ID used for tax payments

force_creation boolean

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.

phone_number string

Person phone number. Required by law to notify the person their background is being checked

last_name string

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 and Mexico if alternative method for Renapo is used.

Response
post

Receive webhook

Receives a webhook for the given webhook type. Body can be JSON, XML, or form-data.
Request example
curl --request POST \
  --url 'https://api.checks.truora.com/v1/webhooks/{webhook_type}' \
  --header 'Truora-API-Key: {api_key}'
Response
Path Parameters
webhook_type string required

The type of webhook (e.g., complyadvantage, etc.)

get

List checks

Lists all the existing checks created in the account. If report_id is provided, it will only return the checks from the report
Request example
curl --request GET \
  --url 'https://api.checks.truora.com/v1/checks' \
  --header 'Truora-API-Key: {api_key}'
Response
Query Parameters
report_id string optional

ID of the report of background checks to be returned.

start_key string optional

Start key value for the pagination.

get

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.

Request example
curl --request GET \
  --url 'https://api.checks.truora.com/v1/checks/{check_id}' \
  --header 'Truora-API-Key: {api_key}'
Response
Path Parameters
check_id string required

A unique identifier for a check.

get

Get Check Attachments

Enables the download of PDF documents associated with the check result. This will list all the files found for a given check and provide the link for downloading
Request example
curl --request GET \
  --url 'https://api.checks.truora.com/v1/checks/{check_id}/attachments' \
  --header 'Truora-API-Key: {api_key}'
Response
Path Parameters
check_id string required

A unique identifier for a check.

get

List Check Details

Lists all details associated with a check, with support for pagination. It includes a list of data sources along with their respective information
Request example
curl --request GET \
  --url 'https://api.checks.truora.com/v1/checks/{check_id}/details' \
  --header 'Truora-API-Key: {api_key}'
Response
Path Parameters
check_id string required

A unique identifier for a check.

Query Parameters
lang string optional

Specifies the desired language for details; use lowercase ISO 639-1 format. If not specified, details will be provided in their original language.

start_key string optional

Start key value for the pagination.

get

Summarize

Returns a summary in a human readable way for the specified check id. It is useful when the details of the check are too long when reviewing manually
Request example
curl --request GET \
  --url 'https://api.checks.truora.com/v1/checks/{check_id}/summarize' \
  --header 'Truora-API-Key: {api_key}'
Response
Path Parameters
check_id string required

A unique identifier for a check.

get

Get the status of a database

Retrieve the current status of all databases that match with query parameters. This endpoint assists in determining the suitability of making a Check, allowing to review the availability of a database at any given moment.
Request example
curl --request GET \
  --url 'https://api.checks.truora.com/v1/health?country={country}&unixTimestampSeconds={unixTimestampSeconds}&unixtimezoneOffsetSeconds={unixtimezoneOffsetSeconds}' \
  --header 'Truora-API-Key: {api_key}'
Response
Query Parameters
country string required

Country code in uppercase ISO 3166 format (e.g., CO for Colombia).

unixTimestampSeconds number required

Unix timestamp in seconds. Send a day timestamp to view the database hourly status for that day or send the current time to know the current database status.

unixtimezoneOffsetSeconds number required

Offset between the local time and the UTC time in seconds. (e.g., Colombia is at UTC -18000 seconds).

delete

Delete check

Deletes the check that matches the Check ID provided, along with relevant information about that specific check. If the check belongs to a continuous check, it will be deleted only if isn’t the first one.
Request example
curl --request DELETE \
  --url 'https://api.checks.truora.com/v1/checks/{check_id}' \
  --header 'Truora-API-Key: {api_key}'
Response
Path Parameters
check_id string required

A unique identifier for a 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.

post

Create custom type

Create a custom type selecting the weight for each background check dataset and the country where it applies. Weights are numbers between 0 and 1 that represent how impactful the dataset is for the score, where datasets with weight 0 do not influence the score but are searched nonetheless. Keep in mind that the sum of all weights must equal 1. To perform a check with the custom type, create a Check and enter the name you gave to your custom type in type
Request example
curl --request POST \
  --url 'https://api.checks.truora.com/v1/config' \
  --header 'Truora-API-Key: {api_key}' \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data '{"country":"ALL","type":"string"}'
Request body
application/x-www-form-urlencoded
country enum required
Allowed: ALL BR CL CO MX PE

Country where this set of rules applies. Use “all” if the check type searches by name by relying on international databases

type string required

Custom type name. It cannot be person, vehicle, or company. Use this type in your checks to perform custom-type checks

dataset_driving_licenses number

Driving license weight for score calculation. From 0 to 1. If not provided, the dataset is skipped entirely decreasing the search time

dataset_affiliations_and_insurances number

Affiliation and insurance weight for score calculation. From 0 to 1. If not provided, the dataset is skipped entirely decreasing the search time

dataset_alert_in_media number

Alert in media weight for score calculation. From 0 to 1. If not provided, the dataset is skipped entirely decreasing the search time

dataset_criminal_record number

Criminal record weight for score calculation. From 0 to 1. If not provided, the dataset is skipped entirely decreasing the search time

dataset_business_background number

Business background weight for score calculation. From 0 to 1. If not provided, the dataset is skipped entirely decreasing the search time

dataset_personal_identity number

Personal identity weight for score calculation. From 0 to 1. If not provided, the dataset is skipped entirely decreasing the search time

dataset_taxes_and_finances number

Taxes and financial background weight for score calculation. From 0 to 1. If not provided, the dataset is skipped entirely decreasing the search time

dataset_vehicle_information number

Vehicle information weight for score calculation. From 0 to 1. If not provided, the dataset is skipped entirely decreasing the search time

dataset_vehicle_permits number

Vehicle certificate background weight for score calculation. From 0 to 1. If not provided, the dataset is skipped entirely decreasing the search time

dataset_professional_background number

Professional background weight for score calculation. From 0 to 1. If not provided, the dataset is skipped entirely decreasing the search time

dataset_traffic_fines number

Traffic fines weight for score calculation. From 0 to 1. If not provided, the dataset is skipped entirely decreasing the search time

dataset_international_background number

International background weight for score calculation. From 0 to 1. If not provided, the dataset is skipped entirely decreasing the search time

dataset_legal_background number

Legal background weight for score calculation. From 0 to 1. If not provided, the dataset is skipped entirely decreasing the search time

Response
put

Update custom type

Allows updating a custom type. Person, vehicle, and company types are not modifiable. Please visit How to Create a Custom Type for Background Check guide for more information.
Request example
curl --request PUT \
  --url 'https://api.checks.truora.com/v1/config' \
  --header 'Truora-API-Key: {api_key}' \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data '{"country":"ALL","type":"string"}'
Request body
application/x-www-form-urlencoded
country enum required
Allowed: ALL BR CL CO MX PE

Country where this set of rules applies. Use “all” if the check type searches by name by relying on international databases

type string required

Custom type name. It cannot be person, vehicle, or company. Use this type in your checks to perform custom-type checks

dataset_alert_in_media number

Alert in media weight for score calculation. From 0 to 1. If not provided, the dataset is skipped entirely decreasing the search time

dataset_international_background number

International background weight for score calculation. From 0 to 1. If not provided, the dataset is skipped entirely decreasing the search time

dataset_business_background number

Business background weight for score calculation. From 0 to 1. If not provided, the dataset is skipped entirely decreasing the search time

dataset_affiliations_and_insurances number

Affiliation and insurance weight for score calculation. From 0 to 1. If not provided, the dataset is skipped entirely decreasing the search time

dataset_legal_background number

Legal background weight for score calculation. From 0 to 1. If not provided, the dataset is skipped entirely decreasing the search time

dataset_criminal_record number

Criminal record weight for score calculation. From 0 to 1. If not provided, the dataset is skipped entirely decreasing the search time

dataset_driving_licenses number

Driving license weight for score calculation. From 0 to 1. If not provided, the dataset is skipped entirely decreasing the search time

dataset_personal_identity number

Personal identity weight for score calculation. From 0 to 1. If not provided, the dataset is skipped entirely decreasing the search time

dataset_taxes_and_finances number

Taxes and financial background weight for score calculation. From 0 to 1. If not provided, the dataset is skipped entirely decreasing the search time

dataset_vehicle_information number

Vehicle information weight for score calculation. From 0 to 1. If not provided, the dataset is skipped entirely decreasing the search time

dataset_vehicle_permits number

Vehicle certificate background weight for score calculation. From 0 to 1. If not provided, the dataset is skipped entirely decreasing the search time

dataset_professional_background number

Professional background weight for score calculation. From 0 to 1. If not provided, the dataset is skipped entirely decreasing the search time

dataset_traffic_fines number

Traffic fines weight for score calculation. From 0 to 1. If not provided, the dataset is skipped entirely decreasing the search time

Response
get

List custom types

Lists all custom types of the associated account. Please visit How to Create a Custom Type for Background Check guide for more information.
Request example
curl --request GET \
  --url 'https://api.checks.truora.com/v1/config' \
  --header 'Truora-API-Key: {api_key}'
Response
Query Parameters
start_key string optional

Start key value for the pagination.

delete

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.

Request example
curl --request DELETE \
  --url 'https://api.checks.truora.com/v1/config?country={country}&type={type}' \
  --header 'Truora-API-Key: {api_key}'
Response
Query Parameters
country string required

Country where the custom type is valid. Use ISO 3166 format in uppercase (e.g., CO for Colombia)

type string required

Name of the custom type to be deleted.

Settings

Allows the configuration of parameters such as names matching type, retries and max duration.

post

Create setting

Allows setting up both retries and names matching type. Keep in mind that this feature is a configuration at a Client level, so it will affect all your check types.
Request example
curl --request POST \
  --url 'https://api.checks.truora.com/v1/settings' \
  --header 'Truora-API-Key: {api_key}'
Request body
application/x-www-form-urlencoded
max_duration string

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

names_matching_type enum
Allowed: soft exact

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

retries boolean

Indicates whether or not database queries must be retried until they successfully return a response or until the max_duration time is reached

Response

Credentials

Allows the management of credentials for the checks API.

post

Create or update credential

Creates or updates a collector credential for the specified database including username, password and authentication complements
Request example
curl --request POST \
  --url 'https://api.checks.truora.com/v1/config/credentials/{database_id}' \
  --header 'Truora-API-Key: {api_key}' \
  --header 'Content-Type: application/json' \
  --data '{"password":"string","username":"string"}'
Request body
application/json
username string required

Username for the collector credential

password string required

Password for the collector credential

complements_for_authentication array

Additional authentication complements

Response
get

List credentials

Lists all collector credentials for the associated account only including database information and available options for management
Request example
curl --request GET \
  --url 'https://api.checks.truora.com/v1/config/credentials' \
  --header 'Truora-API-Key: {api_key}'
Response
delete

Delete credential

Deletes a collector credential for the specified database only using the database ID as a path parameter
Request example
curl --request DELETE \
  --url 'https://api.checks.truora.com/v1/config/credentials/{database_id}' \
  --header 'Truora-API-Key: {api_key}'
Response

Continuous

Enables the creation of recurring checks with customizable frequency, providing notifications whenever there are changes in check scores.

post

Create Continuous Check

Creates a continuous check that will run background checks recurrently according to the frequency provided.
Request example
curl --request POST \
  --url 'https://api.checks.truora.com/v1/continuous-checks' \
  --header 'Truora-API-Key: {api_key}' \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data '{"check_id":"string","end_date":"string","frequency":"string"}'
Request body
application/x-www-form-urlencoded
frequency string required

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

end_date string required

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.

check_id string required

Background checks to be processed recurrently

Response
put

Update Continuous Checks

Updates a continuous check using its ID. This method can only modify its frequency and status
Request example
curl --request PUT \
  --url 'https://api.checks.truora.com/v1/continuous-checks/{continuous_check_id}' \
  --header 'Truora-API-Key: {api_key}'
Request body
application/x-www-form-urlencoded
version enum
Allowed: 0 1

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.

frequency string

Time between background checks

status enum
Allowed: enabled disabled

Indicates whether the background checks must be processed recurrently

Response
Path Parameters
continuous_check_id string required

Unique ID assigned after calling CreateContinuousCheck.

get

List Continuous Checks

Lists all continuous checks created in the given account. This method returns the ’next’ attribute to paginate for the next results
Request example
curl --request GET \
  --url 'https://api.checks.truora.com/v1/continuous-checks' \
  --header 'Truora-API-Key: {api_key}'
Response
get

Get Continuous Checks

Returns the specified continuous check using its ID. This method returns the last check executed and provides information such as frequency, status, count and end date
Request example
curl --request GET \
  --url 'https://api.checks.truora.com/v1/continuous-checks/{continuous_check_id}' \
  --header 'Truora-API-Key: {api_key}'
Response
Path Parameters
continuous_check_id string required

Unique ID assigned after calling CreateContinuousCheck.

get

List Continuous Check Logs

Returns Continuous Check Logs. These logs are useful for analyzing the behavior of the check over time. Each entry includes details of what changed
Request example
curl --request GET \
  --url 'https://api.checks.truora.com/v1/continuous-checks/{continuous_check_id}/history' \
  --header 'Truora-API-Key: {api_key}'
Response
Path Parameters
continuous_check_id string required

Unique ID assigned after calling CreateContinuousCheck.

PDF

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.

post

Create PDF

Create PDF receives a check id and starts the conversion to PDF. Once the method is finished, it will return a link where the file can be downloaded
Request example
curl --request POST \
  --url 'https://api.checks.truora.com/v1/checks/{check_id}/pdf' \
  --header 'Truora-API-Key: {api_key}'
Response
Path Parameters
check_id string required

A unique identifier for a check.

get

Get PDF

Get PDF downloads the PDF in the specified language, Spanish by default. This endpoint must be called after making the POST call
Request example
curl --request GET \
  --url 'https://api.checks.truora.com/v1/checks/{check_id}/pdf' \
  --header 'Truora-API-Key: {api_key}'
Response
Path Parameters
check_id string required

A unique identifier for a check.

Query Parameters
lang string optional

Specifies the language of the PDF; use lowercase ISO 639-1 format. If not specified, the PDF will be downloaded in Spanish by default.

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.

post

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.

Request example
curl --request POST \
  --url 'https://api.checks.truora.com/v1/batches' \
  --header 'Truora-API-Key: {api_key}' \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data '{"country":"ALL","service":"checks","type":"person"}'
Request body
application/x-www-form-urlencoded
type enum required
Allowed: person vehicle company custom_type_name

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.

service enum required
Allowed: checks

The service for which the batch will be processed

country enum required
Allowed: ALL BR CO CL MX PE CR

The country of batch checks

end_date string

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.

frequency string

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

columns_mapping.{input_name} number

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.

Response
post

Request Batch Report Generation

This endpoint requests the generation of a report for a specific batch. The format of the report can be specified via a query param.
Request example
curl --request POST \
  --url 'https://api.checks.truora.com/v1/batches/{batch_id}/report' \
  --header 'Truora-API-Key: {api_key}' \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data '{"format":"string"}'
Request body
application/x-www-form-urlencoded
format string required

Batch report file format

Response
Path Parameters
batch_id string required

Unique identifier of the batch.

post

Start Batch

This endpoint starts the execution of a specific batch. The batch needs to have an uploaded file for this to succeed.
Request example
curl --request POST \
  --url 'https://api.checks.truora.com/v1/batches/{batch_id}/start' \
  --header 'Truora-API-Key: {api_key}'
Response
Path Parameters
batch_id string required

Unique identifier of the batch.

put

Stop Batch

This endpoint is used to stop a specific batch (updating its status to “stopped”) only if it’s currently in progress or not started yet.
Request example
curl --request PUT \
  --url 'https://api.checks.truora.com/v1/batches/{batch_id}' \
  --header 'Truora-API-Key: {api_key}'
Response
Path Parameters
batch_id string required

Unique identifier of the batch.

get

Get Batch

This endpoint returns a specific batch’s information, including its creation date, size, status and failure reason.
Request example
curl --request GET \
  --url 'https://api.checks.truora.com/v1/batches/{batch_id}' \
  --header 'Truora-API-Key: {api_key}'
Response
Path Parameters
batch_id string required

Unique identifier of the batch.

get

Get Batch Report

This endpoint obtains a previously requested batch report. If no report exists yet for the batch it returns a 404 response.
Request example
curl --request GET \
  --url 'https://api.checks.truora.com/v1/batches/{batch_id}/report' \
  --header 'Truora-API-Key: {api_key}'
Response
Path Parameters
batch_id string required

Unique identifier of the batch.

Shared Accounts

Truora Shared accounts API allows accessing services that are transversal to all other services like Background checks or Validators

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.

  • If you haven’t already, sign up for a free account here before generating your Truora-API-Key.
  • Learn how to generate your Truora-API-Key here.
Base URL

https://api.account.truora.com

Rules

This is a set of endpoints that allow you to create, modify and delete rules for executing actions based on the data of the events.

post

Create Rule

Creates a new BRE rule. Request body is application/x-www-form-urlencoded with name, event_type, condition and optional event_actions.
Request example
curl --request POST \
  --url 'https://api.account.truora.com/v1/bre/rules' \
  --header 'Truora-API-Key: {api_key}'
Request body
application/x-www-form-urlencoded
condition string

Condition for the rule, written in jsonlogic

event_type enum
Allowed: checks.check.finished

Event type

name string

Rule name

Response
post

Set action env var

Creates or updates an environment variable for the action. Body is application/x-www-form-urlencoded with name, value and secret.
Request example
curl --request POST \
  --url 'https://api.account.truora.com/v1/bre/rules/{rule_id}/actions/{action_id}/envs' \
  --header 'Truora-API-Key: {api_key}'
Request body
application/x-www-form-urlencoded
name string

Variable name (must start with a letter, alphanumeric and underscore only)

secret boolean

Whether the value is stored as secret (encrypted)

value string

Variable value

Response
put

Edit Rule

Updates an existing BRE rule by rule_id. Request body is application/x-www-form-urlencoded with name, event_type, condition and optional event_actions.
Request example
curl --request PUT \
  --url 'https://api.account.truora.com/v1/bre/rules/{rule_id}' \
  --header 'Truora-API-Key: {api_key}'
Request body
application/x-www-form-urlencoded
condition string

Condition for the rule, written in jsonlogic

event_type enum
Allowed: checks.check.finished

Event type

name string

Rule name

Response
get

List Rules

Returns a paginated list of BRE rules for the client. Response includes rules array, self and next links.
Request example
curl --request GET \
  --url 'https://api.account.truora.com/v1/bre/rules' \
  --header 'Truora-API-Key: {api_key}'
Response
get

Get Rule

Returns a single BRE rule by rule_id. The response includes the rule condition, event_type, creation and update dates, status and optional event_actions.
Request example
curl --request GET \
  --url 'https://api.account.truora.com/v1/bre/rules/{rule_id}' \
  --header 'Truora-API-Key: {api_key}'
Response
get

Get action env vars

Returns the list of environment variables for the action. Each variable has name, secret flag and value; secret values are not returned in the response.
Request example
curl --request GET \
  --url 'https://api.account.truora.com/v1/bre/rules/{rule_id}/actions/{action_id}/envs' \
  --header 'Truora-API-Key: {api_key}'
Response
delete

Delete Rule

Deletes a BRE rule by rule_id. Permanently removes the rule and its actions. Returns a success message when the deletion completes successfully.
Request example
curl --request DELETE \
  --url 'https://api.account.truora.com/v1/bre/rules/{rule_id}' \
  --header 'Truora-API-Key: {api_key}'
Response
delete

Delete env var

Deletes an environment variable from the action by var_name. Permanently removes the variable. Returns a success message when the deletion completes.
Request example
curl --request DELETE \
  --url 'https://api.account.truora.com/v1/bre/rules/{rule_id}/actions/{action_id}/envs/{var_name}' \
  --header 'Truora-API-Key: {api_key}'
Response

Variables

Variables are the data that can be used to create rules and actions.

get

Get variables spec

Returns the variables specification for building BRE conditions. Response includes variables_spec object with available variable paths and types.
Request example
curl --request GET \
  --url 'https://api.account.truora.com/v1/bre/variables-spec' \
  --header 'Truora-API-Key: {api_key}'
Response

Actions

Actions are the actions that can be executed when a rule is triggered.

post

Create Rule Action

Creates an action for the rule. Request body is application/x-www-form-urlencoded with name, type, config and optional status.
Request example
curl --request POST \
  --url 'https://api.account.truora.com/v1/bre/rules/{rule_id}/actions' \
  --header 'Truora-API-Key: {api_key}'
Request body
application/x-www-form-urlencoded
status enum
Allowed: enabled disabled

Action status

type enum
Allowed: http_request email create_check

Action type

name string

Action name

Response
put

Update Action

Updates an action by action_id. Request body is application/x-www-form-urlencoded with name, type, config and optional status.
Request example
curl --request PUT \
  --url 'https://api.account.truora.com/v1/bre/rules/{rule_id}/actions/{action_id}' \
  --header 'Truora-API-Key: {api_key}'
Request body
application/x-www-form-urlencoded
name string

Action name

status enum
Allowed: enabled disabled

Action status

type enum
Allowed: http_request email create_check

Action type

Response
get

Get Rule Actions

Returns a paginated list of actions for the rule. Each action has type, config, status and dates.
Request example
curl --request GET \
  --url 'https://api.account.truora.com/v1/bre/rules/{rule_id}/actions' \
  --header 'Truora-API-Key: {api_key}'
Response
delete

Delete Action

Deletes an action from the rule by action_id. Permanently removes the action and its environment variables. Returns success when the deletion completes.
Request example
curl --request DELETE \
  --url 'https://api.account.truora.com/v1/bre/rules/{rule_id}/actions/{action_id}' \
  --header 'Truora-API-Key: {api_key}'
Response

Users

Manage the users of your account — create, list, update, activate/deactivate, and delete users for backend/M2M provisioning.

post

Create User

Creates a user in the account and provisions it in the underlying identity store, then sends the new user an activation email.
Request example
curl --request POST \
  --url 'https://api.account.truora.com/v1/account/users' \
  --header 'Truora-API-Key: {api_key}' \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data '{"country":"string","email":"string","language":"es","phone_number":"string"}'
Request body
application/x-www-form-urlencoded
language enum required
Allowed: es en pt

Language used for the user communications

email string required

Email of the user. Becomes the username and is stored lowercased

country string required

Country code specified in ISO 3166 Alpha-2 format, for example CO for Colombia

phone_number string required

Phone number in E.164 format, for example +573001234567

role_name string

Role assigned to the user. Defaults to default_access and must reference an existing role

billing_hub string

Billing hub for the user. Required when the tenant has billing hubs and must match one of them exactly

name string

Display name of the user

Response
put

Update User

Updates one or more attributes of an existing user, such as role_name, name, billing_hub or phone_number. Send only the fields you want to change; at least one is required.
Request example
curl --request PUT \
  --url 'https://api.account.truora.com/v1/account/users/{username}' \
  --header 'Truora-API-Key: {api_key}'
Request body
application/x-www-form-urlencoded
role_name string

Name of the role to be assigned to the user. Must reference an existing role

billing_hub string

Billing hub for the user. Stored uppercased and must match a tenant billing hub

name string

Display name of the user

phone_number string

Phone number in E.164 format, for example +573009876543

Response
Path Parameters
username string required

The user’s username, typically their email. URL-encode @ and + characters.

get

List Users

Returns a paginated list of the users registered in the account. System users are filtered out. Supply the start_key returned in the next link to fetch the following page.
Request example
curl --request GET \
  --url 'https://api.account.truora.com/v1/account/users' \
  --header 'Truora-API-Key: {api_key}'
Response
Query Parameters
start_key string optional

Pagination cursor taken from the next link of a previous response.

delete

Delete User

Permanently deletes a user from the account. The user is identified by the email field sent in the application/x-www-form-urlencoded request body, not in the URL path.
Request example
curl --request DELETE \
  --url 'https://api.account.truora.com/v1/account/users' \
  --header 'Truora-API-Key: {api_key}' \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data '{"email":"string"}'
Request body
application/x-www-form-urlencoded
email string required

Email of the user to delete. Identifies the user in the request body, not in the URL path

Response
patch

Activate / Deactivate User

Enables or disables a user’s login access without deleting the user. Send status (enabled or disabled) plus a reason in the request body. Useful for reversible offboarding.
Request example
curl --request PATCH \
  --url 'https://api.account.truora.com/v1/account/users/{username}/status' \
  --header 'Truora-API-Key: {api_key}'
Request body
application/x-www-form-urlencoded
reason string

Reason for the status change. Required and stored in the audit log

status enum
Allowed: enabled disabled

New status of the user in the account. One of enabled or disabled

Response
Path Parameters
username string required

Username

Roles and Permissions

Create and manage roles, assign permissions to them, and list the permissions available in your account.

post

Create Role

Creates a role that groups a set of permissions. The role name must be unique and cannot be full_access or default_access. Permissions must belong to the account master set.
Request example
curl --request POST \
  --url 'https://api.account.truora.com/v1/roles' \
  --header 'Truora-API-Key: {api_key}'
Request body
application/x-www-form-urlencoded
description string

Human-readable description of the role

permissions enum
Allowed: checks.behavior checks.country_all checks.country_ar checks.country_br checks.country_cl checks.country_co checks.country_co_premium checks.country_cr checks.country_ec checks.country_mx checks.country_pa checks.country_pe truora.keys truora.users validations.cell_phone_validation_br validations.cell_phone_validation_co validations.cell_phone_validation_mx validations.documents_validation_br validations.documents_validation_co validations.documents_validation_mx validations.email_validation validations.enterprise_data validations.face_recognition validations.identity_questions validations.voice_recognition

Enter this field as many times as necessary in order to include all permissions

role_name string

Role name. It must be unique and also cannot be full_access or default_access

rules string

Optional JSON-Logic access rule. Repeat the field for each rule

Response
put

Update Role

Updates an existing role identified by role_name. This is not an upsert; the role must already exist. Send the new permission set and optionally rename the role.
Request example
curl --request PUT \
  --url 'https://api.account.truora.com/v1/roles/{role_name}' \
  --header 'Truora-API-Key: {api_key}'
Request body
application/x-www-form-urlencoded
description string

Human-readable description of the role

permissions enum
Allowed: checks.behavior checks.country_all checks.country_ar checks.country_br checks.country_cl checks.country_co checks.country_co_premium checks.country_cr checks.country_ec checks.country_mx checks.country_pa checks.country_pe truora.keys truora.users validations.cell_phone_validation_br validations.cell_phone_validation_co validations.cell_phone_validation_mx validations.documents_validation_br validations.documents_validation_co validations.documents_validation_mx validations.email_validation validations.enterprise_data validations.face_recognition validations.identity_questions validations.voice_recognition

Enter this field as many times as necessary in order to include all permissions

role_name string

Role name. It must be unique and also cannot be full_access or default_access

rules string

Optional JSON-Logic access rule. Repeat the field for each rule

Response
Path Parameters
role_name string required

The name of the role to operate on.

get

List Permissions

Returns the permissions available to the account (the master set), or the calling user’s effective permissions when the list=user query parameter is supplied.
Request example
curl --request GET \
  --url 'https://api.account.truora.com/v1/permissions' \
  --header 'Truora-API-Key: {api_key}'
Response
Query Parameters
list string optional

Optional. Use list=user to return the calling user’s role permissions instead of the account master set.

get

List Roles

Returns a paginated list of the roles defined in the account, each with its permissions and access rules. Supply start_key to fetch the next page.
Request example
curl --request GET \
  --url 'https://api.account.truora.com/v1/roles' \
  --header 'Truora-API-Key: {api_key}'
Response
Query Parameters
start_key string optional

Pagination cursor taken from the next link of a previous response.

get

Get Role

Returns a single role of the account by its role_name, including the permissions it grants and its access rules.
Request example
curl --request GET \
  --url 'https://api.account.truora.com/v1/roles/{role_name}' \
  --header 'Truora-API-Key: {api_key}'
Response
Path Parameters
role_name string required

The name of the role to operate on.

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.

  • If you haven’t already, sign up for a free account here before generating your Truora-API-Key.
  • Learn how to generate your Truora-API-Key here.
Base URL

https://api.identity.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.

post

Generate Token

Once the flow has been created and published, a POST request must be made to generate a temporary API Key. This should be generated every time a user validation is performed.
Request example
curl --request POST \
  --url 'https://api.identity.truora.com/v1/api-keys' \
  --header 'Truora-API-Key: {api_key}' \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data '{"key_type":"backend"}'
Request body
application/x-www-form-urlencoded
key_type enum required
Allowed: backend web

API key type

country enum
Allowed: ALL BR CL CO CR EC MX PE AR SV

Country for the identity verification process. Required only if grant is set to digital-identity

emails array

List of emails to be validated during the identity verification process

redirect_url string

URL where the user is to be redirected once the verification process has ended. Required if grant is set to digital-identity

billing_hub string

Billing hubs allow for separated counters and billing. Required if the customer uses billing hubs

document_type enum
Allowed: passport driver-license foreign-id national-id pep

Document type for the identity verification process. Only used if grant is set to digital-identity

flow_id string

Validation flow to be performed for the identity verification process. Required only if grant is set to digital-identity

grant enum
Allowed: digital-identity signals

Indicates which service this API key grants access to. Required if key_type is set to web or sdk

key_name string

API key name. Required only if key_type was set to backend

phones array

List of phone numbers to be validated during the identity verification process

account_id string

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.

api_key_version string

API key version. Version 0 is used by default

Response
get

Download Process PDF

Retrieves the PDF document for a specified process by its ID.

If the PDF has not been requested before, it is generated first, progressing through:

  • 202 Accepted → "file_status": "requested"
  • 202 Accepted → "file_status": "in_progress"
  • 302 Found * → Redirects to the PDF file when ready
  • 200 OK → Returns the file

If the PDF has already been generated, the response immediately returns:

  • 302 Found * → Redirects to the PDF file when ready
  • 200 OK → Returns the file

Polling: If the file is not ready (202 Accepted), retry until 302 Found or 200 OK.

* 302 Redirect Handling: Most API clients and browsers follow redirects automatically. However, if your API client does not, extract the Location header containing the PDF’s URL and make a GET request to download the file.

Request example
curl --request GET \
  --url 'https://api.identity.truora.com/v1/processes/{process_id}/pdf' \
  --header 'Truora-API-Key: {api_key}'
Response
Path Parameters
process_id string required

The ID of the completed process for which the PDF is requested.

get

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_status values 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.

Request example
curl --request GET \
  --url 'https://api.identity.truora.com/v1/processes/{process_id}/result' \
  --header 'Truora-API-Key: {api_key}'
Response
Path Parameters
process_id string required

The ID of the process for which results are being retrieved.

get

Download Process Video Call Recordings

Retrieves the video call recordings for a specified process by its ID.

If the video call recordings have not been requested before, it is generated first, progressing through:

  • 202 Accepted → "file_status": "requested"
  • 202 Accepted → "file_status": "in_progress"
  • 302 Found * → Redirects to the video call recordings file when ready
  • 200 OK → Returns the file

If the video call recordings have already been generated, the response immediately returns:

  • 302 Found * → Redirects to the video call recordings file when ready
  • 200 OK → Returns the file

Polling: If the file is not ready (202 Accepted), retry until 302 Found or 200 OK.

* 302 Redirect Handling: Most API clients and browsers follow redirects automatically. However, if your API client does not, extract the Location header containing the video call recordings’s URL and make a GET request to download the file.

Request example
curl --request GET \
  --url 'https://api.identity.truora.com/v1/processes/{process_id}/video-call-recordings' \
  --header 'Truora-API-Key: {api_key}'
Response
Path Parameters
process_id string required

The ID of the completed process for which the video call recordings is requested.

WhatsApp

Manage WhatsApp Business lines, inbound flows, campaigns, and sessions.

post

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

Request example
curl --request POST \
  --url 'https://api.identity.truora.com/v1/whatsapp/inbounds' \
  --header 'Truora-API-Key: {api_key}'
Request body
application/x-www-form-urlencoded
flow_id string

Identifier of the Flow previously created.

inbound_message string

Unique message the users will be sending to the business WhatsApp (WABA) in order to begin the Flow.

waba_phone_number string

Phone number of the WABA that interacts with the users. Must include the country code. Example 14080001111.

Response
post

Create WABA subscription

This endpoint allows users to create a WhatsApp Business Account (WABA) subscription. Users can initiate and configure the subscription process by providing the necessary information to establish a connection or subscription with a WABA, facilitating communication and interaction with WhatsApp users.
Request example
curl --request POST \
  --url 'https://api.identity.truora.com/v1/whatsapp/waba-subscription' \
  --header 'Truora-API-Key: {api_key}'
Response
post

Provider Statuses

This endpoint receives and processes the status of a WhatsApp message from a WhatsApp provider. It enables system to handle and manage the status information associated with WhatsApp messages, facilitating effective monitoring and processing of message delivery and engagement.
Request example
curl --request POST \
  --url 'https://api.identity.truora.com/v1/whatsapp/{provider}/statuses' \
  --header 'Truora-API-Key: {api_key}'
Response
post

Cancell Campaign

This endpoint offers the capability to cancel an active campaign. Users can initiate the cancellation process for a specific campaign, preventing further message deliveries and interactions. It provides a means to swiftly and effectively halt campaign activities when necessary.
Request example
curl --request POST \
  --url 'https://api.identity.truora.com/v1/whatsapp/campaigns/{campaign_id}/cancel' \
  --header 'Truora-API-Key: {api_key}'
Response
post

Finish WhatsApp session

Finishes an ongoing WhatsApp session for the given waba_phone_number and phone_number. The user is notified by WhatsApp that the session has ended. Optional body fields: reason (closure reason), closed_by (override; defaults to authenticated user from authorizer).
Request example
curl --request POST \
  --url 'https://api.identity.truora.com/v1/whatsapp/finish-whatsapp-session' \
  --header 'Truora-API-Key: {api_key}'
Response
post

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.

Request example
curl --request POST \
  --url 'https://api.identity.truora.com/v1/whatsapp/inbounds/{inbound_flow_id}' \
  --header 'Truora-API-Key: {api_key}'
Request body
application/x-www-form-urlencoded
flow_id string

Identifier of the Flow previously created.

inbound_message string

Unique message the users will be sending to the business WhatsApp (WABA) in order to begin the Flow.

waba_phone_number string

Phone number of the WABA that interacts with the users. Must include the country code. Example 14080001111.

Response
put

Put WABA Line config

This endpoint provides the functionality to configure and customize the details of a WhatsApp Business Account (WABA) line. Users can modify various parameters and preferences to tailor the configuration of their WABA line according to their specific needs and preferences.
Request example
curl --request PUT \
  --url 'https://api.identity.truora.com/v1/whatsapp/lines/{waba_line}/config' \
  --header 'Truora-API-Key: {api_key}'
Response
Path Parameters
default_flow_id string optional

The default_flow_id parameter is used to specify the ID of the default flow to be used in a WABA Line

get

Get WABA Line

This endpoint provides the functionality to retrieve detailed information about a WhatsApp Business Account (WABA) line. Users can access essential data related to the WABA line’s configuration, contact information, messaging capabilities, and integration options, facilitating effective management and utilization of the WABA line.
Request example
curl --request GET \
  --url 'https://api.identity.truora.com/v1/whatsapp/lines/{waba_line}' \
  --header 'Truora-API-Key: {api_key}'
Response
get

Get Inbound Flow

This endpoint allows users to retrieve information about a previously created inbound. Users can access details and data related to a specific inbound.
Request example
curl --request GET \
  --url 'https://api.identity.truora.com/v1/whatsapp/inbounds/{inbound_flow_id}' \
  --header 'Truora-API-Key: {api_key}'
Response
Path Parameters
inbound_flow_id string required

Unique identifier of inbound flows

get

List Inbound Flows

This endpoint allows users to retrieve a list of created inbound flows. Users can access information about each inbound flow.
Request example
curl --request GET \
  --url 'https://api.identity.truora.com/v1/whatsapp/inbounds' \
  --header 'Truora-API-Key: {api_key}'
Response
Query Parameters
start_key string optional

[Optional] start key value for pagination, if you want to go to the previous or next page.

get

List WABA Lines

This endpoint retrieves a list of WhatsApp Business (WABA) lines that have been assigned to a Truora account. It provides essential information about each WABA line, including line details, configuration settings, and associated data, allowing account holders to manage and monitor their WhatsApp Business lines efficiently.
Request example
curl --request GET \
  --url 'https://api.identity.truora.com/v1/whatsapp/lines' \
  --header 'Truora-API-Key: {api_key}'
Response
get

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_status values 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.

Request example
curl --request GET \
  --url 'https://api.identity.truora.com/v1/processes/{process_id}/result' \
  --header 'Truora-API-Key: {api_key}'
Response
Path Parameters
process_id string required

The ID of the process for which results are being retrieved.

get

Get Campaign

This endpoint provides the functionality to retrieve detailed information about a specific campaign. Users can access comprehensive data related to the campaign.
Request example
curl --request GET \
  --url 'https://api.identity.truora.com/v1/whatsapp/campaigns/{campaign_id}' \
  --header 'Truora-API-Key: {api_key}'
Response
Path Parameters
campaign_id string optional

Unique identifier for the campaign

get

Get Process Validations

This API endpoint allows you to retrieve the current state and information of the process validations.
Request example
curl --request GET \
  --url 'https://api.identity.truora.com/v1/processes/{process_id}/validations' \
  --header 'Truora-API-Key: {api_key}'
Response
get

List WABAs

This endpoint retrieves a list of WhatsApp Business Accounts that have been assigned to a Truora account.
Request example
curl --request GET \
  --url 'https://api.identity.truora.com/v1/whatsapp/wabas' \
  --header 'Truora-API-Key: {api_key}'
Response
delete

Remove Inbound Flow

This endpoint allows users to remove inbound flows. Users can initiate the removal process for specific inbound flows, effectively eliminating them from the system. It provides a means to manage and clean up inbound flows when they are no longer needed or relevant.
Request example
curl --request DELETE \
  --url 'https://api.identity.truora.com/v1/whatsapp/inbounds/{inbound_flow_id}' \
  --header 'Truora-API-Key: {api_key}'
Response
patch

Update WABA Line

This endpoint allows users to update the configuration of a WhatsApp Business Account (WABA) line both in the Truora platform and in meta.
Request example
curl --request PATCH \
  --url 'https://api.identity.truora.com/v1/whatsapp/lines/{waba_line}' \
  --header 'Truora-API-Key: {api_key}'
Response

WA Engagement

Increase your customer engagement by automating your customer service, marketing and sales process in WhatsApp.

post

Delete Agent Templates

This endpoint allows the deletion of agent message templates. Agent can specify the template names in the request body. The endpoint checks if template names are provided; if not, it returns an appropriate error message.
Request example
curl --request POST \
  --url 'https://api.identity.truora.com/v1/engagement/agent/templates/delete' \
  --header 'Truora-API-Key: {api_key}' \
  --header 'Content-Type: application/json' \
  --data '{"template_names":"string"}'
Request body
application/json
template_names array required

Array of the names of the templates that should be deleted.

Response
post

Update agent capacity settings

This endpoint allows toggling agent capacity functionality for an account and updating both default and user-specific capacity settings. For the latter update type, multiple capacities can be updated in a single request.
Request example
curl --request POST \
  --url 'https://api.identity.truora.com/v1/engagement/agent/capacities' \
  --header 'Truora-API-Key: {api_key}' \
  --header 'Content-Type: application/json' \
  --data '{"update_type":"user"}'
Request body
application/json
update_type enum required
Allowed: user default toggle_capacity

Determines the type of update to be performed. “toggle_capacity” is used to enable or disable the agent capacity feature. The other types are used to update default or user-specific capacity settings.

capacity integer

Capacity value to use for the update. Not required for “toggle_capacity” update type.

targets array

List of targets whose settings will be updated. Only required for “user” update type.

Response
post

Send Outbound Message

Sends an Outbound Message as a first interaction to an user. The Outbound Message status needs to be APPROVED before it can be sent.
Request example
curl --request POST \
  --url 'https://api.identity.truora.com/v1/whatsapp/outbounds/send' \
  --header 'Truora-API-Key: {api_key}'
Request body
application/x-www-form-urlencoded
account_id string

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.

country_code string

[Required] Country code for the user phone number. Example: +57

flow_id string

[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

outbound_id string

[Required] ID of an approved Outbound Message. Example: OTB123

phone_number string

[Required] Phone number without the country code of the user that will receive the message. Example: 0001234567

user_authorized boolean

[Required] Must be true for starting the conversation.

User has authorized to be contacted through WhatsApp.

var.<variable_name> string

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

Response
post

Update agent status

This endpoint allows the update of an agent’s status. The options are either online or offline.
Request example
curl --request POST \
  --url 'https://api.identity.truora.com/v1/engagement/agent/status' \
  --header 'Truora-API-Key: {api_key}' \
  --header 'Content-Type: application/json' \
  --data '{"status":"online","username":"string"}'
Request body
application/json
username string required

Determines the user whose status will be updated.

status enum required
Allowed: online offline

The new status the user will have.

Response
post

Create Outbound Messages

Creates an Outbound Message that allows sending messages to users as a first interaction. Each outbound message has two dynamic evaluations assigned by Meta: a status and a quality rating. Both are subject to change over time based on review processes and user feedback.

Status values:

  • PENDING: The outbound is under review by Meta and cannot be sent yet.
  • APPROVED: The outbound has been approved and is eligible to be sent.
  • REJECTED: The outbound was rejected by Meta and cannot be used.
  • FLAGGED: The outbound has received a low quality rating. This is a warning state. If the quality improves to HIGH or MEDIUM for 7 consecutive days, the status will revert to APPROVED.
  • DISABLED: The outbound maintained a low quality rating for over 7 days and was disabled. It cannot be edited or used to send messages.
  • PAUSED: The outbound has been temporarily paused and cannot be sent.

Quality rating values:

  • HIGH: High read rate with no negative feedback (e.g., spam reports or blocks).
  • MEDIUM: Some negative signals such as low engagement, spam reports, or occasional blocks.
  • LOW: Frequent user reports, blocks, or very low engagement; the template may be paused.
  • PENDING: Default value when the template is created. There is not enough data yet to evaluate quality.
Request example
curl --request POST \
  --url 'https://api.identity.truora.com/v1/whatsapp/outbounds' \
  --header 'Truora-API-Key: {api_key}' \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data '{"category":"MARKETING","is_notification":true,"language_code":"en","outbound_name":"string","template_type":"TEXT","waba_phone_number":"string"}'
Request body
application/x-www-form-urlencoded
template_type enum required
Allowed: TEXT IMAGE VIDEO DOCUMENT

Defines the type of content included in the outbound message. Use TEXT when the message does not contain any media elements (image, video, or document).

Supported media types:

  • IMAGE: image/jpeg, image/png (max 5 MB)
  • VIDEO: video/mp4, video/3gpp (max 16 MB)
  • DOCUMENT: Any valid MIME type (max 100 MB)

If category is AUTHENTICATION, only the TEXT template type is allowed.

language_code enum required
Allowed: en en_GB en_US es es_AR es_MX es_ES pt_BR pt_PT

Language code for the outbound message content.

is_notification boolean required

Indicates whether the outbound message is a notification (true) or initiates a flow (false).

If set to true, the outbound is considered a notification and cannot be associated with a flow upon sending. Additionally, notification-type outbounds cannot include QUICK_REPLY buttons.

waba_phone_number string required

WABA Line (WhatsApp Business Account Phone Number) used to send the outbound message.

The WABA Line must be previously activated in Truora.

outbound_name string required

Identifier name for the outbound message.

Maximum 512 characters.

category enum required
Allowed: MARKETING AUTHENTICATION UTILITY

Message category. Refer to the Meta Template Categorization to determine the appropriate category when creating outbound messages.

footer_text string

Applicable only if category is MARKETING or UTILITY.

Optional plain text footer displayed immediately after the body component.

Maximum 60 characters.

code_expiration_minutes integer

Applicable only if category is AUTHENTICATION.

Set this as an integer to include a footer in the message indicating how many minutes remain before the authentication code expires. If omitted, no expiration footer will be shown.

The footer text is predefined based on the selected language_code. Examples:

  • Spanish (es): Este código caduca en <code_expiration_minutes> minutos.
  • English (en): This code expires in <code_expiration_minutes> minutes.
  • Portuguese (pt_BR): Este código expira em <code_expiration_minutes> minutos.

Valid values range from 1 to 90 minutes.

content string

Applicable only if category is MARKETING or UTILITY.

Main message body in plain text. You may include multiple variables; use double curly braces: {{.variable_name}}.

  • Example without variables: Shop our Holiday sale now!

  • Example with variables: Shop now through {{.website_url}} and use code {{.promo_code}} to get {{.discount_percentage}} off all merchandise.

Maximum 1024 characters.

If category is AUTHENTICATION, the message content is predefined based on the selected language and cannot be customized. A single variable ({{.code}}) is always used for the code value, and it must be provided each time the message is sent. Examples:

  • Spanish (es): Tu código de verificación es {{.code}}. Por tu seguridad, no lo compartas.
  • English (en): {{.code}} is your verification code. For your security, do not share this code.
  • Portuguese (pt_BR): Seu código de verificação é {{.code}}. Para sua segurança, não o compartilhe.

outbound_buttons array

Optional interactive buttons that perform actions when tapped. Outbound messages can include up to 10 buttons in total.

This field is not available for outbounds with category set to AUTHENTICATION, since in that case a predefined COPY_CODE button is automatically included.

Each button in the array is an object with the following properties:

  • type (string): Type of button. Must be one of:

    • QUICK_REPLY: Text-only buttons that send a predefined message when tapped. Up to 10 allowed. Must be grouped separately from non-quick reply buttons.
    • URL: Opens a website when tapped. Up to 2 allowed.
    • PHONE_NUMBER: Initiates a call to the specified number. Only 1 allowed.
    • COPY_CODE: Copies a string to the clipboard. Only 1 allowed. Only supported if category is equal to MARKETING. A single variable ({{.code}}) is always used for the value to be copied, and it must be provided each time the message is sent. Maximum 15 characters.

  • text (string): Label of the button. Maximum 25 characters. For COPY_CODE buttons, this must be an empty string ("") because the label is automatically set based on the language_code.

  • url (string): Required if type is URL. Website URL. Max 2000 characters. Supports 1 variable at the end; use double curly braces: {{.variable_name}}. The URL must include a valid host and use either the http or https scheme. For example, https://www.example.com/{{.url_path}} is valid, but ftp://... or a URL without a hostname is not.

  • phone_number (string): Required if type is PHONE_NUMBER. Business phone number to call. Max 20 characters.

The order of the buttons is determined by their position in the array — the first element (index 0) will be displayed as the first button, the second (index 1) as the second, and so on.

Button usage rules by outbound type:

  • Notification outbounds (is_notification = true) cannot include QUICK_REPLY buttons.
  • Flow-trigger outbounds (is_notification = false) can include any combination of button types.

Valid groupings:

  • QUICK_REPLY, QUICK_REPLY
  • QUICK_REPLY, QUICK_REPLY, URL, PHONE_NUMBER
  • URL, PHONE_NUMBER, QUICK_REPLY, QUICK_REPLY

Invalid groupings:

  • QUICK_REPLY, URL, QUICK_REPLY
  • URL, QUICK_REPLY, URL

Outbound messages containing 4 or more buttons, or a combination of a quick reply button and one or more buttons of another type, are not visible on WhatsApp desktop clients. Users receiving such messages will be prompted to view them on a mobile device.

media_id string

Required if template_type is a media type (IMAGE, VIDEO, DOCUMENT).

This is the ID of the file previously uploaded to the Media service, which will be used as the media content in the message.

var.<variable_name> string

Object that defines the example values for each variable used in the outbound message. These variables are referenced in the content, header_text, URL buttons, or the code placeholder in AUTHENTICATION messages.

This object is only used as a sample for validating and previewing the outbound message during creation. It does not affect the actual content sent to end users.

Each key in this object must match the variable name used in the message template (without the {{. }} notation), and the value should be an object with a single field:

  • value (string): Example value assigned to the variable.

Example:

If your message contains:

"header_text": "Our new sale starts {{.sale_start_date}}!",
"content": "Shop now through {{.website_url}} and use code {{.promo_code}} to get {{.discount_percentage}} off all merchandise."

Then the var object should look like:

"var": {
  "sale_start_date": { "value": "today" },
  "website_url": { "value": "truora.com" },
  "promo_code": { "value": "summerTruora2025" },
  "discount_percentage": { "value": "25%" }
}

header_text string

Applicable only if category is MARKETING or UTILITY and template_type is TEXT.

Optional text header that appears at the top of the outbound message. You can include up to one variable; use double curly braces: {{.variable_name}}.

  • Example without variable: Our Holiday sale starts December 1st!

  • Example with variable: Our new sale starts {{.sale_start_date}}!

Maximum 60 characters.

Response
post

Create Agent Template

This endpoint allows the creation of new agent message templates. Users can specify the name, type and content of the message template. The endpoint ensures that each message template name is unique for the account. If an attempt is made to create a message template with a name that already exists, or if the client’s message template limit is reached, appropriate error messages are returned.
Request example
curl --request POST \
  --url 'https://api.identity.truora.com/v1/engagement/agent/templates' \
  --header 'Truora-API-Key: {api_key}' \
  --header 'Content-Type: application/json' \
  --data '{"template_name":"string","template_type":"text"}'
Request body
application/json
template_type enum required
Allowed: text

Type of the template, which defines the content of the template.

template_name string required

Name of the template.

Response
post

Request a new chat export

This endpoint allows creating a new chat export request. After succeeding, the corresponding export process will start executing asynchronously. An email will be sent to the requester once it finishes.
Request example
curl --request POST \
  --url 'https://api.identity.truora.com/v1/engagement/chat/export' \
  --header 'Truora-API-Key: {api_key}' \
  --header 'Content-Type: application/json' \
  --data '{"export_format":"tsv","export_type":"all_chats","language":"en","time_range_end_date":"string","time_range_start_date":"string"}'
Request body
application/json
language enum required
Allowed: en pt es

Language used in the formatting of the export output files.

export_type enum required
Allowed: all_chats single_chat

Type of the export. Defines the scope of the chats included in it.

export_format enum required
Allowed: tsv

Format of the file or files the export request generates as output.

time_range_start_date string required

Date defining the start of the time range that should be used for the export. Currently only year and month are taken into account.

time_range_end_date string required

Date defining the end of the time range that should be used for the export. Currently only year and month are taken into account.

exported_chat_id string

ID of the chat that will be exported. Only required if export_type is “single_chat”.

name string

Optional name for the export request.

Response
post

Force chat assignment dequeue

This endpoint gives users the option of overriding an enqueued chat assignment request and assign the chat immediately
Request example
curl --request POST \
  --url 'https://api.identity.truora.com/v1/engagement/chat/{chat_id}/force-dequeue' \
  --header 'Truora-API-Key: {api_key}' \
  --header 'Content-Type: application/json' \
  --data '{"assignment_type":"specific_agent"}'
Request body
application/json
assignment_type enum required
Allowed: specific_agent

The strategy used to override the assignment request.

target string

The assignment target. Only required for certain assignment types. For specific agent assignments, it must be the agent’s email.

Response
post

Send a message to a chat

The send endpoint is designed to send a message to a chat specified by the chat id, the message is sent via the channel associated with the chat.
Request example
curl --request POST \
  --url 'https://api.identity.truora.com/v1/engagement/chat/{chat_id}/send' \
  --header 'Truora-API-Key: {api_key}'
Response
Path Parameters
chat_id string required

ID of the chat to send the message in.

put

Update Outbound Message

Updates an Outbound Message that allows to send messages to users as a first interaction. Outbound messages need to be approved before they can be used.
Request example
curl --request PUT \
  --url 'https://api.identity.truora.com/v1/whatsapp/outbounds/{outbound_id}' \
  --header 'Truora-API-Key: {api_key}'
Response
put

Update Agent Template

This endpoint allows the update of an agent message template. Agent can specify the new content text of the message template. The endpoint checks if the new content text is valid; if not, it returns an appropriate error message.
Request example
curl --request PUT \
  --url 'https://api.identity.truora.com/v1/engagement/agent/templates/{template_name}' \
  --header 'Truora-API-Key: {api_key}' \
  --header 'Content-Type: application/json' \
  --data '{"template_type":"text"}'
Request body
application/json
template_type enum required
Allowed: text

Type of the template, which defines the content of the template.

Response
put

Update chat owner/status

This endpoint is in charge of updating a specific chat’s owner and/or status. If the chat does not exist, an error message is returned.
Request example
curl --request PUT \
  --url 'https://api.identity.truora.com/v1/engagement/chat/agent/{chat_id}' \
  --header 'Truora-API-Key: {api_key}'
Request body
application/json
owner string

The email of the agent that will become the chat’s owner.

status enum
Allowed: open closed

The new status of the chat.

Response
Path Parameters
chat_id string required

ID of the chat to be updated.

put

Update chat tags

This endpoint allows the user to update the tags of a specific chat. If the tags are not valid, the endpoint returns an appropriate error response.
Request example
curl --request PUT \
  --url 'https://api.identity.truora.com/v1/engagement/chat/{chat_id}/tags' \
  --header 'Truora-API-Key: {api_key}' \
  --header 'Content-Type: application/json' \
  --data '{"name":"string"}'
Request body
application/json
name string required

Name of the tag.

color_hex string

Hex code of the tag’s color.

Response
Path Parameters
chat_id string required

ID of the chat to be updated.

get

Download Process PDF

Retrieves the PDF document for a specified process by its ID.

If the PDF has not been requested before, it is generated first, progressing through:

  • 202 Accepted → "file_status": "requested"
  • 202 Accepted → "file_status": "in_progress"
  • 302 Found * → Redirects to the PDF file when ready
  • 200 OK → Returns the file

If the PDF has already been generated, the response immediately returns:

  • 302 Found * → Redirects to the PDF file when ready
  • 200 OK → Returns the file

Polling: If the file is not ready (202 Accepted), retry until 302 Found or 200 OK.

* 302 Redirect Handling: Most API clients and browsers follow redirects automatically. However, if your API client does not, extract the Location header containing the PDF’s URL and make a GET request to download the file.

Request example
curl --request GET \
  --url 'https://api.identity.truora.com/v1/processes/{process_id}/pdf' \
  --header 'Truora-API-Key: {api_key}'
Response
Path Parameters
process_id string required

The ID of the completed process for which the PDF is requested.

get

Search Chats

This endpoint retrieves information for multiple chats, with optional filters to refine the search. It provides a high-level overview of chat metadata and attributes, excluding actual messages.
Request example
curl --request GET \
  --url 'https://api.identity.truora.com/v1/engagement/chat/search' \
  --header 'Truora-API-Key: {api_key}'
Response
Query Parameters
contact_query string optional

Filter used to search chats based on either their corresponding contact’s name or phone number.

enqueued_only string optional

If set to “true”, only chats whose assignments are currently enqueued will be returned.

from_last_activity_date string optional

Filter to limit results based on chats’ last activity dates. Must be provided alongside “to_last_activity_date” param to work.

last_activity_actor_type string optional

If provided, only chats whose latest activity corresponds to the given actor type are returned.

last_activity_type string optional

If provided, only chats whose latest activity is of the given type are returned.

owner string optional

If provided, only chats with the specified owner will be returned.

start_key string optional

Used for pagination purposes. Responses will include this value in case there are further result pages.

status enum optional

Allowed: open | closed | UNASSIGNED

tag string optional

If provided, only chats that have any of the specified tags will be returned.

to_last_activity_date string optional

Filter to limit results based on chats’ last activity dates. Must be provided alongside “from_last_activity_date” param to work.

get

Get Chat

By specifying the unique chat ID, this particular endpoint is designed to retrieve comprehensive chat information, excluding the actual messages within the chat, offering a high-level overview of the chat’s metadata and attributes
Request example
curl --request GET \
  --url 'https://api.identity.truora.com/v1/engagement/chat/{chat_id}' \
  --header 'Truora-API-Key: {api_key}'
Response
Path Parameters
chat_id string required

ID of the chat to get.

get

Get Channels

The endpoint to get the channels available to enable the user to contact their users
Request example
curl --request GET \
  --url 'https://api.identity.truora.com/v1/engagement/channels' \
  --header 'Truora-API-Key: {api_key}'
Response
Query Parameters
start_key string optional

Used for pagination purposes. Responses will include this value in case there are further result pages.

get

Get ICE servers

Returns short-lived WebRTC ICE server credentials (STUN/TURN) for establishing peer connections during voice and video calls.
Request example
curl --request GET \
  --url 'https://api.identity.truora.com/v1/engagement/calling/ice-servers' \
  --header 'Truora-API-Key: {api_key}'
Response
get

List chat exports

Returns a paginated list of chat export requests for the authenticated client. Supports filtering by request actor, export type, export format, language, date range, and chat ID.
Request example
curl --request GET \
  --url 'https://api.identity.truora.com/v1/engagement/chat/export' \
  --header 'Truora-API-Key: {api_key}'
Response
Query Parameters
chat_id string optional

Filter by the exported chat ID. Only applicable for single_chat exports.

end_date string optional

Filter exports by time range end date. Must be in RFC3339 format.

export_format string optional

Filter by export format. Allowed values: tsv.

export_name string optional

Filter by export name. Only exports whose names contain this value will be returned (case-insensitive).

export_type string optional

Filter by export type. Allowed values: all_chats, single_chat.

language string optional

Filter by the language used in the export output. Allowed values: en, es, pt.

limit string optional

Maximum number of results to return per page.

request_actor string optional

If provided, only exports requested by the specified actor will be returned.

start_date string optional

Filter exports by time range start date. Must be in RFC3339 format.

start_key string optional

Pagination cursor. Use the value from the previous response’s next URL to fetch the next page.

get

Get groups counters

This endpoint allows the retrieval of group counters such as total open conversations and total online agents on a group by group basis.
Request example
curl --request GET \
  --url 'https://api.identity.truora.com/v1/engagement/agent/groups/counters' \
  --header 'Truora-API-Key: {api_key}'
Response
get

Search Chat Activities

This endpoint retrieves a chat’s activity history. Optional filters can be applied to refine the search. It provides a comprehensive overview of all activities within a given chat.
Request example
curl --request GET \
  --url 'https://api.identity.truora.com/v1/engagement/chat/{chat_id}/activities' \
  --header 'Truora-API-Key: {api_key}'
Response
Path Parameters
chat_id string required

ID of the chat the activities belong to.

Query Parameters
actor_type string optional

If provided, only activities whose actor is of the specified type will be returned.

start_key string optional

Used for pagination purposes. Responses will include this value in case there are further result pages.

type string optional

If provided, only activities with the specified type will be returned.

get

Get Assignment Ruleset

This endpoint allows the retrieval of an assignment ruleset by its ID. If the ID is not valid or the ruleset is not found, an appropriate error will be returned.
Request example
curl --request GET \
  --url 'https://api.identity.truora.com/v1/engagement/agent/assignment-rulesets/{ruleset_id}' \
  --header 'Truora-API-Key: {api_key}'
Response
Path Parameters
ruleset_id string required

ID of the ruleset to get

get

Download Process Video Call Recordings

Retrieves the video call recordings for a specified process by its ID.

If the video call recordings have not been requested before, it is generated first, progressing through:

  • 202 Accepted → "file_status": "requested"
  • 202 Accepted → "file_status": "in_progress"
  • 302 Found * → Redirects to the video call recordings file when ready
  • 200 OK → Returns the file

If the video call recordings have already been generated, the response immediately returns:

  • 302 Found * → Redirects to the video call recordings file when ready
  • 200 OK → Returns the file

Polling: If the file is not ready (202 Accepted), retry until 302 Found or 200 OK.

* 302 Redirect Handling: Most API clients and browsers follow redirects automatically. However, if your API client does not, extract the Location header containing the video call recordings’s URL and make a GET request to download the file.

Request example
curl --request GET \
  --url 'https://api.identity.truora.com/v1/processes/{process_id}/video-call-recordings' \
  --header 'Truora-API-Key: {api_key}'
Response
Path Parameters
process_id string required

The ID of the completed process for which the video call recordings is requested.

get

List Outbound Messages

This endpoint retrieves a list of outbound messages that have been created. Users can access this endpoint to view and review the outbound messages they have generated or sent, providing an overview of the created outbound messages within the system or application.
Request example
curl --request GET \
  --url 'https://api.identity.truora.com/v1/whatsapp/outbounds?line={line}' \
  --header 'Truora-API-Key: {api_key}'
Response
Query Parameters
add_pagination boolean optional

If ’true’, the response includes pagination (outbounds, self, next). If ‘false’ or not sent, the response is just the array of outbounds, and if there are no results, it may return 404.

flow_id string optional

Default flow ID to filter outbounds associated with that flow. Example: IPF123456

interaction_category enum optional

Allowed: MARKETING | UTILITY | AUTHENTICATION

line string required

WhatsApp business account line (WABA). Do not forget that you must add the country code followed by the number. Example: 1432567893

query string optional

Search text for the outbounds, or outbound ID when the value starts with the OTB prefix. If it starts with OTB, only that outbound is returned (search by ID). Example: OTB123456

start_key string optional

Cursor for pagination. Use the value returned in the next link of the previous response to fetch the next page. Omit for the first page.

status enum optional

Allowed: APPROVED | PENDING | REJECTED | PAUSED | PENDING_DELETION | DISABLED | FLAGGED

get

Get Agent Templates

This endpoint allows getting the agent message templates of the account. An item limit, message template name prefix and start key can be defined as query params. If any of the query params is invalid, an error message is returned.
Request example
curl --request GET \
  --url 'https://api.identity.truora.com/v1/engagement/agent/templates' \
  --header 'Truora-API-Key: {api_key}'
Response
Query Parameters
limit string optional

The maximum number of items that should be returned in the response.

prefix_name string optional

If specified, only templates whose name starts with this term will be returned.

start_key string optional

Used for pagination purposes. Responses will include this value in case there are next result pages.

get

Get agents status

This endpoint allows the retrieval of agents online status along with information and open chat counters.
Request example
curl --request GET \
  --url 'https://api.identity.truora.com/v1/engagement/agent/status' \
  --header 'Truora-API-Key: {api_key}'
Response
Query Parameters
group string optional

If specified, only users belonging to any of the specified groups will be returned.

start_key string optional

Used for pagination purposes. Responses will include this value in case there are further result pages.

status string optional

If specified, only users with this status will be returned. Allowed values: “online”, “offline”

username string optional

If specified, only usernames containing this value will be returned.

get

Get Outbound Message

This endpoint retrieves an outbound message. Users can use this endpoint to obtain details or content related to a specific outbound message.
Request example
curl --request GET \
  --url 'https://api.identity.truora.com/v1/whatsapp/outbounds/{outbound_id}' \
  --header 'Truora-API-Key: {api_key}'
Response
Path Parameters
outbound_id string required

outbound ID

delete

Remove Outbound Message

This endpoint allows users to delete an outbound message. Users can initiate the removal process for a specific outbound message, effectively eliminating it from the system or application. It provides a means to manage and clean up outbound messages when they are no longer needed or relevant.
Request example
curl --request DELETE \
  --url 'https://api.identity.truora.com/v1/whatsapp/outbounds/{outbound_id}' \
  --header 'Truora-API-Key: {api_key}'
Response
delete

Delete Agent Template

This endpoint allows the deletion of an agent message template. The endpoint checks if the template exists; if not, it returns an appropriate error message.
Request example
curl --request DELETE \
  --url 'https://api.identity.truora.com/v1/engagement/agent/templates/{template_name}' \
  --header 'Truora-API-Key: {api_key}'
Response
Path Parameters
template_name string required

Name of the template to delete

Catalogs

Manage your catalogs and products in a single place.

post

Create Catalog

This endpoint allows the creation of new catalog. Users must specify the name and provider type. In the case of a Meta catalog, the user must also specify the vertical. The catalog will be created but it will not be published until the user publishes it.
Request example
curl --request POST \
  --url 'https://api.identity.truora.com/v1/engagement/catalogs' \
  --header 'Truora-API-Key: {api_key}' \
  --header 'Content-Type: application/json' \
  --data '{"catalog_name":"string","provider_type":"META"}'
Request body
application/json
provider_type enum required
Allowed: META

Type of the provider. For example, ‘META’.

catalog_name string required

Name of the catalog.

vertical enum
Allowed: commerce

Vertical of the catalog. For example, ‘commerce’.

Response
post

Create products for a catalog

Creates products and returns a 200 status code. It triggers an async Meta sync if the catalog is published, otherwise storing them as UNPUBLISHED.
Request example
curl --request POST \
  --url 'https://api.identity.truora.com/v1/engagement/catalogs/{catalog_id}/products' \
  --header 'Truora-API-Key: {api_key}' \
  --header 'Content-Type: application/json' \
  --data '{"products":"string"}'
Request body
application/json
products array required

Products to create.

Response
put

Update catalog

Updates an existing catalog. If the catalog is published, changes are synced with the provider.
Request example
curl --request PUT \
  --url 'https://api.identity.truora.com/v1/engagement/catalogs/{catalog_id}' \
  --header 'Truora-API-Key: {api_key}'
Response
Path Parameters
catalog_id string required

ID of the catalog to update.

put

Update products for a catalog

Updates the products and returns a 200 status code. If the catalog is published, it synchronizes the uploaded products with Meta.
Request example
curl --request PUT \
  --url 'https://api.identity.truora.com/v1/engagement/catalogs/{catalog_id}/products' \
  --header 'Truora-API-Key: {api_key}' \
  --header 'Content-Type: application/json' \
  --data '{"products":"string"}'
Request body
application/json
products array required

Products to create.

Response
Path Parameters
catalog_id string optional

The unique identifier of the catalog where the products will be updated.

get

Get Catalogs

This endpoint allows the retrieval of all catalogs for a given client with pagination support.
Request example
curl --request GET \
  --url 'https://api.identity.truora.com/v1/engagement/catalogs' \
  --header 'Truora-API-Key: {api_key}'
Response
get

Get catalog

By specifying the unique catalog ID, this particular endpoint is designed to retrieve comprehensive catalog information, offering a high-level overview of the catalog’s metadata and attributes
Request example
curl --request GET \
  --url 'https://api.identity.truora.com/v1/engagement/catalogs/{catalog_id}' \
  --header 'Truora-API-Key: {api_key}'
Response
Path Parameters
catalog_id string required

ID of the catalog to get.

get

List products for a catalog

Returns products for a catalog with optional filters and cursor pagination (self and next URLs).
Request example
curl --request GET \
  --url 'https://api.identity.truora.com/v1/engagement/catalogs/{catalog_id}/products' \
  --header 'Truora-API-Key: {api_key}'
Response
Path Parameters
catalog_id string optional

The unique identifier of the catalog whose products are listed.

Query Parameters
availability string optional

Filter by availability.

brand string optional

Filter by brand.

condition string optional

Filter by product condition.

limit string optional

Maximum number of products to return per page.

next_token string optional

Opaque token to retrieve the next page of results.

price_range_max string optional

Maximum price (integer, same currency as stored products).

price_range_min string optional

Minimum price (integer, same currency as stored products).

retailer_ids string optional

Comma-separated retailer ids to filter by.

search_query string optional

Filter products by name or retailer id (substring match).

sync_statuses string optional

Comma-separated sync statuses to filter by.

delete

Delete catalog

Deletes a catalog and all its related items. If the catalog is published on Meta, it is also removed there. Returns an error if the catalog does not exist or the request is invalid.
Request example
curl --request DELETE \
  --url 'https://api.identity.truora.com/v1/engagement/catalogs/{catalog_id}' \
  --header 'Truora-API-Key: {api_key}'
Response
Path Parameters
catalog_id string required

ID of the catalog to delete.

patch

Mark products for deletion

Marks the specified products for deletion in the catalog. Accepts a list of retailer IDs in the request body. After marking, the catalog is republished via the publish products service
Request example
curl --request PATCH \
  --url 'https://api.identity.truora.com/v1/engagement/catalogs/{catalog_id}/products/mark-for-deletion' \
  --header 'Truora-API-Key: {api_key}' \
  --header 'Content-Type: application/json' \
  --data '{"retailer_ids":"string"}'
Request body
application/json
retailer_ids array required

List of retailer IDs identifying the catalog products that should be marked for deletion. At least one ID is required.

Response
Path Parameters
catalog_id string required

The unique identifier of the catalog that contains the products you want to mark for deletion. Must be a valid UUID.

post

Publish a catalog

This method publishes a catalog to the external provider (Meta). The catalog must already be linked to the WABA specified in the request body. On success, the catalog is published to the provider and products are synced.
Request example
curl --request POST \
  --url 'https://api.identity.truora.com/v1/engagement/catalogs/{catalog_id}/publish' \
  --header 'Truora-API-Key: {api_key}' \
  --header 'Content-Type: application/json' \
  --data '{"waba_id":"string"}'
Request body
application/json
waba_id string required

The ID of the WABA used to retrieve the WABA info.

Response
Path Parameters
catalog_id string required

ID of the catalog to publish.

WA Contacts

Add, search and manage your customers (end users) in a single place.

post

Create contact property

This endpoint is used to create a new contact property with data like its name and type. NOTE: A maximum of 25 visible (non-hidden) properties can exist simultaneously.
Request example
curl --request POST \
  --url 'https://api.identity.truora.com/v1/contact-properties' \
  --header 'Truora-API-Key: {api_key}' \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data '{"name":"string","type":"string"}'
Request body
application/x-www-form-urlencoded
type enum required
Allowed: string int boolean date email enum

Indicates the type of the custom property.

name string required

Indicates the name of the custom property.

config_values.allowed_values enum
Allowed: value1 value2 value3

Required only if type is enum. Add the list of personalized values separated by comma, example: value1, value2, value3.

is_hidden boolean

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.

Response
post

Create contact

This endpoint is used to create a new contact with data such as its phone number, external_id, name, optional email, and values for custom contact properties. At least one of phone_number or external_id must be provided.
Request example
curl --request POST \
  --url 'https://api.identity.truora.com/v1/contacts' \
  --header 'Truora-API-Key: {api_key}' \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data '{"external_id":"string","name":"string","phone_number":"string"}'
Request body
application/x-www-form-urlencoded
phone_number string required

Indicates the Phone number of the contact that you want to register. Must include the country code (e.g., +570000000000). Required if external_id is not provided.

name string required

Indicates the name of the contact that you want to register.

external_id string required

Indicates the external identifier defined by you for the contact (e.g., usr_12345). Required if phone_number is not provided.

custom_property_values.{{property_id}} string

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

email string

Indicates the email address you want to register (e.g., email@yourdomain.com).

Response
put

Update contact

This endpoint is used to update a specific contact with the ID provided as a path parameter. The contact’s name, email and custom property values can be changed. An optional “emit_sysevent” body parameter can be passed so that the update triggers a sysevent.
Request example
curl --request PUT \
  --url 'https://api.identity.truora.com/v1/contacts/{contact_id}' \
  --header 'Truora-API-Key: {api_key}'
Request body
application/x-www-form-urlencoded
name string

Indicates the name of the contact that you want to update.

custom_property_values.{{property_id}} string

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

email string

Indicates the email address you want to update (e.g., email@yourdomain.com).

Response
Path Parameters
contact_id string required

The identifier of the contact to update. By default, the value is interpreted as a contact_id. To use a different identifier, provide the key_type query parameter (e.g., phone_number or external_id).

Query Parameters
key_type string optional

Specifies which identifier is used to update the contact. Defaults to contact_id if not provided. Supported values: contact_id, phone_number, external_id.

get

Get contact properties

This endpoint is used to list pages of contact properties created in our platform. An optional “start_key” query parameter can be passed to continue pagination.
Request example
curl --request GET \
  --url 'https://api.identity.truora.com/v1/contact-properties' \
  --header 'Truora-API-Key: {api_key}'
Response
get

Get all contacts

This endpoint is used to list pages of contacts created in our platform. An optional “start_key” query parameter can be passed to continue pagination.
Request example
curl --request GET \
  --url 'https://api.identity.truora.com/v1/contacts' \
  --header 'Truora-API-Key: {api_key}'
Response
get

Get contact

This endpoint is used to get the data related to a specific contact using the identifier provided as a path parameter.
Request example
curl --request GET \
  --url 'https://api.identity.truora.com/v1/contacts/{contact_id}' \
  --header 'Truora-API-Key: {api_key}'
Response
Path Parameters
contact_id string required

The identifier used to retrieve the contact. By default, it is treated as a contact_id. To use a different identifier, provide the key_type query parameter (e.g., phone_number or external_id).

Query Parameters
key_type string optional

Specifies which identifier is used to retrieve the contact. Defaults to contact_id if not provided. Supported values: contact_id, phone_number, external_id.

delete

Delete contact

This endpoint is used to delete a specific contact with the ID provided as a path parameter.
Request example
curl --request DELETE \
  --url 'https://api.identity.truora.com/v1/contacts/{contact_id}' \
  --header 'Truora-API-Key: {api_key}'
Response
Path Parameters
contact_id string required

The unique identifier of the contact to delete.

DI Processes

Configure and order the validations you want to do in your process. Try and start validating your users by sending a link.

post

Identity Back

Allows stepping back in the identity verification process or retrying the last step.

  • If retry_step is true, the last step is re-executed with the same expected inputs.
  • If retry_step is false or not provided, the process moves one step back.
Request example
curl --request POST \
  --url 'https://api.identity.truora.com/v1/processes/{process_id}/back' \
  --header 'Truora-API-Key: {api_key}'
Request body
application/x-www-form-urlencoded
retry_step boolean

Indicates whether to retry the previous step with the same expected inputs. If set to true, it decreases current_step by 1 and invokes the verify process.

Response
Path Parameters
process_id string required

The ID of the ongoing process.

post

Feed wallet

Exchanges a wallet OAuth code for an access token and pushes the process’s document/face validations to /v1/oauth2/validations on the wallet.
Request example
curl --request POST \
  --url 'https://api.identity.truora.com/v1/processes/feed-wallet' \
  --header 'Truora-API-Key: {api_key}' \
  --header 'Content-Type: application/json' \
  --data '{"code":"string"}'
Request body
application/json
code string required

[Required] Wallet OAuth2 authorization code returned by the wallet sign-up iframe via web_message. The lambda exchanges it for an access token at the wallet’s /oauth2/token endpoint.

Response
post

Create log

[Internal use] Allows to create logs from front end to send to kibana to keep track of usage
Request example
curl --request POST \
  --url 'https://api.identity.truora.com/v1/processes/enqueue-log' \
  --header 'Truora-API-Key: {api_key}'
Response
post

Verify Identity

The Verify Identity endpoint processes each step in an identity verification process. It receives step input data, validates it, and updates the process to the next step. The step input must be provided in the request body according to the specific requirements of each step.

To retrieve steps required values and track the process progression use the Read Identity endpoint.

Refer to the Verify Identity Steps guide for a practical example of using the Verify Identity endpoint along with other DI Processes endpoints.

If you need help with a specific integration scenario, please contact our Support Team.

Request example
curl --request POST \
  --url 'https://api.identity.truora.com/v1/processes/{process_id}' \
  --header 'Truora-API-Key: {api_key}' \
  --header 'Content-Type: application/json' \
  --data '{"expected_inputs":"string","step_id":"string","type":"string","verification_id":"string"}'
Request body
application/json
verification_id string required

The identifier for the verification that the step belongs to.

type string required

The type of step being verified.

step_id string required

The identifier for the step being verified.

expected_inputs array required

An array containing the required inputs for the specified step type. Some steps may not require inputs—omit this parameter in such cases.

Response
Path Parameters
process_id string required

The ID of the process being verified.

post

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.

Request example
curl --request POST \
  --url 'https://api.identity.truora.com/v1/processes' \
  --header 'Truora-API-Key: {api_key}'
Response
post

Add Verification

Appends a verification and its first step to an existing dynamic identity process. Only one verification may be active at a time — the request is rejected if another verification is still pending or a step is in flight.
Request example
curl --request POST \
  --url 'https://api.identity.truora.com/v1/processes/{process_id}/verifications' \
  --header 'Truora-API-Key: {api_key}'
Response
Path Parameters
process_id string required

The ID of the dynamic process to append the verification to.

put

Update Identity

This API endpoint updates an existing process identified by process_id, modifying changeable process information such as phone number and device details until the process is complete.
Request example
curl --request PUT \
  --url 'https://api.identity.truora.com/v1/processes/{process_id}' \
  --header 'Truora-API-Key: {api_key}'
Request body
application/x-www-form-urlencoded
phone_number string

Phone number with country code.

device_info string

Device information in serialized JSON format.

Response
get

Read Variables

Retrieves all the variables associated with the specified identity process, including their names and current values.
Request example
curl --request GET \
  --url 'https://api.identity.truora.com/v1/processes/{process_id}/variables' \
  --header 'Truora-API-Key: {api_key}'
Response
Path Parameters
process_id string required

The ID of the process from which to retrieve the variables.

get

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.

Note: Responses for users with the permission identity.process.read.own are limited to their own processes (those they initiated and those linked to them via configured “own” scope variables).
Request example
curl --request GET \
  --url 'https://api.identity.truora.com/v1/processes' \
  --header 'Truora-API-Key: {api_key}'
Response
Query Parameters
declined_reason string optional

Filters processes by a Declined Reason. Multiple declined_reason parameters can be used to filter results by more than one reason.

end_date string optional

Specifies the end of the date range for filtering processes. Must be in the ISO 8601 format (YYYY-MM-DDTHH:MM:SS±hh:mm). When used, the range between start_date and end_date cannot exceed 2 months. Both start_date and end_date are required for date range filtering.

failure_status string optional

Filters processes by their failure status, such as expired or pending.

search string optional

Filters results by matching the provided value against specific fields. For process_id and flow_id, an exact match is required. For other fields, such as account_id, document_number, cell_phone, first_name, and last_name, partial matches are supported. Provide only the value to search for; specifying the field name will not work.

start_date string optional

Specifies the start of the date range for filtering processes. Must be in the ISO 8601 format (YYYY-MM-DDTHH:MM:SS±hh:mm). When used, the range between start_date and end_date cannot exceed 2 months. Both start_date and end_date are required for date range filtering.

start_key string optional

Specifies the starting key value for pagination. Use this parameter after the first query if more results are available for pagination.

status string optional

Filters processes by their status: pending, failure, or success.

get

Download Process PDF

Retrieves the PDF document for a specified process by its ID.

If the PDF has not been requested before, it is generated first, progressing through:

  • 202 Accepted → "file_status": "requested"
  • 202 Accepted → "file_status": "in_progress"
  • 302 Found * → Redirects to the PDF file when ready
  • 200 OK → Returns the file

If the PDF has already been generated, the response immediately returns:

  • 302 Found * → Redirects to the PDF file when ready
  • 200 OK → Returns the file

Polling: If the file is not ready (202 Accepted), retry until 302 Found or 200 OK.

* 302 Redirect Handling: Most API clients and browsers follow redirects automatically. However, if your API client does not, extract the Location header containing the PDF’s URL and make a GET request to download the file.

Request example
curl --request GET \
  --url 'https://api.identity.truora.com/v1/processes/{process_id}/pdf' \
  --header 'Truora-API-Key: {api_key}'
Response
Path Parameters
process_id string required

The ID of the completed process for which the PDF is requested.

get

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_status values 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.

Request example
curl --request GET \
  --url 'https://api.identity.truora.com/v1/processes/{process_id}/result' \
  --header 'Truora-API-Key: {api_key}'
Response
Path Parameters
process_id string required

The ID of the process for which results are being retrieved.

get

Download Process Video Call Recordings

Retrieves the video call recordings for a specified process by its ID.

If the video call recordings have not been requested before, it is generated first, progressing through:

  • 202 Accepted → "file_status": "requested"
  • 202 Accepted → "file_status": "in_progress"
  • 302 Found * → Redirects to the video call recordings file when ready
  • 200 OK → Returns the file

If the video call recordings have already been generated, the response immediately returns:

  • 302 Found * → Redirects to the video call recordings file when ready
  • 200 OK → Returns the file

Polling: If the file is not ready (202 Accepted), retry until 302 Found or 200 OK.

* 302 Redirect Handling: Most API clients and browsers follow redirects automatically. However, if your API client does not, extract the Location header containing the video call recordings’s URL and make a GET request to download the file.

Request example
curl --request GET \
  --url 'https://api.identity.truora.com/v1/processes/{process_id}/video-call-recordings' \
  --header 'Truora-API-Key: {api_key}'
Response
Path Parameters
process_id string required

The ID of the completed process for which the video call recordings is requested.

get

Read Identity

Retrieves the current status and detailed results of the specified identity process, including the progress of each step.

Responses for users with the permission identity.process.read.own are limited to their own processes (those they initiated and those linked to them via configured “own” scope variables)
Request example
curl --request GET \
  --url 'https://api.identity.truora.com/v1/processes/{process_id}' \
  --header 'Truora-API-Key: {api_key}'
Response
Path Parameters
process_id string required

The ID of the process to retrieve.

delete

Delete Identity

This API endpoint permanently removes an identity process, typically used for legal requests to delete customer data, granted the necessary permissions. Note: This action is definitive, so there is no way to reverse it.
Request example
curl --request DELETE \
  --url 'https://api.identity.truora.com/v1/processes/{process_id}' \
  --header 'Truora-API-Key: {api_key}'
Response

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.

post

Query user customers

User profile query endpoint allows to obtain detailed statistics on different aspects of user customers
Request example
curl --request POST \
  --url 'https://api.identity.truora.com/v1/customers/query' \
  --header 'Truora-API-Key: {api_key}'
Response
post

Compute profile segment

Trigger the computation of a profile segment. This will queue the segment for processing and convert the JSONLogic rule to SQL.
Request example
curl --request POST \
  --url 'https://api.identity.truora.com/v1/customers/segments/{segment_id}/compute' \
  --header 'Truora-API-Key: {api_key}'
Response
Path Parameters
segment_id string required

The unique identifier of the segment to compute

post

Create profile segment

Create a new profile segment with a name, description and JSONLogic rule to define the segment criteria.
Request example
curl --request POST \
  --url 'https://api.identity.truora.com/v1/customers/segments' \
  --header 'Truora-API-Key: {api_key}' \
  --header 'Content-Type: application/json' \
  --data '{"name":"string","rule":"string"}'
Request body
application/json
rule string required

represents the JSONLogic rule that defines the segment criteria

name string required

represents the name of the segment

description string

represents the description of the segment

Response
put

Update profile segment

Update a profile segment with a name, description and JSONLogic rule to define the segment criteria.
Request example
curl --request PUT \
  --url 'https://api.identity.truora.com/v1/customers/segments/{segment_id}' \
  --header 'Truora-API-Key: {api_key}'
Request body
application/x-www-form-urlencoded
rule string

represents the rule that defines the segment criteria

description string

represents the description of the segment

name string

represents the name of the segment

Response
Path Parameters
segment_id string required

The segment ID is an automatically generated ID and is unique for each segment

put

Update Customer Tags

Update customer tags endpoint allows you to update, add, remove, and manage the tags associated with a customer profile.
Request example
curl --request PUT \
  --url 'https://api.identity.truora.com/v1/customers/{customer_id}/tags' \
  --header 'Truora-API-Key: {api_key}' \
  --header 'Content-Type: application/json' \
  --data '{"action":"add","color":"string","name":"string","source":"profile"}'
Request body
application/json
name string required

Tag name

color string required

Tag color in hex format

action enum required
Allowed: add remove

Action to perform on the tag.

source enum required
Allowed: profile engagement-chat validation check contact form external-system

Source of the tag

source_type string

Type of the source. (Define this field only for the ’external-system’ source; this field must contain the system name. It is important to define it correctly, as it is used for tag traceability.)

engagement_chat_id string

Engagement chat ID (Required only for engagement-chat tags)

Response
Path Parameters
customer_id string required

The customer ID is an automatically generated ID and is unique for each customer

get

List available decision variables

This endpoint returns all available decision variables in the system with their metadata, types, allowed values and example values. Supports filtering by search, ID, name, category, active status, product, type, and level. Multiple values can be provided for ID, name, category, product, type, and level filters. This endpoint supports pagination.
Request example
curl --request GET \
  --url 'https://api.identity.truora.com/v1/customers/decision-variables/available' \
  --header 'Truora-API-Key: {api_key}'
Response
Query Parameters
active boolean optional

Filter decision variables by active status (true or false)

category array optional

Filter decision variables by category. Multiple values can be provided (e.g., profile, profile_reliability)

id array optional

Filter decision variables by ID. Multiple values can be provided

level array optional

Filter decision variables by level. Multiple values can be provided (integer values)

name array optional

Filter decision variables by name. Multiple values can be provided

product array optional

Filter decision variables by product. Multiple values can be provided (e.g., process, check)

search string optional

Search term to filter decision variables by name or description

start_key string optional

Start key value for pagination to continue from a specific point

type array optional

Filter decision variables by data type. Multiple values can be provided (e.g., boolean, string, number, date)

get

Get Customer Waba Lines

Get customer waba lines endpoint allows you to consult the waba lines that have interacted with a customer.
Request example
curl --request GET \
  --url 'https://api.identity.truora.com/v1/customers/{customer_id}/waba-lines' \
  --header 'Truora-API-Key: {api_key}'
Response
Path Parameters
customer_id string required

The customer ID is an automatically generated ID and is unique for each customer

get

List decision variables for user customers

Allows to obtain decision variables for user customers by search, date range, categories and names. This endpoint supports pagination.
Request example
curl --request GET \
  --url 'https://api.identity.truora.com/v1/customers/decision-variables' \
  --header 'Truora-API-Key: {api_key}'
Response
Query Parameters
categories array optional

Filter decision variables by categories. Multiple values can be provided

end_date string optional

End date for filtering decision variables by date range (format: YYYY-MM-DD)

names array optional

Filter decision variables by specific names. Multiple values can be provided

search string optional

Search term to filter decision variables by text content

start_date string optional

Start date for filtering decision variables by date range (format: YYYY-MM-DD)

start_key string optional

Start key value for pagination to continue from a specific point

get

List Customers

This API endpoint allows retrieving the current status and general information of all customers associated with an account.
Request example
curl --request GET \
  --url 'https://api.identity.truora.com/v1/customers' \
  --header 'Truora-API-Key: {api_key}'
Response
Query Parameters
basic_info string optional

When true, returns only basic profile fields (id, name, country, phone, email, document_number, document_type, birthday, document_issue_date, gender) for faster responses.

search string optional

Filter the list of customers by document-id, email, name and phone number

search_field string optional

When used with search and basic_info=true, specifies the exact field to search in. Allowed values: document_id, email, phone_number. Uses direct equality match instead of regex for faster results.

single string optional

When true, expects a single profile match from the search filter.

start_key string optional

Start key value for the pagination.

get

Get Customer Transaction

Get customer transaction endpoint allows you to consult the detailed information of a transaction associated with a customer.
Request example
curl --request GET \
  --url 'https://api.identity.truora.com/v1/customers/{customer_id}/transactions/{transaction_id}' \
  --header 'Truora-API-Key: {api_key}'
Response
Path Parameters
customer_id string required

The customer ID is an automatically generated ID and is unique for each customer

transaction_id string required

The transaction ID is the unique identifier of the transaction.

get

List profile segments

This API endpoint allows retrieving all profile segments associated with the authenticated client. The response includes pagination support through start_key and limit query parameters and can be filtered by segment name with search.
Request example
curl --request GET \
  --url 'https://api.identity.truora.com/v1/customers/segments' \
  --header 'Truora-API-Key: {api_key}'
Response
Query Parameters
limit integer optional

Maximum number of segments to return (default: 20, max: 100)

search string optional

Text used to filter segments by name

start_key string optional

Pagination token to get the next page of results

get

List Customers Transactions

List customer transactions endpoitn allows you to consult the detailed information of the transactions associated with a customer.
Request example
curl --request GET \
  --url 'https://api.identity.truora.com/v1/customers/{customer_id}/transactions' \
  --header 'Truora-API-Key: {api_key}'
Response
Path Parameters
customer_id string required

The customer ID is an automatically generated ID and is unique for each customer

Query Parameters
source string optional

Allowed: check | process | validation | engagement-chat | profile

Product that originated the transaction.

start_key string optional

Start key value for the pagination.

get

Get profile segment

The API endpoint allows retrieving the details of the segment identified by the provided ID.
Request example
curl --request GET \
  --url 'https://api.identity.truora.com/v1/customers/segments/{segment_id}' \
  --header 'Truora-API-Key: {api_key}'
Response
Path Parameters
segment_id string required

The segment ID is an automatically generated ID and is unique for each segment

get

Get Customer Tag History

Get customer tag history endpoint allows you to consult the detailed information of the tag history associated with a customer.
Request example
curl --request GET \
  --url 'https://api.identity.truora.com/v1/customers/{customer_id}/tag-history' \
  --header 'Truora-API-Key: {api_key}'
Response
Path Parameters
customer_id string required

The customer ID is an automatically generated ID and is unique for each customer

get

Get Customer

This API endpoint allows retrieving the details of the customer identified by the provided ID.
Request example
curl --request GET \
  --url 'https://api.identity.truora.com/v1/customers/{customer_id}' \
  --header 'Truora-API-Key: {api_key}'
Response
Path Parameters
customer_id string required

The customer ID is an automatically generated ID and is unique for each customer

get

List segment profiles

Returns the profiles that belong to the requested segment and supports cursor-based pagination through the start_key query parameter.
Request example
curl --request GET \
  --url 'https://api.identity.truora.com/v1/customers/segments/{segment_id}/profiles' \
  --header 'Truora-API-Key: {api_key}'
Response
Path Parameters
segment_id string required

The unique identifier of the segment

Query Parameters
start_key string optional

Pagination cursor for the next or previous page of profiles

delete

Delete profile segment

This API endpoint allows you to delete a profile segment. It removes the segment from the system, including all associated rules and configurations. The response includes a success message indicating that the segment has been deleted.
Request example
curl --request DELETE \
  --url 'https://api.identity.truora.com/v1/customers/segments/{segment_id}' \
  --header 'Truora-API-Key: {api_key}'
Response
Path Parameters
segment_id string required

The segment ID is an automatically generated ID and is unique for each segment

Truora Pass

Truora Pass lets your users verify their identity once and reuse it to sign in across apps. It is a standard OAuth 2.0 / OpenID Connect provider: your application redirects the user to Truora Pass to authenticate and consent, exchanges the resulting authorization code for tokens, and reads the user’s verified identity claims from the UserInfo endpoint.

Start with the Getting started guide, register your application following Registering your application, and see the Scopes reference for scope details. Detailed flow guides: Authorization Code flow, Embedded SDK, CIBA flow, Refresh tokens, UserInfo and claims, Verification results and Errors and troubleshooting.

The authorization page (GET /authorize) is served from https://pass.truora.com; every JSON/form API below is served from the base URL https://api.pass.truora.com. Truora Pass does not publish an OIDC discovery document, JWKS, or a token revocation endpoint — the endpoints below are the complete public surface.

Scopes

Request scopes space-delimited on /authorize and /bc-authorize. Every requested scope must be registered for your application. Scopes marked sensitive require a binding_message on CIBA requests; restricted scopes are enabled per client by Truora.

ScopeUserInfo claims it unlocksNotes
openidsub; enables the id_token
emailemail, email_verified
phonephone_number, phone_number_verified
profilename, first_name, last_name, gender, birthdate, nationality, updated_at
identityidentity_verified, verification_level, given_name, family_name, birthdate, nationality, document_number, document_type, issuing_authority, is_risky, was_manually_reviewed, plus document_expired and expiration_date when the primary document is expired
documentsdocuments arraysensitive; equivalent to document:ALL:ALL
document:<COUNTRY>:<TYPE>documents filtered to the country/typegranular form — <COUNTRY> is lowercase ISO 3166-1 alpha-2 or ALL, <TYPE> a known document type or ALL
ageage_verified; with a birthdate on file: is_minor, age_range, birthdate
addressaddress object
backgroundtrust_level, background_verified, verification_badges, manual_verification_statussensitive; refreshes an in-progress background check before responding
biometricface_enrolled, last_face_verification_date, liveness_check_passed, face_match_confidence, quality_level, verification_method
verificationverification_status, verification_date, verification_methods
contactemail, email_verified, phone_number, phone_number_verified, preferred_communication_method
nationalitynationality
documents:images, biometric:image— (image delivery; no UserInfo claims today)sensitive
approval:read—gates GET /oauth2/approval-outcome
validations:write—sensitive, restricted; gates POST /oauth2/validations
google:drive:readonly, google:docs:readonly, google:sheets:readonly, google:gmail:readonly, google:calendar:readonlygoogle_tokens / google_tokens_statusrestricted; Google delegated access via the user's consent

Detailed aliases (profile:detailed, identity:basic, identity:full, document:passport, age:exact, address:full, background:summary, verification:detailed, contact:full, biometric:status, …) are accepted and normalized to the flat scopes above.

Base URL

https://api.pass.truora.com

Authorization

Front-channel authorization. Redirect the user’s browser to the /authorize page on https://pass.truora.com to start the Authorization Code flow; the user authenticates and consents, and Truora Pass redirects back to your registered redirect_uri with a single-use authorization code. The Embedded SDK drives this same endpoint inside a modal using response_mode=web_message.

Authentication strength (acr_values). You may require a minimum authentication level; Truora Pass steps the user up when their session is weaker. The effective requirement is the stronger of your request and the floor configured for your application.

ACRMeaning
urn:truora:acr:0Guest / no authentication
urn:truora:acr:1Single factor (password, federated sign-in, email OTP)
urn:truora:acr:2Strong single factor (passkey / WebAuthn)
urn:truora:acr:3Multi-factor with biometrics (factor + face)

The level actually achieved is returned in the id_token acr claim; the methods used are in amr (RFC 8176 values: pwd, webauthn, face, federated, otp, anon).

get

Start the Authorization Code flow

Redirect the user’s browser to https://pass.truora.com/authorize with the query parameters below. After the user authenticates and consents, Truora Pass redirects back to your redirect_uri with code and state query parameters on success, or error, error_description and state on failure. The authorization code is single-use and expires after 10 minutes.

Some failures are rejected inside Truora Pass without redirecting back (your callback never fires): a redirect_uri mismatch, an unregistered scope, an invalid response_type or response_mode, web_message not enabled or the origin not allow-listed, and step-up conditions such as acr_not_satisfied, session_too_old or email_domain_not_allowed.

Request example
curl --request GET \
  --url 'https://api.pass.truora.com/authorize?client_id={client_id}&redirect_uri={redirect_uri}&response_type={response_type}&scope={scope}&state={state}' \
  --header 'Truora-API-Key: {api_key}'
Response
Query Parameters
acr_values string optional

Requested minimum authentication strength, urn:truora:acr:0 through urn:truora:acr:3. Used for step-up authentication.

client_id string required

Your application’s client ID (WLT_APP_...).

max_age integer optional

Maximum age of the Truora Pass session in seconds before the user must re-authenticate.

redirect_uri string required

Callback URL. Must exactly match one of the redirect URIs registered for your application.

response_mode string optional

Empty or query for the redirect flow; web_message for the Embedded SDK modal flow (must be enabled for your application).

response_type string required

Must be code.

scope string required

Space-delimited, URL-encoded list of scopes. Every requested scope must be registered for your application — see the Scopes reference.

state string required

Fresh, unguessable CSRF token bound to the user’s session. Returned unchanged on the callback — verify it matches.

Tokens

Back-channel token endpoint. A single endpoint multiplexed by grant_type: exchange an authorization code for tokens, rotate a refresh token, or poll a CIBA (decoupled) authorization request. Requests carry your client_secret and must always run server-to-server — never in the browser.

Token lifetimes. Authorization codes are single-use and expire after 10 minutes. Access tokens live 60 minutes. Refresh tokens are single-use and rotate on every redemption with a 365-day sliding lifetime — reusing an already-used refresh token revokes the whole token family.

ID token. Issued only when the openid scope is granted (authorization-code and CIBA grants; never on refresh). It is a JWT that expires after 5 minutes, with claims:

ClaimValue
subThe user's stable Truora Pass identifier
isshttps://pass.truora.com
aud[<your client_id>]
iat, expIssued-at / expiry (5 minutes)
jtiUnique token ID
auth_timeWhen the user authenticated (when available)
acrAuthentication level achieved (see Authorization)
amrAuthentication methods used (RFC 8176)
at_hashCIBA only — left-half SHA-256 hash of the access token
urn:openid:params:jwt:claim:auth_req_idCIBA only — the authorization request ID

post

Exchange a code, rotate a refresh token, or poll CIBA

Server-to-server only — this request carries your client_secret and must never run in the browser.

Grant authorization_code (JSON): exchange the single-use code from the callback for tokens. Send grant_type, code, client_id, client_secret and redirect_uri (must match the authorize request). Returns access_token, token_type (Bearer), expires_in (3600), scope, a refresh_token, and an id_token when the openid scope was granted (expires after 5 minutes).

Grant refresh_token (JSON): rotate a refresh token without re-authorizing the user. Send grant_type, refresh_token, client_id, client_secret, and optionally scope to down-scope (a subset of the originally granted scopes). Refresh tokens are single-use and rotate on every call (365-day sliding lifetime): the response contains a NEW refresh_token — replace the stored one. Reusing an already-used token revokes the whole token family. No id_token is returned.

Grant urn:openid:params:grant-type:ciba (form-encoded): poll for tokens after a backchannel authorization request. Send grant_type, auth_req_id, client_id and client_secret, waiting at least interval seconds between polls. While the user has not decided the response is 400 authorization_pending; once approved it returns tokens (no refresh_token for this grant).

Request example
curl --request POST \
  --url 'https://api.pass.truora.com/v1/oauth2/token' \
  --header 'Truora-API-Key: {api_key}' \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data '{"auth_req_id":"string","client_id":"string","client_secret":"string","grant_type":"urn:openid:params:grant-type:ciba"}'
Request body
application/json
grant_type enum required
Allowed: authorization_code refresh_token

authorization_code or refresh_token.

client_secret string required

Your application’s client secret.

client_id string required

Your application’s client ID.

scope string

(refresh_token grant, optional) Space-delimited subset of the originally granted scopes to down-scope the new access token.

code string

(authorization_code grant) The code from the callback. Single-use, expires after 10 minutes.

redirect_uri string

(authorization_code grant) Must match the redirect_uri used on the authorize request.

refresh_token string

(refresh_token grant) The most recently issued refresh token.

Request body
application/x-www-form-urlencoded
grant_type enum required
Allowed: urn:openid:params:grant-type:ciba

urn:openid:params:grant-type:ciba.

client_secret string required

Your application’s client secret.

client_id string required

Your application’s client ID.

auth_req_id string required

The authorization request identifier returned by POST /v1/oauth2/bc-authorize.

Response

Backchannel (CIBA)

Decoupled authorization (OpenID CIBA). Start an authorization request for a user identified by email; Truora Pass delivers an approval link to the user’s verified phone over WhatsApp, and your backend polls the token endpoint until the user approves or declines. Requires the CIBA grant to be enabled for your application — contact Truora.

Beyond plain authorization, CIBA requests can carry rich authorization_details (RFC 9396) for approval-style consent (the user reviews and approves a concrete action, optionally filling a form). Use POST /v1/oauth2/approval-attachments to stage files shown on the approval screen, and GET /v1/oauth2/approval-outcome to read the decision and any submitted form data afterwards.

post

Start a backchannel authorization request

Starts a decoupled authorization request for the user resolved by login_hint (email). Truora Pass sends the user a WhatsApp approval link to their verified phone; your backend then polls POST /v1/oauth2/token with the returned auth_req_id and the CIBA grant type, waiting at least interval seconds between polls.

Requires the CIBA grant to be enabled for your application (contact Truora). The resolved user must have a verified phone. When a sensitive scope (documents, background) is requested, binding_message is required and is shown on the approval screen (truncated to 200 characters).

Request example
curl --request POST \
  --url 'https://api.pass.truora.com/v1/oauth2/bc-authorize' \
  --header 'Truora-API-Key: {api_key}' \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data '{"client_id":"string","client_secret":"string","login_hint":"string","scope":"string"}'
Request body
application/x-www-form-urlencoded
scope string required

Space-delimited scopes to request. See the Scopes reference.

client_secret string required

Your application’s client secret.

login_hint string required

The user’s email address (must contain @).

client_id string required

Your application’s client ID.

authorization_details string

Optional RFC 9396 JSON array (as a string, up to 64 KiB). Its presence switches the request into approval mode — the user reviews a concrete action described by the details (title, prompt, optional JSONForms form and staged attachments) instead of a plain scope consent. When present, scope becomes optional.

binding_message string

Required when any requested scope is sensitive (documents, documents:images, biometric:image, background, validations:write). Shown to the user on the approval screen; truncated to 200 characters.

client_notification_token string

Bearer token (RFC 6750 token68 syntax, up to 1024 chars) that Truora Pass will present when calling your registered backchannel_client_notification_endpoint. Required when your application has one registered.

requested_expiry integer

Seconds the request stays approvable. Default 300, capped at 900.

delegate_notification_to_client string

true to deliver the approval link yourself instead of Truora Pass sending it over WhatsApp (trusted clients). The response then includes approval_url.

acr_values string

Requested authentication context (step-up), urn:truora:acr:0 through urn:truora:acr:3. See the Authorization group for the ACR table.

Response
post

Stage an approval attachment

Stages a file to be shown on a CIBA approval screen (e.g. the contract the user is asked to approve). Returns a presigned upload_url — PUT the file bytes there directly; they never pass through Truora Pass. Reference the returned s3_key from the attachments of your authorization_details on the subsequent POST /v1/oauth2/bc-authorize.

The attachment is keyed to the future approver by login_hint (email), so it can be staged before the user has a Truora Pass account. Allowed content types: image/png, image/jpeg, image/gif, image/webp, application/pdf, text/plain, text/markdown, text/csv, application/json (active content is refused). Maximum object size 10 MiB; the upload URL expires after 10 minutes; file_name is sanitized and limited to 200 characters.

Request example
curl --request POST \
  --url 'https://api.pass.truora.com/v1/oauth2/approval-attachments' \
  --header 'Truora-API-Key: {api_key}' \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data '{"client_id":"string","client_secret":"string","content_type":"string","file_name":"string","login_hint":"string"}'
Request body
application/x-www-form-urlencoded
login_hint string required

Email of the user who will review the approval.

file_name string required

Display name of the file (sanitized, up to 200 characters). Its extension, when present, must match content_type.

content_type string required

MIME type of the file. Must be on the allow-list above.

client_secret string required

Your application’s client secret.

client_id string required

Your application’s client ID.

Response
get

Read an approval outcome

Returns the reviewer’s decision for a CIBA approval request, plus any form data they submitted on the approval screen (the token response has no room for it). Authenticate with a Bearer access token that carries the approval:read scope; the approval must belong to your application.
Request example
curl --request GET \
  --url 'https://api.pass.truora.com/v1/oauth2/approval-outcome?auth_req_id={auth_req_id}' \
  --header 'Truora-API-Key: {api_key}'
Response
Query Parameters
auth_req_id string required

The authorization request ID returned by POST /v1/oauth2/bc-authorize.

UserInfo

Read the user’s verified identity claims. The response is a JSON map whose keys depend on the scopes granted to the access token — see the Scopes table above for the full claim-to-scope map.

get

Read the user's verified identity claims

Returns a JSON map of the user’s verified identity claims for the scopes granted to the access token. sub is always present; empty claims are omitted. When the background scope is granted, background data is refreshed before responding. See the Scopes table above for the complete claim-to-scope map.

When the token carries Google-delegated scopes (google:*), the response additionally includes google_tokens (access_token, refresh_token, expires_at, scopes) or google_tokens_status (re_consent_required when the user must re-consent).

Send the access token as a Bearer token: Authorization: Bearer <access_token>.

Request example
curl --request GET \
  --url 'https://api.pass.truora.com/v1/oauth2/userinfo' \
  --header 'Truora-API-Key: {api_key}'
Response

Validations (restricted)

Append-only write of externally performed identity validations into a user’s Truora Pass profile. Restricted — available only to client applications allow-listed by Truora, with the sensitive validations:write scope granted.

post

Write identity validations

Appends externally performed identity validations (document and/or face) to the user’s Truora Pass profile. Restricted — your client application must be allow-listed by Truora and the access token must carry the sensitive validations:write scope.

Send 1 to 100 items. Each item is type: document (requires the document object with at least document_number and document_type) or type: face (requires the face object). Providing a process_id makes the write idempotent: replaying a request whose process_ids were all already recorded returns 200 with an empty list instead of creating duplicates.

Request example
curl --request POST \
  --url 'https://api.pass.truora.com/v1/oauth2/validations' \
  --header 'Truora-API-Key: {api_key}' \
  --header 'Content-Type: application/json' \
  --data '{"validations":"string"}'
Request body
application/json
validations array required

1–100 validation items. Each item has type (document or face), resource_id (required), verified (boolean), and optionally resource_url, process_id, plus the type-specific document (document_number, document_type, country, first_name, last_name, date_of_birth, expiration_date, front_image, reverse_image) or face (face_photo) object.

Response

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.

  • If you haven’t already, sign up for a free account here before generating your Truora-API-Key.
  • Learn how to generate your Truora-API-Key here.
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.

post

Create Validation Account

Creates a validation account with options to include details such as name, document, email, phone, social media usernames, and other personal identifiers. This account provides a convenient way to track validations linked to a specific user.
Request example
curl --request POST \
  --url 'https://api.validations.truora.com/v1/accounts' \
  --header 'Truora-API-Key: {api_key}'
Request body
application/x-www-form-urlencoded
email string

Email address of the person associated with the account.

facebook_user string

Facebook username of the person associated with the account.

first_name string

First name of the person associated with the account.

country string

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.

document_number string

Document number of the person associated with the account.

document_type enum
Allowed: national-id identity-card foreign-id passport

Type of document for the person associated with the account.

last_name string

Last name of the person associated with the account.

phone_number string

Phone number of the person associated with the account.

twitter_user string

X (formerly Twitter) username of the person associated with the account.

account_id string

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.

document_issue_date string

Issue date of the person’s document, formatted in RFC3339 (e.g., 2000-05-24).

Response
get

List Validation Accounts

Retrieves all validation accounts created under your client account, with optional pagination using the start_key query parameter. The response includes a list of each validation account and its details.
Request example
curl --request GET \
  --url 'https://api.validations.truora.com/v1/accounts' \
  --header 'Truora-API-Key: {api_key}'
Response
Path Parameters
start_key string required

Start key value for the pagination.

get

Get Validation Account

Retrieves details of the specified validation account ID. This account represents an individual user within the validation system.
Request example
curl --request GET \
  --url 'https://api.validations.truora.com/v1/accounts/{account_id}' \
  --header 'Truora-API-Key: {api_key}'
Response
Path Parameters
account_id string required

ID of the account to be retrieved.

get

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.

Request example
curl --request GET \
  --url 'https://api.validations.truora.com/v1/accounts/{account_id}/enrollments' \
  --header 'Truora-API-Key: {api_key}'
Response
Path Parameters
account_id string required

The account ID for which the enrollments will be retrieved.

get

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:

Request example
curl --request GET \
  --url 'https://api.validations.truora.com/v1/accounts/{account_id}/validations' \
  --header 'Truora-API-Key: {api_key}'
Response
Path Parameters
account_id string required

The account ID linked with the validations.

get

Get Validation from Account

Note: This request will soon be deprecated. Please use the Get Validation (GET /v1/validations/{validation_id}) request instead.

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:

Request example
curl --request GET \
  --url 'https://api.validations.truora.com/v1/accounts/{account_id}/validations/{validation_id}' \
  --header 'Truora-API-Key: {api_key}'
Response
Path Parameters
account_id string required

Unique identifier of the account associated with the validation.

validation_id string required

Unique identifier of the validation.

Query Parameters
show_details boolean optional

If set to 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.

post

Create Enrollment

This is the first step in validation processes like Face Search, Face, Phone, and Email validation. It requires the submission of necessary images or base information. During enrollment, essential materials, such as photographs or other relevant data, are collected to serve as the basis for user verification. It is important to emphasize that the actual validation will take place in later steps, using the information gathered during this stage. This step is crucial to ensure the system has all the necessary elements to perform an accurate and effective evaluation in subsequent stages.
Request example
curl --request POST \
  --url 'https://api.validations.truora.com/v1/enrollments' \
  --header 'Truora-API-Key: {api_key}' \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data '{"type":"face-recognition","user_authorized":true}'
Request body
application/x-www-form-urlencoded
type enum required
Allowed: face-recognition email-verification phone-verification face-search

Indicates the type of validation to be performed along with this enrollment.

user_authorized boolean required

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.

account_id string

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.

country string

[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

phone_number string

[Required for phone-verification] Phone number to be associated with the validation account on successful validation. Must include the country code (e.g., +57300XXXXXXX).

phone_type enum
Allowed: home office recover

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

confirmation enum
Allowed: none

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.

email string

[Required for email-verification] Email to be associated with the user account.

fraud_reason enum
Allowed: manipulated_document manipulated_photo non_payment criminal_records_in_company fraudster

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

Response
Query Parameters
account_id string optional

Validation account ID. If left empty, a new validation account will be created

get

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.

Request example
curl --request GET \
  --url 'https://api.validations.truora.com/v1/accounts/{account_id}/enrollments' \
  --header 'Truora-API-Key: {api_key}'
Response
Path Parameters
account_id string required

The account ID for which the enrollments will be retrieved.

get

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.

Request example
curl --request GET \
  --url 'https://api.validations.truora.com/v1/enrollments/{enrollment_id}' \
  --header 'Truora-API-Key: {api_key}'
Response
Path Parameters
enrollment_id string required

Enrollment ID to search.

delete

Delete enrollment

Deletes an enrollment. If this endpoint is executed on an enrollment ID, the enrollment will be removed from the client’s account.
Request example
curl --request DELETE \
  --url 'https://api.validations.truora.com/v1/enrollments/{enrollment_id}' \
  --header 'Truora-API-Key: {api_key}'
Response
Path Parameters
enrollment_id string required

Enrollment ID to be removed from the client’s account.

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.

post

Create Validation

Creates a new validation for the specified validation type. This process allows your company to confirm that the user’s identity matches the provided information (such as documents, images, videos, or codes like OTP), ensuring accuracy and security in the verification process, which is crucial for legal responsibilities.
Request example
curl --request POST \
  --url 'https://api.validations.truora.com/v1/validations' \
  --header 'Truora-API-Key: {api_key}' \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data '{"account_id":"string","type":"document-validation","user_authorized":true}'
Request body
application/x-www-form-urlencoded
user_authorized boolean required

This indicates that you have the authorization of the person to be verified. This is mandatory in order to comply with data protection laws. Value must be set to true in order to perform the validation.

account_id string required

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.

type enum required
Allowed: document-validation face-recognition email-verification phone-verification face-search

Indicates the type of validation to be performed.

check_manual_review_availability boolean

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.

custom_input string

Optional external identifier stored in the database along with the main structure. Used for reference purposes only, without affecting processing or logic. (Maximum length: 128 characters).

phone_locale enum
Allowed: en es pt-BR

[Required for phone-verification] Language used to perform the validation via the selected verification channel.

subvalidations enum
Allowed: passive_liveness similarity speech_match

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.

phone_type enum
Allowed: home office recover

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

language enum
Allowed: es en

For email-verification, specifies the language of the email that the final user receives.

country string

[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 | SV | 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

verify_channel enum
Allowed: sms call whatsapp

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

document_type enum
Allowed: national-id foreign-id driver-license passport identity-card rut ppt invoice picture-id record cnh

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

retry_of_id string

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

threshold number

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.

timeout integer

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.

minimum_precision enum
Allowed: very_high high medium low

[Required for speech_match subvalidation] Minimum precision that the audio transcription obtained from the video selfie should have with the speech_token.

custom_type string

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.

Response
post

Perform validation

Perform validation for the specified 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.
Request example
curl --request POST \
  --url 'https://api.validations.truora.com/v1/validations/{validation_id}' \
  --header 'Truora-API-Key: {api_key}' \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data '{"token":"string","type":"email-verification"}'
Request body
application/x-www-form-urlencoded
type enum required
Allowed: email-verification phone-verification

Indicates the type of validation to be performed.

token string required

The validation code sent to the user’s email or phone (via SMS, call, or WhatsApp) for verification.

Response
Path Parameters
validation_id string required

ID of the validation to be performed.

post

Restores a previously deleted validation and its associated data

The data restoration endpoint restores a previously deleted validation record and all linked user data across Truora services
Request example
curl --request POST \
  --url 'https://api.validations.truora.com/v1/validations/{validation_id}/restore' \
  --header 'Truora-API-Key: {api_key}'
Response
Path Parameters
validation_id string required

Unique ID of the validation record to restore

put

File Upload

Allows the upload of binary files, such as images or videos, needed for document validation or person verification. To upload a file, make a PUT request to the URL provided during the validation or enrollment process.
Request example
curl --request PUT \
  --url 'https://api.validations.truora.com{file_upload_url}' \
  --header 'Truora-API-Key: {api_key}' \
  --header 'Content-Type: ' \
  --data '{"file":"string"}'
Request body
file binary required

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.

Response
get

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:

Request example
curl --request GET \
  --url 'https://api.validations.truora.com/v1/accounts/{account_id}/validations' \
  --header 'Truora-API-Key: {api_key}'
Response
Path Parameters
account_id string required

The account ID linked with the validations.

get

Get Validation from Account

Note: This request will soon be deprecated. Please use the Get Validation (GET /v1/validations/{validation_id}) request instead.

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:

Request example
curl --request GET \
  --url 'https://api.validations.truora.com/v1/accounts/{account_id}/validations/{validation_id}' \
  --header 'Truora-API-Key: {api_key}'
Response
Path Parameters
account_id string required

Unique identifier of the account associated with the validation.

validation_id string required

Unique identifier of the validation.

Query Parameters
show_details boolean optional

If set to true, retrieves additional validation details, including links to user-uploaded files that remain valid for 15 minutes.

get

Get Document Selection

Returns a catalog of countries and document types that clients can use when choosing documents for validation workflows
Request example
curl --request GET \
  --url 'https://api.validations.truora.com/v1/config/document-selection' \
  --header 'Truora-API-Key: {api_key}'
Response
get

Get Document Infographic

Retrieves infographic slides for specific document versions to display in manual review. Searches by country and document version, returning the first matching file found.
Request example
curl --request GET \
  --url 'https://api.validations.truora.com/v1/document-infographic' \
  --header 'Truora-API-Key: {api_key}'
Response
get

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:

Request example
curl --request GET \
  --url 'https://api.validations.truora.com/v1/validations' \
  --header 'Truora-API-Key: {api_key}'
Response
get

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:

Request example
curl --request GET \
  --url 'https://api.validations.truora.com/v1/validations/{validation_id}' \
  --header 'Truora-API-Key: {api_key}'
Response
Path Parameters
validation_id string required

Unique identifier of the validation.

Query Parameters
show_details boolean optional

If set to true, retrieves additional validation details, including links to user-uploaded files that remain valid for 15 minutes.

delete

Deletes a validation and all its associated data

The data deletion endpoint removes a validation record and all linked user data across Truora services
Request example
curl --request DELETE \
  --url 'https://api.validations.truora.com/v1/validations/{validation_id}' \
  --header 'Truora-API-Key: {api_key}'
Response
Path Parameters
validation_id string required

Unique ID of the validation record

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.

    ParametersDocument ValidatorFace ValidatorPhone ValidatorEmail Validator
    timeoutXXXX
    allowed_retriesXXXX
    retry_ttlXX--

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.

put

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:

Request example
curl --request PUT \
  --url 'https://api.validations.truora.com/v1/config' \
  --header 'Truora-API-Key: {api_key}' \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data '{"validator":"face-recognition"}'
Request body
application/x-www-form-urlencoded
validator enum required
Allowed: face-recognition email-verification phone-verification document-validation

Validator to be configured.

threshold number

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.

timeout number

The time, in seconds, users will have to complete the validation.

  • Default: 300 (5 minutes) for all validators.
  • Max: 600 (10 minutes) for phone-verification and email-verification;
    21600 (6 hours) for document-validation and face-recognition.

validation_method.manual-review.status enum
Allowed: enabled disabled

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.

validation_method.image-analysis.status enum
Allowed: enabled disabled

Checks for any alterations or edits in the image of the validated document in document-validation.

validation_method.photo-of-photo.status enum
Allowed: enabled disabled

Analyzes if the image used for validation is a photograph of a photograph of a document in document-validation.

country enum
Allowed: CO CL MX PE BR SV ALL

Country for which the document-validation configuration will be updated.

document_type enum
Allowed: national-id foreign-id driver-license passport identity-card rut ppt invoice picture-id record cnh

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

document_version enum
Allowed: mx_ine-c mx_ine-d mx_ine-e mx_ife-f mx_ife-g mx_fm3 co_national-id-2000 co_national-id-2020 co_foreign-id co_ppt passport

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.

email_title string

Custom main title text in the email-verification validator email. For details, language options and default values, see the Email Validator Config guide.

include_face_search boolean

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

use_manual_review boolean

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.

allowed_retries number

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-verification and phone-verification: The default value is 2 retries, with a maximum of 4 retries.

validation_method.photocopy-analysis.status enum
Allowed: enabled disabled

Analyzes if the image used for document-validation is a photocopy of a document.

email_subject string

Custom subject text in the email-verification validator email. For details, language options and default values, see the Email Validator Config guide.

retry_ttl number

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

support_email string

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.

validation_method.data-consistency.status enum
Allowed: enabled disabled

Analyzes the extracted data from the document for consistency in document-validation, such as date of birth and document number.

validation_method.government-database-validation.status enum
Allowed: enabled disabled

Validates the extracted identification number against government databases in document-validation.

custom_name string

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.

email_text_1 string

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.

email_text_2 string

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.

Response
get

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.

Request example
curl --request GET \
  --url 'https://api.validations.truora.com/v1/config' \
  --header 'Truora-API-Key: {api_key}'
Response
delete

Delete Config

Allows you to delete a validator’s configuration or a specific parameter (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.
Request example
curl --request DELETE \
  --url 'https://api.validations.truora.com/v1/config?validator={validator}' \
  --header 'Truora-API-Key: {api_key}'
Response
Query Parameters
type enum optional

If validator is document-validation:
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.

validator enum required

Allowed: document-validation | face-recognition | email-verification | phone-verification

Name of the validator’s config to be deleted.

Status

Status lets you check the current state of our services in real time.

get

Get status

Checks the current availability of the validations API. If this endpoint fails, it means the validations api is down and should contact support.
Request example
curl --request GET \
  --url 'https://api.validations.truora.com/v1/status' \
  --header 'Truora-API-Key: {api_key}'
Response