1 of 25

Verified Business APIs

Getting Started

Welcome to the API Documentation for our Verified Business Caller ID Solution!

In this you'll find everything you need to seamlessly integrate our APIs into your systems. Our clear, step-by-step guides and detailed references are designed to help you streamline your processes, enhance customer interactions, and drive operational efficiency. Explore the documentation and unlock the full potential of our solution today.

API URLs to be used

Authentication

This page provides the steps to generate the Key ID and Secret API Key.

Generate API Keys

API keys are used to ensure the authenticity of interactions between your application and Truecaller for Business APIs.A maximum of 10 tokens can be created every 30 minutes.

Truecaller for Business uses API keys for authenticating API requests.
You can view and manage your API keys from the True caller for Business console.
Click on “Manage API Keys” from the overflow menu beside the account name in the left hand side panel of the console.
Click on the “Create API Key” button.
Enter the Key Name and Description (optional). You can see the access level underneath the description box for all available features.
Click on “Generate”. This will take you to the screen which has the option to copy/save the Key ID and Secret API Key. This file should be downloaded and kept securely.

A total of 5 API Keys can be configured under a customer account at a given point in time.

Customers will not be able to see the secret key and key ID once generated. It is advised that you should copy the secret key and key ID and save it in a safe and secure folder. In case if you have failed to secure the secret key and key ID ,there is an option to regenerate the secret key and key ID using the regenerate option on the Manage API Keys Page

Generate Access Token

This API is used to generate an access token using the Key ID and Secret API Key created from the Manage API Keys page

Validity of the auth token is 60min ,post that we need to recall the API for fresh auth token value.

Replace the {{BaseURL}}

Call Personalisation

Build secure and personalised calling experiences with end to end authentication of every call. Deliver personalised context and identity with APIs that seamlessly integrate into your existing calling infrastructure.

Here are some use cases for Call Personalisation APIs:

Enhance your Verified Business identity by making every call secure with call-by-call assurance through an automated signing process.
Calling operations done through non-company owned numbers where a permanent identity cannot be listed.
Scheduled calling operations that are run daily, where your business wants to add a clean identity and personalised call context for optimal performance.
Calls often made from one business number to multiple users.
Refreshing your identity on Truecaller easily, if your business has limited calling numbers.

Pre-requisites for using Call Personalisation APIs:

Android Device Pre-requisite: Please make sure that the settings mentioned in this documentation are followed for the Dynamic Caller Id to work.
iOS Device – Live Caller ID Limitation:Dynamic Caller ID is currently not supported on iOS devices. However, Static Caller ID can still be enabled and used on iOS. For settings on iOS, kindly refer
Dynamic Label ID: Only “Dynamic Label IDs” can be used in the API request for placing calls.

A subscription to a package that includes Call Personalisation APIs.

Integration steps:

If your business is interested in knowing more about Call Personalisation APIs, please reach out to -> [email protected]

Call Personalisation Real-time v2

Real-time synchronous API to personalize calls for a given Caller-Receiver combination

Replace the {{BaseURL}} with the one mentioned here

POST {{BaseURL}}/v2/clients/{clientAccountId}/dynamic_call_record

{clientAccountId} : This can be taken directly from the self serve portal under the Manage API Keys Page

This API can handle 100 requests per second per token.

For Authorization Token kindly refer the section followed by API

Headers

Name

Value

Body

Name

Type

Validations

Description

Request

Response

Call Personalisation Batch v2

This endpoint pushes the dynamic caller ID details to the respective TC users.

Replace the {{BaseURL}} with the one mentioned

POST {{BaseURL}}/v2/clients/{clientAccountId}/dynamic_call_records

Call Personalization Batch v2 Status

Each record indicates whether the record was successfully pushed or not.

Replace the {{BaseURL}} with the one mentioned here

GET {{BaseURL}}/v2/clients/{clientAccountId}/dynamic_call_records

{clientAccountId} : This can be taken directly from the self serve portal under the Manage API Keys Page

For Authorization Token kindly refer the section followed by API

Headers

Name

Value

Query Parameter

Name

Value

Type

Response

Details of Dynamic Label

This API is used to get the details of the Dynamic Labels created on the Truecaller

Replace the {{BaseURL}} with the one mentioned here

GET {{BaseURL}}/clients/{clientAccountId}/labels

