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
Base URL :
Note: The above URL is for API requests only.
The corresponding frontend web application URL where you can log in and verify the data is
This Page lists all the Deprecated API which should not be used for new customers.
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
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.
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.
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.
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!
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.
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
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:
Timeout
Duration
Connection Timeout
20,000 ms
Read Timeout
20,000 ms
Webhook Execution Timeout
60,000 ms
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:
Retry
Time
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
These details are mentioned in the webhook event page.
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
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:
Out of network zone
Bad internet
Call Personalisation Real-time v2
Real-time synchronous API to personalize calls for a given Caller-Receiver combination
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
Batch Status
Fetch status of records for Batch-ID returned in the Bulk Call Personalisation API.
Replace the {{BaseURL}} with the one mentioned here
{
"status_info": {
"status": "error",
"field": "ends_at",
"message": "Request body is invalid: ends_at cannot be older than current time"
}
}
).
Click "Test URL" to send a test notification.
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
batchId
Required
This is received from the Create Dynamic Call Records API response
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]
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 here
These dynamic label IDs need to be created in the Truecaller for Business console, after which the dynamic label ID can be copied from the Caller ID page in the console
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
limit
optional, Limit per page
integer
page
optional, Current page number
integer
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
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 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
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
