Checks API
NOTE: Truora provides a Postman collection online that includes the necessary tools to simplify the testing process.
Welcome to the Truora Check RESTful API reference. If you haven’t already, we strongly advise you to check out our Guides Section.
Truora Check API allows performing full background checks on people, vehicles and companies. There are three main types of background checks:
- Personal background check: Verifies national IDs in multiple databases of public and legal entities in the LATAM region. For every national ID, returns information on: personal identity, criminal records, international background check, and professional background.
- Vehicle background check: Verifies the vehicle documents and the owner identity in multiple databases of public and legal entities in the LATAM region. For every vehicle and owner type, returns information on: personal identity, driving records, criminal records, and vehicle information.
- Company background check: Verifies the tax ID or a company name in multiple databases of public and legal entities in the LATAM region. For every company, returns the associated: business status, legal and criminal records, and media reports.
Authentication
To access Truora’s services and perform API calls securely, you need to authenticate your requests. This is done by including a specific authentication token, known as the ”Truora-API-Key” in the header of your requests.
By providing this key in your API requests, you establish a secure and authorized connection, enabling seamless interaction with Truora’s services.
Base URL
https://api.checks.truora.com
Checks
Checks API enables you to create and retrieve background checks. It consults multiple databases and provides a comprehensive set of information to assess the reliability of a person, vehicle, or company. Explore our guide on Background Checks for further details.
Create check
Creates a background check and queues it to start collecting information. The full details of background checks can be retrieved with their respective Check IDs using getCheck endpoint. Keep in mind that, depending on the check type, input document, and country of a search, certain inputs are required. You should always provide as many inputs as possible in order to get the highest accuracy.
If your check type is not referenced in the following table, please reach out to find out the fields that apply for you.
Document country
Indicates whether the person subject to the validation authorized the validation. Must be true in order to proceed [Required for API key V1 or later]
Background check type. Replace custom_type_name with the name of your custom type to perform a custom type check
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).
Diplomatic ID
Person phone number. Required by law to notify the person their background is being checked
Company ID used for tax payments
national-id, foreign-id, tax-id or passport
Vehicle NIV number
Colombian escrow
15-digit IMEI to be validated
Payment day of a vehicle circulation permit (Chile only)
ID for Venezuelans working in Colombia
ID for Venezuelans working in Peru
This field also apply for PPT (Permiso de Protección Temporal) in Colombia
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
Person birth certificate
Folio for Chilean certificate search. Chile only
Company name “Don’t forget this required field to complete background checks in Brazil”
ID of the vehicle owner
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.
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.
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.
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.
Vehicle license plate
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
Document number of Chilean identity. This number is used to get some additional information about a person. Chile only
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.
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.
National ID
National ID from the person native country. Keep in mind that you must provide the native_country if you enter a native_national_id
Professional ID card
Report ID the background check will be inserted into
Verification code registered for criminal records in Peru and Chile
Driver’s license number
Person foreign ID
Country of birth. Required if native_national_id is provided
Person passport
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
Receive webhook
List checks
Get check
Returns the results of the check that matches the ID provided, complete with a set of scores explained below.
Scores:
- Global Score: Average risk associated with a person, company or vehicle, according to the background check results. The global score considers results that are validated with the ID number provided. The score ranges from 0 to 1, where 0 represents high risk and 1 low risk.
- ID Score: Average risk associated with a person according to the background check results. The ID score considers the results that are validated with a person identity document. The score ranges from 0 to 1, where 0 represents high risk and 1 low risk.
- Name Score: Average risk associated with a person according to the background check results. The name score considers results that are validated against the name of a person and could not be validated with their ID number. These results might have homonyms associated with them. The score ranges from 0 to 1, where 0 represents high risk and 1 low risk.
In order to calculate these scores, a weighted average is considered with different weights allocated to each dataset. Scores can be customized using the config endpoints by assigning a weight to each dataset according to its relevance.
Keep in mind that results from the API vary depending on the country, check type and the inputs entered on check creation.
Get Check Attachments
List Check Details
Summarize
Get the status of a database
Delete check
Custom-Type
The Custom Type API enables the creation of custom searches, allowing you to include only the desired datasets in background checks, thus enhancing the check efficiency. Moreover, you can customize the impact of each dataset on the global score by assigning it a weight value between 0 and 1. It’s important to note that the sum of all weights must equal 1.
You can use custom types in your checks to perform custom-type checks. For detailed information, refer to our Custom Type guide.
Create custom type
typeCountry where this set of rules applies. Use “all” if the check type searches by name by relying on international databases
Custom type name. It cannot be person, vehicle, or company. Use this type in your checks to perform custom-type checks
Affiliation and insurance weight for score calculation. From 0 to 1. If not provided, the dataset is skipped entirely decreasing the search time
Professional background weight for score calculation. From 0 to 1. If not provided, the dataset is skipped entirely decreasing the search time
Taxes and financial background weight for score calculation. From 0 to 1. If not provided, the dataset is skipped entirely decreasing the search time
Personal identity weight for score calculation. From 0 to 1. If not provided, the dataset is skipped entirely decreasing the search time
International background weight for score calculation. From 0 to 1. If not provided, the dataset is skipped entirely decreasing the search time
Legal background weight for score calculation. From 0 to 1. If not provided, the dataset is skipped entirely decreasing the search time
Alert in media weight for score calculation. From 0 to 1. If not provided, the dataset is skipped entirely decreasing the search time
Criminal record weight for score calculation. From 0 to 1. If not provided, the dataset is skipped entirely decreasing the search time
Vehicle certificate background weight for score calculation. From 0 to 1. If not provided, the dataset is skipped entirely decreasing the search time
Business background weight for score calculation. From 0 to 1. If not provided, the dataset is skipped entirely decreasing the search time
Driving license weight for score calculation. From 0 to 1. If not provided, the dataset is skipped entirely decreasing the search time
Traffic fines weight for score calculation. From 0 to 1. If not provided, the dataset is skipped entirely decreasing the search time
Vehicle information weight for score calculation. From 0 to 1. If not provided, the dataset is skipped entirely decreasing the search time
Update custom type
Custom type name. It cannot be person, vehicle, or company. Use this type in your checks to perform custom-type checks
Country where this set of rules applies. Use “all” if the check type searches by name by relying on international databases
Traffic fines weight for score calculation. From 0 to 1. If not provided, the dataset is skipped entirely decreasing the search time
Vehicle certificate background weight for score calculation. From 0 to 1. If not provided, the dataset is skipped entirely decreasing the search time
Business background weight for score calculation. From 0 to 1. If not provided, the dataset is skipped entirely decreasing the search time
Driving license weight for score calculation. From 0 to 1. If not provided, the dataset is skipped entirely decreasing the search time
Criminal record weight for score calculation. From 0 to 1. If not provided, the dataset is skipped entirely decreasing the search time
Vehicle information weight for score calculation. From 0 to 1. If not provided, the dataset is skipped entirely decreasing the search time
International background weight for score calculation. From 0 to 1. If not provided, the dataset is skipped entirely decreasing the search time
Legal background weight for score calculation. From 0 to 1. If not provided, the dataset is skipped entirely decreasing the search time
Personal identity weight for score calculation. From 0 to 1. If not provided, the dataset is skipped entirely decreasing the search time
Professional background weight for score calculation. From 0 to 1. If not provided, the dataset is skipped entirely decreasing the search time
Taxes and financial background weight for score calculation. From 0 to 1. If not provided, the dataset is skipped entirely decreasing the search time
Alert in media weight for score calculation. From 0 to 1. If not provided, the dataset is skipped entirely decreasing the search time
Affiliation and insurance weight for score calculation. From 0 to 1. If not provided, the dataset is skipped entirely decreasing the search time
List custom types
Delete custom type
Allows deleting a custom type. Please note that person, vehicle, and company custom types can not be deleted.
After deletion, the response will display the remaining custom types associated with the country of the deleted custom type.
Settings
Allows the configuration of parameters such as names matching type, retries and max duration.
Create setting
Indicates whether or not database queries must be retried until they successfully return a response or until the max_duration time is reached
Indicates the maximum amount of time a check can take to fetch responses. It follows the following format "xt" where x is a number and t is a letter ( m for minutes or h for hours). Example 25m indicates 25 minutes, 2h indicates 2 hours. This value must be between 15 minutes and 7 days (168 hours). When not configured, it is set to default. If retries is enabled, the default max duration is set to 48 hours; otherwise, it is set to 3 hours for Colombia, Mexico, Peru, and Brazil; 48 hours for Chile and International searches; and 72 hours for Costa Rica
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
Credentials
Allows the management of credentials for the checks API.
Create or update credential
Password for the collector credential
Username for the collector credential
Additional authentication complements
List credentials
Delete credential
Continuous
Enables the creation of recurring checks with customizable frequency, providing notifications whenever there are changes in check scores.
Create Continuous Check
Time between background checks. It can be daily, weekly, monthly, yearly or have a custom frequency written as a number accompanied by a letter d: day, w: week, m: month, y: year. For instance: 3d: every three days, 2w: every two weeks
Date on which background checks will stop. YYYY-MM-DD format. For the date to be valid, it must allow at least one check to be run according to the frequency.
Background checks to be processed recurrently
Update Continuous Checks
Time between background checks
Indicates whether the background checks must be processed recurrently
API Key version to be used for the continuous check hooks. This version must match API key version you use. Version 0 is used by default.
List Continuous Checks
Get Continuous Checks
List Continuous Check Logs
Enables the export of a comprehensive PDF containing the obtained information, Truora’s assigned score, and consulted datasets. For more details, refer to Background Checks: PDF, Variables and Attachments guide.
Create PDF
Get PDF
Batch
Given a valid xlsx file, this endpoint takes the information from the file and starts creating the checks and associating it to the specified report object. For a step-by-step explanation of all methods and required fields for submitting a batch, please refer to the Background Checks Batch via API guide.
Create Batch
This endpoint facilitates the creation of batches of different types. This endpoint does not include input file uploading or batch start logic.
The check inputs to be uploaded in the file can be manually mapped using columns_mapping.{input_name} body params, by default the inputs accepted by the check type will be mapped. The request will return a columns array with the order in which the inputs should be in the xlsx file.
The batch creation request returns a temporary URL in the file_upload_link field. This URL must be used to make a PUT request with the file containing the mapped batch data. It is crucial to note that the URL has a limited expiration time (30min) and will only allow the first submitted file to be uploaded. Therefore, it is highly recommended to carefully review the information before uploading.
Type of the batch checks. Replace custom_type_name with the name of your custom type to perform a batch of custom type checks. In case you want to create a custom type please visit How to Create a Custom Type for Background Check guide for more information.
The service for which the batch will be processed
The country of batch checks
Columns mapping of the xlsx file. This body parameter must be sent for each column you want to upload in the xlsx file, replacing the input_name with the name of the input (e.g. columns_mapping.national_id). The value must be the index of the column in the file, being 0 for column A, 1 for column B and so on. If no column mapping is sent, all inputs for the selected custom type will be automatically mapped.
Date on which background checks will stop to create a batch of continuous checks. YYYY-MM-DD format. For the date to be valid, it must allow at least one check to be run according to the frequency.
Time between background checks to create a batch of continuous checks. It can be daily, weekly, monthly, yearly or have a custom frequency written as a number accompanied by a letter d: day, w: week, m: month, y: year. For instance: 3d: every three days, 2w: every two weeks
Request Batch Report Generation
Batch report file format
Start Batch
Stop Batch
Get Batch
Get Batch Report
Create Rule
Rule name
Condition for the rule, written in jsonlogic
Event type
Set action env var
Variable name (must start with a letter, alphanumeric and underscore only)
Whether the value is stored as secret (encrypted)
Variable value
Edit Rule
Condition for the rule, written in jsonlogic
Event type
Rule name
List Rules
Get Rule
Get action env vars
List Events
Get Event
Delete Rule
Delete env var
Get variables spec
Create Rule Action
Action type
Action name
Action status
Update Action
Action name
Action status
Action type
Get Rule Actions
Delete Action
Digital Identity
NOTE: Truora provides a Postman collection online that includes the necessary tools to simplify the testing process.
Truora Digital Identity (Truora DI) is a versatile platform that allows you to create a personalized process for authenticating your users. It enables you to utilize a range of Validators in a single process to simplify user identity verification. The Validators enable diverse actions, ranging from verifying that a phone or email belongs to the user, to matching users´ biometrics against government sources. The platform offers the flexibility to create the processes securely and without introducing complexity to the user experience, ensuring your new users can promptly access and enjoy your services.
Authentication
To access Truora’s services and perform API calls securely, you need to authenticate your requests. This is done by including a specific authentication token, known as the ”Truora-API-Key” in the header of your requests.
By providing this key in your API requests, you establish a secure and authorized connection, enabling seamless interaction with Truora’s services.
Base URL
https://api.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.
Send Identity Process Link
Indicates the channel through which the link to initiate the validation will be sent. Before selecting the channel, note that some problems may occur when receiving the SMS due to external protocols of mobile service providers.
Indicates the language of the message explaining why the validation link is being sent. This parameter must be sent using the ISO 639-1 lowercase format.
Indicates the phone number of the person to whom the link will be sent. This parameter must be provided in E.164 format (e.g., +573001112233 for Colombia).
Identifier for the outbound message to use. Required if message_channel is set to whatsapp. Must be valid for redirection.
Template variables required for the outbound message. To use these variables, outbound_id must be explicitly set.
Target email address. Required if message_channel is set to email. Must follow a valid email format.
Generate Token
API key type
API key version. Version 0 is used by default
Billing hubs allow for separated counters and billing. Required if the customer uses billing hubs
Document type for the identity verification process. Only used if grant is set to digital-identity
List of emails to be validated during the identity verification process
Validation flow to be performed for the identity verification process. Required only if grant is set to digital-identity
Indicates which service this API key grants access to. Required if key_type is set to web or sdk
API key name. Required only if key_type was set to backend
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.
Country for the identity verification process. Required only if grant is set to digital-identity
List of phone numbers to be validated during the identity verification process
URL where the user is to be redirected once the verification process has ended. Required if grant is set to digital-identity
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.
Get Result
Allows you to retrieve the current status and details of a process. The status begins as pending and updates to either success or failure when the process completes.
- Pending: The process is still ongoing.
- Success: All steps in the process have been successfully completed. If the flow includes validators, all
validation_statusvalues must also be successful. - Failure: Occurs due to an internal error, timeout, or if the process is declined or expired.
Here’s a comprehensive list of reasons why a process or validation might be declined or expired, as recorded in the declined_reason and expired_reason fields:
If a process includes validators and the identity process times out because a validation did not complete, but all inputs have been uploaded, the system grants an additional 5 minutes to receive a validation response with the final status. This behavior occurs up to 3 times.
On the final attempt to retrieve the validation response, if the validation remains in the pending status, the identity process status will update to failure, with failure_status set to expired.
If a process includes the attributes override_status and override_status_history, it means the final status was modified by an authorized user. In this case, use the override_status attribute instead of status to determine the final status of the process. The override_status_history attribute will contain the history of changes made to the status.
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.
Manage WhatsApp Business lines, inbound flows, campaigns, and sessions.
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
Identifier of the Flow previously created.
Unique message the users will be sending to the business WhatsApp (WABA) in order to begin the Flow.
Phone number of the WABA that interacts with the users. Must include the country code. Example 14080001111.
Create WABA subscription
Provider Statuses
Cancell Campaign
Finish WhatsApp session
Update Inbound Flow
Allows updating an inbound flow.
Note: Do not forget that if you already have a whatsapp link created and you update it, you must generate a new link.
Identifier of the Flow previously created.
Unique message the users will be sending to the business WhatsApp (WABA) in order to begin the Flow.
Phone number of the WABA that interacts with the users. Must include the country code. Example 14080001111.
Put WABA Line config
Get WABA Line
Get Inbound Flow
List Inbound Flows
List WABA Lines
Get Result
Allows you to retrieve the current status and details of a process. The status begins as pending and updates to either success or failure when the process completes.
- Pending: The process is still ongoing.
- Success: All steps in the process have been successfully completed. If the flow includes validators, all
validation_statusvalues must also be successful. - Failure: Occurs due to an internal error, timeout, or if the process is declined or expired.
Here’s a comprehensive list of reasons why a process or validation might be declined or expired, as recorded in the declined_reason and expired_reason fields:
If a process includes validators and the identity process times out because a validation did not complete, but all inputs have been uploaded, the system grants an additional 5 minutes to receive a validation response with the final status. This behavior occurs up to 3 times.
On the final attempt to retrieve the validation response, if the validation remains in the pending status, the identity process status will update to failure, with failure_status set to expired.
If a process includes the attributes override_status and override_status_history, it means the final status was modified by an authorized user. In this case, use the override_status attribute instead of status to determine the final status of the process. The override_status_history attribute will contain the history of changes made to the status.
Get Campaign
Get Process Validations
List WABAs
Remove Inbound Flow
Update WABA Line
WA Engagement
Increase your customer engagement by automating your customer service, marketing and sales process in WhatsApp.
Delete Agent Templates
Array of the names of the templates that should be deleted.
Update agent capacity settings
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 value to use for the update. Not required for “toggle_capacity” update type.
List of targets whose settings will be updated. Only required for “user” update type.
Send Outbound Message
status needs to be APPROVED before it can be sent.[Required] Country code for the user phone number. Example: +57
[Required] If the Outbound Message is_notification field is false. Contains the FlowID of the flow that will start when the Outbound message is accepted by the user.
Example: IPF123
[Required] ID of an approved Outbound Message. Example: OTB123
[Required] Phone number without the country code of the user that will receive the message. Example: 0001234567
[Required] Must be true for starting the conversation.
User has authorized to be contacted through WhatsApp.
[Required] If the outbound message has variables like hello {{.name}} {{.lastname}}. The value must be the desired value of the variable.
It is important to send as many key-value pairs as variables present in the message.
Example: for the first variable var.name: Roger and for the second variable var.lastname: Federer.
This field is used as a unique identifier for your user in the Truora’ system. If you send it, outbound messages sent to each user will be linked through this. Note that only Account IDs following the regex pattern [a-zA-Z0-9_.-]+ are supported. Please go to Create an Account ID to learn more about it.
Update agent status
Determines the user whose status will be updated.
The new status the user will have.
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.
Language code for the outbound message content.
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.
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.
WABA Line (WhatsApp Business Account Phone Number) used to send the outbound message.
Message category. Refer to the Meta Template Categorization to determine the appropriate category when creating outbound messages.
Identifier name for the outbound message.
Maximum 512 characters.
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 ifcategoryis equal toMARKETING. 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. ForCOPY_CODEbuttons, this must be an empty string ("") because the label is automatically set based on thelanguage_code. -
url(string): Required iftypeisURL. 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 thehttporhttpsscheme. For example,https://www.example.com/{{.url_path}}is valid, butftp://...or a URL without a hostname is not. -
phone_number(string): Required iftypeisPHONE_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 includeQUICK_REPLYbuttons. - 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.
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.
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.
Applicable only if category is MARKETING or UTILITY.
Optional plain text footer displayed immediately after the body component.
Maximum 60 characters.
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.
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%" }
}
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.
Create Agent Template
Type of the template, which defines the content of the template.
Name of the template.
Request a new chat export
Type of the export. Defines the scope of the chats included in it.
Format of the file or files the export request generates as output.
Date defining the start of the time range that should be used for the export. Currently only year and month are taken into account.
Date defining the end of the time range that should be used for the export. Currently only year and month are taken into account.
Language used in the formatting of the export output files.
Optional name for the export request.
ID of the chat that will be exported. Only required if export_type is “single_chat”.
Force chat assignment dequeue
The strategy used to override the assignment request.
The assignment target. Only required for certain assignment types. For specific agent assignments, it must be the agent’s email.
Send a message to a chat
Update Outbound Message
Update Agent Template
Type of the template, which defines the content of the template.
Update chat owner/status
The email of the agent that will become the chat’s owner.
The new status of the chat.
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.
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.