Trigger an outbound call

Initiate an outbound call to a phone number

POST /v1/outbound-calling

Trigger an outbound call

cURL

curl --request POST \
  --url https://api.example.com/v1/outbound-calling \
  --header 'Content-Type: <content-type>' \
  --header 'X-PolyAi-Auth-Token: <x-polyai-auth-token>' \
  --data '
{
  "to_number": "<string>",
  "country_code": "<string>",
  "metadata": {},
  "encryption": "<string>"
}
'

200

{
  "call_sid": "<string>"
}

Triggers a new outbound call to the specified phone number. When the request is accepted, the call is placed close to immediately.

The API should only be called to make a call. The call is always attempted, and the start tool (start_function) is executed after the call connects.

It is your responsibility to ensure that calls are placed in compliance with applicable laws and regulations.

Request

Headers

X-PolyAi-Auth-Token · string · required

Authentication token provided by your PolyAI representative

Content-Type · string · required

Must be application/json

Body

to_number · string · required

Phone number to call. Provide it in E.164 format (e.g., [phone]), or supply country_code and pass a national-format number for that country.

country_code · string

Optional ISO 3166-1 alpha-2 country code (e.g., US, GB) used to parse a non-E.164 to_number. Leave unset when to_number is already in E.164 format.

metadata · object

Arbitrary key/value pairs to attach to the call. All values must be strings. The base64 representation of the metadata must be less than 26 KB.

Each key is delivered to the agent as a SIP header and can be read inside start_function (or any tool) with:

conv.sip_headers.get('key_name')

encryption · string · default: "TLS/SRTP"

Telephony encryption type for the outbound leg. One of:

• TLS/SRTP (default)
• TLS/RTP
• UDP/SRTP
• UDP/RTP

Response

call_sid · string

Unique identifier for the triggered call. Always prefixed with OUT-. Use this to check call status.

Example

cURL

curl -X POST https://api.us-1.platform.polyai.app/v1/outbound-calling \
  -H "X-PolyAi-Auth-Token: YOUR_AUTH_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "to_number": "[phone]",
    "metadata": {
      "patient_first_name": "Paul",
      "patient_last_name": "Glynn",
      "patient_dob": "1981-August-26",
      "referred_by_name": "Dr. Alex Deerman",
      "variant": "Inpatient at St Charles",
      "patient_address_street": "13 Main Street",
      "patient_city_state": "Colonia, New Jersey",
      "patient_zip_code": "07676"
    }
  }'

Response example

{
  "call_sid": "OUT-550e8400-e29b-41d4-a716-446655440000"
}

Error responses

400 Bad Request

Invalid request parameters – for example, an unparseable to_number, a metadata value that isn’t a string, or metadata that exceeds the 26 KB base64 size limit.

401 Unauthorized

Invalid or missing authentication token, or the connector behind the token is not configured for outbound calling.

500 Internal Server Error

Failed to place the outbound call. Retry with exponential backoff.

Notes

• Phone numbers must be in E.164 format unless you also pass country_code.
• All metadata values must be strings; nested objects, numbers, and booleans are rejected.
• Use the Get call status endpoint to monitor call progress.
• Call status data is retained for approximately 2 hours after the call ends.