{clientAccountId} This can be taken directly from the self serve portal under the Manage API Keys Page

For Authorization Token kindly refer the section followed by API

Headers

Name

Value

Response

Number Management

Businesses can efficiently automate the management of their Truecaller business numbers using our comprehensive Number Management APIs.

These APIs offer a robust set of features to streamline various tasks, including:

Listing Verified Numbers: Register and display your business numbers as verified on the Truecaller platform.
Delisting Numbers: Easily remove numbers that are no longer in use, ensuring accuracy and relevance.
Retrieving Verified Number Information: Access detailed information about your verified numbers.
Managing Feature Sets: Obtain Feature Set IDs to organise and control numbers within specific feature sets.

By leveraging these APIs, businesses can significantly simplify and automate their number ownership and management processes, ensuring that their Truecaller profiles are always accurate and up-to-date.

When you use our APIs to list or delist a number, these operations are asynchronous. This means they don't happen instantly; there's a processing period.

It's important to know that if you try to delist a number and then immediately list the same number while the delisting is still being processed (i.e., it hasn't been fully delisted or failed), your subsequent listing request for that number will be ignored. It won't be picked up for processing until the initial delisting action is complete.

List Number

This API is used to list the business numbers on the Truecaller Portal

Replace the {{BaseURL}} with the one mentioned here

The maximum limit to list is 10,000 numbers per feature set.

POST{{BaseURL}}/clients/{clientAccountId}/number_management/feature_sets/{featureSetId}/numbers/publish

{clientAccountId} : This can be taken directly from the self serve portal under the Manage API Keys Page

{featureSetId}: This can be taken directly from the feature set configuration page on the self serve portal

For Authorization Token kindly refer the section followed by API

Headers

Name

Value

Body

Name

Type

Validations

Description

Request

Response

DeList Number

This API is used to delist and remove business numbers from the client account and its feature-set.

Replace the {{BaseURL}} with the one mentioned

POST{{BaseURL}}/clients/{clientAccountId}/number_management/feature_sets/{featureSetId}/numbers/delist

Number details

This API is used to get meta-data of listed business numbers.

Replace the {{BaseURL}} with the one mentioned

GET{{BaseURL}}/clients/{clientAccountId}/number_management/numbers

Webhooks

To help you stay informed about events related to the features in your enterprise plan, you can easily configure Webhooks (also known as HTTP callbacks) directly on our Self-serve platform. This ensures your systems are automatically notified, keeping you seamlessly updated.

Webhooks are currently available for two key features: Call Me Back and User Feedback.

Should you wish to learn more about how webhooks can benefit your operations, please don't hesitate to contact us at: [email protected]. We'd be happy to assist you!

Webhook Configuration

A total of 5 webhooks can be configured under a customer account at a given point in time.

To configure your webhooks, simply follow these steps:

