Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
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.
This page provides the steps to generate the Key ID and Secret API Key.
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
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.
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.
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!
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}} with the one mentioned here
POST {{BaseURL}/clients/{clientAccountId}/token
{clientAccountId} : This can be taken directly from the self serve portal under the Manage API Keys Page
Headers
X-Public-Access
allow
Required
Body
api_key
string
Required API key from the Manage API Keys Page
key_id
string
Required Key ID from the Manage API Keys Page
{
"key_id": "aaaee1b1-7a2f-4c0b-8271-4e2b41c1bf01",
"api_key": "caf1694e-b8a4-4082-82fc-105a0a63eafe"
}Response
{
"token": "a4p0pZ2x3aEk9TYGxPZldm0qvWQknTXTINPZxNpIZ32yWmiOFtGqv2mEU7nJlQO6",
"created_at": "2025-07-10T06:59:05.72Z"
}{
"slug": "invalid-input",
"message": "api_key is required"
}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 personalized 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.
: Only “Dynamic Label IDs” can be used in the API request for placing calls.
A subscription to a package that includes Call Personalisation APIs.
Log in to the Truecaller for Business console.
Navigate to Business Identity in the left hand side panel.
Click on "Identity" and then go to the Caller ID Details section.
Click on "Create a Label".
Select the caller ID type as Dynamic Caller ID.
Add a logo for your dynamic caller ID. The logo should be a PNG file, with dimensions 200x200 and file size less than 2 MB.
Add a label name of less than 40 characters for your Dynamic Caller ID.
Choose the category for your business from the dropdown after creating a label name.
Click on "Create Caller ID' to finish creating your dynamic caller ID.
If your business is interested in knowing more about Call Personalisation APIs, please reach out to -> [email protected]
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 .
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:
Out of network zone
Bad internet
Airplane mode
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.
Fetch status of records for Batch-ID returned in the Bulk Call Personalisation API.
Replace the {{BaseURL}} with the one mentioned here
GET {{BaseURL}}/clients/{clientAccountId}/dynamic_call_records
{clientAccountId} This can be taken directly from the self serve portal under the Manage API Keys Page
batchId
Required
This is received from the Create Dynamic Call Records API response
Headers
Authorization
Required
Bearer <token>
Response
[
{
"id": "3ce1e19f-182d-4f04-ae28-422ca9f0bcd4",
"client_account_id": "91c173bb-28d8-4030-9722-8663ff9589f3",
"batch_id": "c951e498-abf3-4e50-ba94-a8065ca743f4",
"caller": "************",
"receiver": "************",
"label_id": "c6d86658-008d-4c08-98fb-2bf2649d59a5",
"label_name": "Flower",
"call_reason": "Flower Delivery",
"starts_at": 1752760800000,
"ends_at": 1752868800000,
"status": "success",
"created_at": "2025-07-17T08:52:55.383Z"
}
]{
"slug": "internal-server-error",
"message": "500/50011 - Failed to parse token"
}This Page lists all the Deprecated API which should not be used for new customers.
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 Authentication section followed by Generate Access Token API
Headers
Authorization
Required
Bearer <token>
Response
[
{
"id": "255297eb-7f13-44f9-967a-f287ff0f5025",
"name": "FlowerEra",
"logo_url": "https://business-priority-media-noneu.truecaller.com/staging/logos/06930f35-4b9c-4144-b748-9ace309c70d2-1751871235271177747.png",
"category": 10,
"sub_category": 142,
"created_by_email": "[email protected]",
"created_at": "2025-07-07T06:53:55.402122Z",
"label_type": "dynamic"
},
{
"id": "d3c2ff94-beb4-412f-a7d5-daebf9596cfa",
"name": "test-label-priority",
"logo_url": "https://business-priority-media-noneu.truecaller.com/staging/logos/06930f35-4b9c-4144-b748-9ace309c70d2-1739786448319894688.png",
"category": 1,
"sub_category": 16,
"created_by_email": "[email protected]",
"created_at": "2025-02-17T10:00:48.506685Z",
"label_type": "dynamic"
}
]{
"slug": "forbidden-error",
"message": "not authorized. please contact your admin."
}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").
Click "Test URL" to send a test notification.
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 Authentication section followed by Generate Access Token API
Headers
Content-Type
Required
application/json
Authorization
Required
Bearer <token>
batchId
Required
This is received from the Create Dynamic Call Records API response
string
Response
{
"client_account_id": "91c173bb-28d8-4030-9722-8663ff9589f3",
"batch_id": "0ca10281-11a0-4f86-bb27-7452da543cb6",
"data": [
{
"id": "c458227a-a730-4ced-81b4-19c21ea8d97c",
"caller_number": "************",
"receiver_number": "************",
"label_id": "c6d86658-008d-4c08-98fb-2bf2649d59a5",
"dynamic_label_name": "Centro Bank KYC Department",
"dynamic_call_reason": "Calling you for KYC Verification",
"starts_at": 1753246858000,
"ends_at": 1753362058000,
"status_info": {
"status": "success"
},
"created_at": "2025-07-23T09:07:32.21Z"
}
]
}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
Body
Response
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
Body
Response
Content-Type
Required
application/json
Authorization
Required
Bearer <token>
call_records
array of object
min:1 max: 500
Required Call record object Maximum batch size is 500 per API Call
dynamic_call_reason
string
minLength: 3 maxLength: 10
Optional
The call reason to be displayed.
caller_number
string
NA
Required The phone no. of the caller
ends_at
integer (int64)
Epoch timestamp in milliseconds
Required The timestamp in milliseconds at which dynamic caller ID should expire. Should not be before the current timestamp. starts_at and ends_at cannot be more than 24 hrs apart
label_id
string
NA
Optional The label ID of the dynamic label to be used as caller id
dynamic_label_name
string
minLength: 3 maxLength: 40
Required The caller ID name to be displayed. If not present it will default to the label name of the label ID provided.
receiver_number
string
NA
Required The phone no. of the receiver
starts_at
integer (int64)
Epoch timestamp in milliseconds
Required The timestamp in milliseconds at which dynamic caller ID should start reflecting.
starts_at and ends_at cannot be more than 24 hrs apart
{
"call_records":[
{
"label_id": "c6d86658-008d-4c08-98fb-2bf2649d59a5",
"dynamic_label_name": "Centro Bank KYC Department",
"dynamic_call_reason": "Calling you for KYC Verification",
"caller_number": "+91**********",
"receiver_number": "91**********",
"starts_at": 1753246858000,
"ends_at": 1753362058000
}
]
}{
"batch_id": "b72f7a40-ec3a-462f-b528-da0e8dc87e79"
}{
"slug": "authorization-error",
"message": "please login again"
}Content-Type
Required
application/json
Authorization
Required
Bearer <token>
phone_numbers
string
NA
Additionally, there’s a separate maximum limit associated with the client account ID.numbers to be added to feature set
{
"phone_numbers": [
"911234567891"
]
}{
"client_account_id": "91c173bb-28d8-4030-9722-8663ff9589f3",
"created_by_email": "[email protected]",
"phone_type": "verified",
"new_numbers": [
"911234567891"
],
"other_phonetype_numbers": [],
"existing_numbers": [],
"others_numbers": [],
"invalid_numbers": [],
"other_feature_set_numbers": [],
"status": "pending",
"migrated_numbers": [],
"delisted_numbers": [],
"updated_numbers": []
}{
"slug": "forbidden-error",
"message": "not authorized. please contact your admin."
}
This API is used to get feature-set ID to list and delist numbers.
Replace the {{BaseURL}} with the one mentioned here
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 Authentication section followed by Generate Access Token API
department_id
optional, to filter by department
string
operation_id
optional, to filter by operation
string
process_id
optional, to filter by process or subprocess
string
limit
optional, Limit per page
integer
page
optional, Current page number
integer
Authorization
Required
Bearer <token>
Response
{
"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
}
}{
"slug": "forbidden-error",
"message": "not authorized. please contact your admin."
}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 Authentication section followed by Generate Access Token API
Headers
Content-Type
Required
application/json
Authorization
Required
Bearer <token>
Body
dynamic_call_reason
string
minLength: 10 maxLength: 100
Optional.
The call reason to be displayed.
caller_number
string
Format Supported:"91**********"
Required The phone no. of the caller
ends_at
integer (int64)
Epoch timestamp in milliseconds
Required The timestamp in milliseconds at which dynamic caller ID should expire. Should not be before the current timestamp. starts_at and ends_at cannot be more than 24 hrs apart
label_id
string
NA
Optional The label ID of the dynamic label to be used as caller id
dynamic_label_name
string
minLength: 3 maxLength: 40
Required The caller ID name to be displayed. If not present it will default to the label name of the label ID provided.
receiver_number
string
NA
Required The phone no. of the receiver
starts_at
integer (int64)
Epoch timestamp in milliseconds
Required The timestamp in milliseconds at which dynamic caller ID should start reflecting.
starts_at and ends_at cannot be more than 24 hrs apart
{
"label_id": "c6d86658-008d-4c08-98fb-2bf2649d59a5",
"dynamic_label_name": "Flower rasm",
"dynamic_call_reason": "Flower Delivery",
"caller_number": "918861277591",
"receiver_number": "919035712806",
"starts_at": 1753088751000,
"ends_at": 1753103151000
}Response
{
"status_info": {
"status": "success",
"message": "Record processed successfully"
}
{
"status_info": {
"status": "error",
"field": "ends_at",
"message": "Request body is invalid: ends_at cannot be older than current time"
}
}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 here
POST{{BaseURL}}/clients/{clientAccountId}/number_management/feature_sets/{featureSetId}/numbers/delist
{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 Authentication section followed by Generate Access Token API
Headers
Content-Type
Required
application/json
Authorization
Required
Bearer <token>
Body
phone_numbers
string
minLength: 1 maxLength: 10000
Required.
List of phone numbers to be added to feature set
{
"phone_numbers": [
"911234567891"
]
}Response
{
"client_account_id": "91c173bb-28d8-4030-9722-8663ff9589f3",
"phone_type": "",
"processing_numbers": [],
"new_numbers": [],
"other_phonetype_numbers": [],
"existing_numbers": [
"911234567891"
],
"others_numbers": [],
"invalid_numbers": [],
"other_feature_set_numbers": [],
"status": "pending"
}{
"client_account_id": "91c173bb-28d8-4030-9722-8663ff9589f3",
"phone_type": "",
"processing_numbers": [],
"new_numbers": [
"911234567891"
],
"other_phonetype_numbers": [],
"existing_numbers": [],
"others_numbers": [],
"invalid_numbers": [],
"other_feature_set_numbers": [],
"status": "failed"
}We support Call Me Back and User Feedback events for webhooks. Each event has its resources that can be referred from the resource column.
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
Body
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
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.
// For Customers with Slot Picker - Scenario 1
// Happy Flow
{
"event_id": "860a7f4c-6545-40f1-85be-3655edde650f",
"client_account_id": "91c173bb-28d8-4030-9722-8663ff9589f3",
"event_type": "cmb",
"created_at": "1753945760",
"cmb_payload": {
"business_number": "910987654321",
"feature_set": "Fresh Flower Delivery",
"client_number": "911234567890",
"requested_at": "1753945760",
"requested_date": "2025-08-02",
"requested_slot": "Saturday",
"preferred_from_time": "1754116200",
"preferred_to_time": "1754118000",
"is_interested": true,
"alternate_number": ""
}
}// For Customers with Slot Picker - Scenario 2
// SIMinfo related issues on device
{
"event_id": "119be0c3-d23f-4728-8e42-d936c2e8dad6",
"client_account_id": "91c173bb-28d8-4030-9722-8663ff9589f3",
"event_type": "cmb",
"created_at": "1753945773",
"cmb_payload": {
"business_number": "910987654321",
"feature_set": "cmb",
"client_number": "Phone number not available",
"requested_at": "1753945773",
"requested_date": "31 July 2025",
"requested_slot": "Friday",
"preferred_from_time": "1754031600",
"preferred_to_time": "1754033400",
"is_interested": true,
"alternate_number": "918047360788"
}
}// For Customers with Slot Picker - Scenario 3
// Customers who are Not Interested
{
"event_id": "119be0c3-d23f-4728-8e42-d936c2e8dad6",
"client_account_id": "91c173bb-28d8-4030-9722-8663ff9589f3",
"event_type": "cmb",
"created_at": "1753945773",
"cmb_payload": {
"business_number": "910987654321",
"feature_set": "cmb",
"client_number": "Phone number not available",
"requested_at": "1753945773",
"requested_date": "31 July 2025",
"requested_slot": "Friday",
"preferred_from_time": "1754031600",
"preferred_to_time": "1754033400",
"is_interested": false,
"alternate_number": "918047360788"
}
}// For Customers without Slot Picker
{
"event_id": "119be0c3-d23f-4728-8e42-d936c2e8dad6",
"client_account_id": "91c173bb-28d8-4030-9722-8663ff9589f3",
"event_type": "cmb",
"created_at": "1753945773",
"cmb_payload": {
"business_number": "910987654321",
"feature_set": "cmb",
"client_number": "Phone number not available",
"requested_at": "1753945773",
"requested_date": "31 July 2025",
"requested_slot": "Friday",
"preferred_from_time":null,
"preferred_to_time": null,
"is_interested": true,
"alternate_number": "918067676878"
}
}{
"event_id": "7719f451-5436-470a-98ba-422b997582f8",
"client_account_id": "91c173bb-28d8-4030-9722-8663ff9589f3",
"event_type": "user_feedback",
"created_at": "1753946877",
"survey_payload": {
"name": "Flower Quality Check",
"business_number": "+910987654321",
"feature_set": "Fresh Flower Delivery",
"client_number": "911234567890",
"requested_at": "1753946877",
"user_responses": [
{
"question": "How was the delivery experience?",
"response": "5"
},
{
"question": "Flower Quality?",
"response": "Good"
}
]
}
}Content-Type
Required
application/json
Authorization
Required
Bearer <token>
call_reason
string
minLength: 3 maxLength: 10
Optional.
The call reason to be displayed.
caller
string
Format Supported:"91**********"
Caller number should be without the “+” character.
Required The phone no. of the caller
ends_at
integer (int64)
NA
Required The timestamp in milliseconds at which dynamic caller ID should expire. Should not be before the current timestamp. starts_at and ends_at cannot be more than 24 hrs apart
label_id
string
NA
Optional The label ID of the dynamic label to be used as caller id
label_name
string
minLength: 3 maxLength: 40
Required The caller ID name to be displayed. If not present it will default to the label name of the label ID provided.
receiver
string
Format Supported:"91**********" Receiver number should be without the “+” character.
Required The phone no. of the receiver
starts_at
integer (int64)
NA
Required The timestamp in milliseconds at which dynamic caller ID should start reflecting.
starts_at and ends_at cannot be more than 24 hrs apart
{
"status": "success",
"message": "Records Uploaded Successfully. BatchID: 6dabe53b-14a5-44bf-9bab-3dda8b0fee54"
}{
"status": "failure",
"message": "ends_at cannot be older than current time. BatchID: d30ca8f7-ae64-4c30-8700-d63f6b2f1dd6"
}{
"slug": "authorization-error",
"message": "Missing authorization header"
}{
"call_reason": "Flower Delivery",
"caller": "91**********",
"ends_at":1751886000000,
"label_id": "255297eb-7f13-44f9-967a-f287ff0f5025",
"label_name": "Delivery",
"receiver": "91**********",
"starts_at": 1751879424883
}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 here
GET /clients/{clientAccountId}/openapi/callback-logs/summary
{clientAccountId} : This can be taken directly from the self serve portal under the Manage API Keys Page
Headers
Authorization
Required
Bearer <token>
Query Parameter
from
string
Required Start time in milliseconds
to
string
Required End time in milliseconds
Response
API NOT WORKING{
"message": "No CMB found for client Id"
}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
Authorization
Required
Bearer <token>
Query Parameter
from_date
string
Required
Response
API NOT WORKING{
"message": "No CMB found for client Id"
}This API is used to get meta-data of listed business numbers.
Replace the {{BaseURL}} with the one mentioned here
GET{{BaseURL}}/clients/{clientAccountId}/number_management/numbers
{clientAccountId} : This can be taken directly from the self serve portal under the Manage API Keys Page
department_id
optional, to filter by department
string
operation_id
optional, to filter by operation
string
process_id
optional, to filter by process or subprocess
string
feature_set_id
optional, to filter by feature set
string
limit
optional, Limit per page
integer
page
optional, Current page number
integer
For Authorization Token kindly refer the Authentication section followed by Generate Access Token API
Authorization
Required
Bearer <token>
Response
{
"numbers": [
{
"phone_number": "918848628575230",
"phone_type": "verified",
"status": "listed",
"client_account_id": "91c173bb-28d8-4030-9722-8663ff9589f3",
"created_by_email": "[email protected]",
"department": "TestingSanity",
"operation": "Collections",
"process": "SanityProcess",
"subprocess": "",
"feature_set_name": "New Feature set",
"call_me_back": "enabled",
"created_at": "2025-07-28T09:25:19.557139Z",
"updated_at": "2025-07-28T09:25:23.644159Z",
"label_name": "testLabel from fs page"
},
{
"phone_number": "918735783247237",
"phone_type": "verified",
"status": "listed",
"client_account_id": "91c173bb-28d8-4030-9722-8663ff9589f3",
"created_by_email": "[email protected]",
"department": "TestingSanity",
"operation": "Collections",
"process": "SanityProcess",
"subprocess": "",
"feature_set_name": "New Feature set",
"call_me_back": "enabled",
"created_at": "2025-07-28T09:25:19.557139Z",
"updated_at": "2025-07-28T09:25:23.671083Z",
"label_name": "testLabel from fs page"
}
],
"pagination_information": {
"total_page_count": 8
}
}{
"client_account_id": "91c173bb-28d8-4030-9722-8663ff9589f3",
"phone_type": "",
"processing_numbers": [],
"new_numbers": [
"911234567891"
],
"other_phonetype_numbers": [],
"existing_numbers": [],
"others_numbers": [],
"invalid_numbers": [],
"other_feature_set_numbers": [],
"status": "failed"
}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
Body
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
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.
Total Webhook Timeout: Beyond the connection and read timeouts, Truecaller for Business also enforces a comprehensive timeout that limits the total execution time for any single webhook call.
The values for each timeout are as follows:
Webhook execution can fail due to timeouts or errors. For each event where webhook call fails, the calls are retried up to 7 times based on the following schedules:
These details are mentioned in the webhook event page.
Content-Type
Required
application/json
Authorization
Required
Bearer <token>
call_records
object
NA
Call Record object
call_reason
string
minLength: 3 maxLength: 10
Optional
The call reason to be displayed.
caller
string
Format Supported:"91**********"
Caller number should be without the “+” character.
Required The phone no. of the caller
ends_at
integer (int64)
NA
Required The timestamp in milliseconds at which dynamic caller ID should expire. Should not be before the current timestamp. starts_at and ends_at cannot be more than 24 hrs apart
label_id
string
NA
Optional The label ID of the dynamic label to be used as caller id
label_name
string
minLength: 3 maxLength: 40
Required The caller ID name to be displayed. If not present it will default to the label name of the label ID provided.
receiver
string
Format Supported:"91**********" Receiver number should be without the “+” character.
Required The phone no. of the receiver
starts_at
integer (int64)
NA
Required The timestamp in milliseconds at which dynamic caller ID should start reflecting.
starts_at and ends_at cannot be more than 24 hrs apart
{
"status": "success",
"message": "Records Uploaded Successfully. BatchID: 6dabe53b-14a5-44bf-9bab-3dda8b0fee54"
}{
"status": "failure",
"message": "ends_at cannot be older than current time. BatchID: d30ca8f7-ae64-4c30-8700-d63f6b2f1dd6"
}{
"slug": "authorization-error",
"message": "please login again"
}{
"call_records": [
{
"call_reason": "Flower Delivery",
"caller": "**********",
"ends_at": 2,
"label_id": "255297eb-7f13-44f9-967a-f287ff0f5025",
"label_name": "Flower",
"receiver": "**********",
"starts_at": 1
}
]
}Connection Timeout
20,000 ms
Read Timeout
20,000 ms
Webhook Execution Timeout
60,000 ms
1
2 minutes after the failure
2
6 minutes after the previous retry
3
30 minutes after the previous retry
4
1 hour after the previous retry
5
5 hours after the previous retry
6
1 day after the previous retry
7
2 days after the previous retry
