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.

Authentication

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

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.

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

POST {{BaseURL}/clients/{clientAccountId}/token

Headers

Name

Value

Description

Call Personalisation

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.

Call Personalisation Real-time v2

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

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

Headers

Name

Value

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

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

This API can handle 60 requests per minute per token.

For Authorization Token kindly refer the section followed by API

Headers

Name

Value

Body

Name

Type

Validations

Description

Response

Call Personalization Batch v2 Status

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

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

Headers

Name

Value

Details of Dynamic Label

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

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

Headers

Name

Value

List Number

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

Replace the {{BaseURL}} with the one mentioned

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

Response

DeList Number

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

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

Headers

Name

Value

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

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

Query Parameters

Name

Value

Type

department_id

Name

Value

Response

Feature-set ID

This API is used to get feature-set ID to list and delist numbers.

Replace the {{BaseURL}} with the one mentioned

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

{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

Query Parameters

Name

Value

Type

department_id

Name

Value

Response

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: cs@truecaller.com. We'd be happy to assist you!

Webhook Configuration

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.

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.

The values for each timeout are as follows:

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:
- Rescheduled error: This state of the event occurs when we are unable to send webhook request ( i.e. we didnt get 200 OK response ) in first attempt, retry logic kicks in.
- Webhook Deleted: Webhook config is deleted.
Webhook Failed: We retry webhook events 7 times, if none of the attempts are successful, admins receive failure email.

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 Real-time API

Sync API to send call personalisation data for a Caller-Receiver combination. This is a real-time API

Replace the {{BaseURL}} with the one mentioned

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

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

Headers

Name

Value

Content-Type

Body

Name

Type

Validations

Description

Response

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

Call Personalisation (Bulk)

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

Replace the {{BaseURL}} with the one mentioned

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

Content-Type

Body

Name

Type

Validations

Description

Response

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.

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

Name

Value

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

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

Headers

Name

Value

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.

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

Headers

Name

Value

{ "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

Authentication

Generate Access Token

Call Personalisation

Call Personalisation Real-time v2

Call Personalisation Batch v2

Call Personalization Batch v2 Status

Details of Dynamic Label

List Number

DeList Number

Number details

Query Parameters

Feature-set ID

Query Parameters

Webhooks

Webhook Configuration

Webhook Timeouts

Error scenarios for Webhooks

Call Reason Errors

Deprecated API's

Call Personalisation Real-time API

Call Personalisation (Bulk)

Batch Status

User Feedback

Call Me Back

Call Personalisation Batch v2

Getting Started

Authentication

Generate Access Token

API URLs to be used

Request

Generate API Keys

Request

Call Personalisation

Call Personalization Batch v2 Status

Details of Dynamic Label

Query Parameter

.

.

Create a dynamic label on Truecaller for Business console:

Here are some use cases for Call Personalisation APIs:

Pre-requisites for using Call Personalisation APIs:

Integration steps:

Check the status of pushed records.

Hit the dialer and place the call.

Deprecated API's

Webhooks

Error scenarios for Webhooks

Call Reason Errors

Batch Status

User Feedback

Webhook Configuration

Call Me Back

Webhook Timeouts

Query Parameter

Update or Delete Webhook

List Number

DeList Number

Call Personalisation Real-time v2

Request

Request

Request

Number details

Query Parameters

Feature-set ID

Query Parameters

Call Personalisation (Bulk)

Call Personalisation Real-time API

Header

Header

Request

Request

Event Types

Payload - User Feedback

Number Management