Access Webhook Management: Click on the overflow menu (usually represented by three dots or lines) and select "Manage Webhooks."
Create a New Webhook: Click on the "Create webhook" button to begin adding a new webhook.
Enter Webhook Details:
- Webhook Name: Provide a descriptive name for your webhook in the designated field. This name will be used to identify the webhook within the Truecaller for Business console. Please ensure the name is unique at any given time and does not exceed 50 characters.
- Webhook URL: Enter the endpoint to which Truecaller should send the webhook notifications. For enhanced security, you might consider including a self-generated key as part of your URL (e.g., https://server.yourcompany.com/tcbiz-webhook?key=<yourkey>
Select Event Type: Choose the specific type of webhook event you wish to receive notifications for. Currently, webhooks are available for Call Me Back and User Feedback events. Whenever a response occurs for these enabled features, we will capture it as an event and send it to your configured URL.
You can review event logs for your webhooks on both the "Manage Webhooks" page and the dedicated "Webhook events" page. Detailed information for each event is available on its respective event details page, with logs retained for the last 30 days.
Finalize Creation: Once all the required details are filled, click "Create." Your webhook will now be successfully set up.
Test Your Webhook : After creation, you can test your webhook to ensure it's functioning correctly.
- Click on "Test Webhook" next to an existing webhook.
- Select the event you wish to test (the default is "Call Me Back").

Update or Delete Webhook

Webhook should respond with status code 2XX and content type should be application/json along with json body

Event Types

We support Call Me Back and User Feedback events for webhooks. Each event has its resources that can be referred from the resource column.

Event

Event Trigger

Resources

Call me back

When a user requests a call me back from the Truecaller App in the scenario of a missed / rejected call

Type - Feature for which the webhook is being used.
Created At - Event creation time.
JSON content - Structure of payload data that is sent to the Business Client.

User Feedback

When a user responds to a campaign based on the type of call, answered or missed / rejected. This response is from the campaign on the Truecaller app.

Type: Feature for which the webhook is being used.
Created at: event creation time.
JSON content: structure of payload data that is sent to the business client.

Configure your systems to consume webhook response by assigning appropriate fields to the below scenarios :

Payload - Call Me Back

#For Customers with Slot Picker

Payload - User Feedback

Webhook Timeouts

Truecaller for Business implements three distinct timeouts for webhooks to ensure reliable and efficient delivery of notifications:

Connection Timeout: This timeout governs the duration allowed for establishing the initial connection to your webhook URL's HTTP server.
Read Timeout: Once the connection is successfully established, this timeout sets the maximum waiting period for reading data from the HTTP server at any point during the process.

Error scenarios for Webhooks

This page list the errors which we can encounter while using the webhooks.

There are 3 error scenarios for webhooks:

Webhook not found :For each webhook event triggered, we fetch the latest configuration of webhook ( this is needed in case if the webhook url is updated or the config is deleted). If config is deleted, we get webhook_not_found .
Events:

Call Reason Errors

You can find explanations for errors related to Call Reason in this section.

Invalid input: The issue is with the request payload. Please check if the request body is well-formed, the key names and values are as per the API documentation. Special characters, if any, are not allowed in the call reason. For more details on special characters, refer to this link.
Not a Truecaller user: The receiver is not a Truecaller user, or they might have uninstalled the app or switched to a new device that does not have Truecaller installed.
OS not supported: User is on an operating system other than Android. Please note that personalized call reason is only available for Android devices.
App version not supported: User is on a very old version of Android which is not supported now.
Failed to push: This is returned when system is unable to establish a connection with user's device. Reasons can include but are not limited to:
1. Out of network zone
2. Bad internet

Deprecated API's

This Page lists all the Deprecated API which should not be used for new customers.

Call Personalisation (Bulk)

Async API to send call personalisation data for a Caller-Receiver combination

Replace the {{BaseURL}} with the one mentioned here

POST {{BaseURL}}/clients/{clientAccountId}/dynamic_call_records

{clientAccountId} : This can be taken directly from the self serve portal under the Manage API Keys Page

Headers

Name

Value

Body

Name

Type

Validations

Description

Request

Response

API Rate Limits

Truecaller for Business restricts API requests when you exceed the limits entitled to your business.
Each token can handle 100 requests per second
Maximum of 10 tokens can be created in every 30 minutes

Batch Status

Fetch status of records for Batch-ID returned in the Bulk Call Personalisation API.

Replace the {{BaseURL}} with the one mentioned

GET {{BaseURL}}/clients/{clientAccountId}/dynamic_call_records

User Feedback

The User Feedback API helps you to download logs for User Feedback campaigns running on the numbers where this feature has been enabled

Replace the {{BaseURL}} with the one mentioned here

GET /clients/{clientAccountId}/openapi/feedback_stack/{surveyId}/export_report

{clientAccountId} : This can be taken directly from the self serve portal under the Manage API Keys Page

Headers

Name

Value

Query Parameter

Name

Type

Description

Response

Call Me Back

The Call Me Back API helps you to download Call Me Back requests for the numbers for which this feature has been enabled.

Replace the {{BaseURL}} with the one mentioned

GET /clients/{clientAccountId}/openapi/callback-logs/summary

{ "feature_sets": [ { "id": "069d2e3a-41e6-41f9-a768-157d7e3bd6b9", "name": "prio1", "description": "", "status": "draft", "process_id": "318d5ae4-d2ad-4dc6-898a-861347ce279d", "client_account_id": "91c173bb-28d8-4030-9722-8663ff9589f3", "label_id": "7c7ec202-96cc-4c5f-8b24-23cbc07a2a8a", "call_reason_id": "689f6ce5-c03d-4d96-8af8-c8fb9b52510d", "video_caller_id": null, "business_profile_id": null, "call_me_back": false, "survey": false, "department_id": "8e16b0d3-0953-40d0-9079-2a412363063e", "department_name": "QA Test new flow edit", "operation_id": "14349208-1e61-4f88-81c5-2f55dfc755db", "calling_operation_id": "690aa251-122e-4cbc-87a8-8d270fffb218", "calling_operation_name": "Delivery", "process_name": "newProcess", "sub_process_name": "subPro", "created_at": "2025-07-16T10:15:04.800203Z", "updated_at": "2025-07-16T10:15:04.800203Z" }, { "id": "684de058-3d09-4b05-ba65-3612b5cf616b", "name": "New Feature Set-7", "description": "", "status": "draft", "process_id": "510ab615-1dda-4cac-97f3-7975e10a4cd5", "client_account_id": "91c173bb-28d8-4030-9722-8663ff9589f3", "label_id": "7c7ec202-96cc-4c5f-8b24-23cbc07a2a8a", "call_reason_id": "f435f291-6508-4362-84bb-00100f008544", "video_caller_id": null, "business_profile_id": null, "call_me_back": false, "survey": false, "department_id": "85c87025-35e2-4e68-9257-0517609cfd3d", "department_name": "Listingdelisting", "operation_id": "358328f9-d99e-49ec-927e-28029efb0dde", "calling_operation_id": "0cb2cb40-8c23-44ce-b546-6d9b6b66af88", "calling_operation_name": "Sales", "process_name": "Listingdelisting", "sub_process_name": "", "created_at": "2025-07-16T10:12:24.561896Z", "updated_at": "2025-07-16T10:12:24.561896Z" } ], "pagination_info": { "total_page_count": 2, "current_page": 1, "page_limit": 50 } }

Verified Business APIs

Getting Started

hashtagAPI URLs to be used

Authentication

hashtagGenerate API Keys

Generate Access Token

Call Personalisation

hashtagHere are some use cases for Call Personalisation APIs:

hashtagPre-requisites for using Call Personalisation APIs:

hashtagIntegration steps:

hashtag.

hashtag

Call Personalisation Real-time v2

hashtagRequest

Call Personalisation Batch v2

Call Personalization Batch v2 Status

hashtagQuery Parameter

Details of Dynamic Label

Number Management

List Number

hashtagRequest

DeList Number

Number details

Webhooks

Webhook Configuration

hashtagUpdate or Delete Webhook

Event Types

hashtagPayload - User Feedback

Webhook Timeouts

Error scenarios for Webhooks

Call Reason Errors

Deprecated API's

Call Personalisation (Bulk)

hashtagRequest

Batch Status

User Feedback

Call Me Back

Webhooks

Deprecated API's

Authentication

hashtagGenerate API Keys

List Number

hashtagRequest

Getting Started

hashtagAPI URLs to be used

Event Types

hashtagPayload - User Feedback

Call Personalisation (Bulk)

hashtagRequest

DeList Number

Batch Status

Number Management

hashtagRequest

hashtagQuery Parameter

Call Personalisation Real-time v2

hashtagRequest

Webhook Configuration

hashtagUpdate or Delete Webhook

User Feedback

Call Reason Errors

Call Me Back

Webhook Timeouts

Call Personalisation

hashtagHere are some use cases for Call Personalisation APIs:

hashtagPre-requisites for using Call Personalisation APIs:

hashtagIntegration steps:

hashtag.

hashtag

Details of Dynamic Label

Number details

Generate Access Token

Error scenarios for Webhooks

hashtagCreate a dynamic label on Truecaller for Business console:

hashtagCheck the status of pushed records.

hashtagHit the dialer and place the call.

hashtagQuery Parameters

hashtagHeader

hashtagRequest

Call Personalization Batch v2 Status

hashtagQuery Parameter

API URLs to be used

Generate API Keys

Here are some use cases for Call Personalisation APIs:

Pre-requisites for using Call Personalisation APIs:

Integration steps:

.

Request

Query Parameter

Request

Update or Delete Webhook

Payload - User Feedback

Request

Generate API Keys

Request

API URLs to be used

Payload - User Feedback

Request

Request

Query Parameter

Request

Update or Delete Webhook

Here are some use cases for Call Personalisation APIs:

Pre-requisites for using Call Personalisation APIs:

Integration steps:

.

Create a dynamic label on Truecaller for Business console:

Check the status of pushed records.

Hit the dialer and place the call.

Query Parameters

Header

Request

Query Parameter

Request

Query Parameters

Header

Request