Skip to main content
POST
Trigger Click-to-Dial Call
Initiate an outbound click-to-dial call that connects a customer’s number to your agent’s phone. The system first rings the customer’s phone (client_number) and, once answered, bridges the call to the agent (user_number). The customer sees the did_number as the incoming caller ID.

API Endpoint

POST /api/v1/global/click-to-dial Content-Type: application/json Authentication: Required (Token header: token or api_access_token)

Request Body

Required Fields

FieldTypeDescription
client_numberstringThe customer’s phone number to dial (the callee). This number is rung first. Country code prefixes are normalized automatically, e.g. +919876543210 and 9876543210 are treated as the same number
user_numberstringThe calling agent’s own phone number. The call is bridged to this number once the customer answers
did_numberstringThe DID to display as the caller ID. Must be an active DID owned by your workspace

Optional Fields

FieldTypeDescription
app_idintegerID of the app to associate this call with, used for tracking and for filtering call history
object_idintegerID of the record/object this call relates to (tracking metadata)
submitted_idstringSubmission identifier to associate with this call (tracking metadata)
slugstringField slug to associate with the dialled number (tracking metadata)

Success Response

Status Code: 200 OK

Response Fields

FieldTypeDescription
call_idstringUnique identifier for this call. Use it to correlate the call with entries returned by the call history endpoint
client_numberstringThe normalized customer number that was dialled
caller_idstringThe DID displayed to the customer as the caller ID
user_numberstringThe agent number the call was bridged to

Error Responses

All errors are returned in a common envelope. Always check the error field of the response body.

422 Unprocessable Entity

MessageCause
Invalid client numberclient_number is empty or not a valid phone number
Invalid user numberuser_number is empty
Invalid DID numberdid_number is empty
This number does not belong to your account, kindly buy itThe did_number is not an active DID on your workspace. Purchase the DID or use one you own
Failed to dial the callThe telephony provider could not place the call. Retry, or contact support if it persists

401 Unauthorized

Example Request

Important Notes

DID Ownership

  • The did_number must be a DID (phone number) that is already purchased and active on your workspace
  • Calls with a DID you do not own are rejected with This number does not belong to your account, kindly buy it

Call Flow

  1. The customer’s phone (client_number) rings first
  2. Once the customer answers, the call is bridged to the agent (user_number)
  3. The customer sees the did_number as the incoming caller ID

Phone Number Format

  • Country code prefixes are normalized automatically, so +919876543210 and 9876543210 are treated as the same number
  • It is still recommended to include the country code with the + prefix

Call Tracking

  • Store the call_id returned in the response for tracking purposes
  • Use the optional app_id, object_id, submitted_id, and slug fields to attach tracking metadata to the call
  • Calls triggered with an app_id can later be filtered in the call history endpoint

Headers

token
string
required

API token for authentication

Body

application/json
client_number
string
required

The customer's phone number to dial (the callee). This number is rung first. Country code prefixes are normalized automatically

user_number
string
required

The calling agent's own phone number. The call is bridged to this number once the customer answers

did_number
string
required

The DID to display as the caller ID. Must be an active DID owned by your workspace

app_id
integer

ID of the app to associate this call with, used for tracking and filtering call history

object_id
integer

ID of the record/object this call relates to (tracking metadata)

submitted_id
string

Submission identifier to associate with this call (tracking metadata)

slug
string

Field slug to associate with the dialled number (tracking metadata)

Response

Call dialled successfully

data
object
message
string