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}'