Skip to main content
POST
/
outbound
/
trigger
Trigger an outbound call
curl --request POST \
  --url https://api.example.com/outbound/trigger \
  --header 'Content-Type: <content-type>' \
  --header 'X-PolyAi-Auth-Token: <x-polyai-auth-token>' \
  --data '
{
  "to_number": "<string>",
  "country_code": "<string>",
  "encryption": "<string>",
  "metadata": {}
}
'
{
  "call_sid": "<string>"
}
Triggers a new outbound call to the specified phone number. The call will be queued and processed by the outbound calling system.

​
Request

​
Headers

​
X-PolyAi-Auth-Token
string
required
Connector authentication token for outbound calls
​
Content-Type
string
required
Must be application/json

​
Body

​
to_number
string
required
Phone number to call in E.164 format (e.g., +14155552671)
​
country_code
string
default:"ZZ"
ISO 3166-1 alpha-2 country code for phone number validation (e.g., US, GB, FR). Defaults to ZZ (unknown region).
​
encryption
string
default:"TLS/SRTP"
Encryption method for the call. Options: TLS/SRTP, UDP/RTP
​
metadata
object
Custom metadata to pass to the conversation. This data will be available in functions via conv.integration_attributes.
Metadata must be less than 26KB when base64-encoded. Larger payloads will be rejected.

​
Response

​
call_sid
string
Unique identifier for the triggered call. Use this to check call status.

​
Example

curl -X POST https://api.us-1.platform.polyai.app/outbound/trigger \
  -H "X-PolyAi-Auth-Token: YOUR_CONNECTOR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "to_number": "+14155552671",
    "country_code": "US",
    "metadata": {
      "customer_id": "12345",
      "appointment_time": "2024-03-15T10:00:00Z"
    }
  }'

​
Response example

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

​
Error responses

​
400 Bad Request
Invalid request parameters. Check phone number format and metadata size.
​
401 Unauthorized
Invalid or missing authentication token.
​
500 Internal Server Error
Failed to queue the outbound call. Retry with exponential backoff.

​
Notes

  • Phone numbers must be in E.164 format (international format with + prefix)
  • The country_code parameter helps validate the phone number format
  • Metadata is optional but useful for passing context to your conversation functions
  • The returned call_sid starts with OUT- to distinguish outbound calls
  • Use the Get call status endpoint to monitor call progress