Sign in

v1

latestOpenAPI 3.1.02026-07-2687120159.0 KB
Outbound Calls

Trigger an outbound call

Triggers the PolyAI voice agent to dial a phone number. The agent will call the provided number and conduct the conversation autonomously. Returns a callSid that can be used to poll status.

post/v1/agents/{agentId}/telephony/outbound-calls

Request body

toNumberstring required

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

environment'sandbox' | 'pre-release' | 'live' required

Target environment for the call.

countryCodestring

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

variantIdstring

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

encryptionstring

Telephony encryption mode for the outbound leg.

metadataobject

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

Example request

{
  "toNumber": "+442012345678",
  "environment": "live",
  "countryCode": "GB",
  "encryption": "tls_srtp",
  "metadata": {
    "customer_name": "Paul Smith",
    "appointment_date": "2026-08-26"
  }
}

Response

Call accepted and queued.

callSidstring

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

statusstring

Initial call status.

Example response

{
  "callSid": "OUT-550e8400-e29b-41d4-a716-446655440000",
  "status": "QUEUED"
}