Trigger an outbound call - PolyAI Platform

curl --request POST \ --url https://api.us.poly.ai/v1/agents/{agentId}/telephony/outbound-calls \ --header 'Content-Type: application/json' \ --header 'X-API-KEY: <api-key>' \ --data ' { "toNumber": "+442012345678", "environment": "live", "countryCode": "GB", "variantId": "<string>", "encryption": "tls_srtp", "metadata": { "customer_name": "Paul Smith", "appointment_date": "2026-08-26" } } '

Authorizations

X-API-KEY

string

header

required

Path Parameters

agentId

string

required

Body

application/json

toNumber

string

required

Phone number to dial in E.164 format (e.g. +442012345678). If the number lacks a country prefix, also supply countryCode.

Example:

"+442012345678"

environment

enum<string>

required

Target environment for the call.

Available options:

sandbox,

pre-release,

live

Example:

"live"

countryCode

string

ISO 3166-1 alpha-2 country code (e.g. GB) for parsing a non-E.164 toNumber.

Example:

"GB"

variantId

string

Variant ID to use for the call. If omitted, the default connector for the environment is used.

encryption

string

default:tls_srtp

Telephony encryption mode for the outbound leg.

Example:

"tls_srtp"

metadata

object

Arbitrary key/value pairs delivered to the agent as SIP headers. All values must be strings. The base64 representation must be under 26 KB.

Show child attributes

Example:

{
  "customer_name": "Paul Smith",
  "appointment_date": "2026-08-26"
}

Response

Call accepted and queued.

callSid

string

Unique call identifier (prefixed with OUT-). Use this to poll status.

Example:

"OUT-550e8400-e29b-41d4-a716-446655440000"

status

string

Initial call status.

Example:

"QUEUED"