Skip to main content
POST
Initiate an outbound call
Back to the Outbound Dialing API overview Places an outbound call through the given channel connection. Returns immediately once the call has been accepted for submission. This does not wait for the call to ring or connect. The response returns the outboundCallId, the initial phase (accepted), and the initiationState. The request needs the outbound_calls.initiate scope. Returns 201 on a genuinely new call. Repeating the exact same idempotencyKey and body returns 200 with the original call instead of placing a duplicate one. Reusing a key with a different body returns 409 IDEMPOTENCY_CONFLICT. The request requires channelConnectionId, to, and idempotencyKey. Set to to a phone number in E.164 format or to a SIP URI. Optional fields are clientReferenceId to correlate the call with your own records, amdMode (off, continue, or disconnect) for answering-machine detection, and sessionMetadata to attach to the session that starts when the call connects. A 502 error means the call could not be submitted to the telephony provider. If the error code is OUTBOUND_PROVIDER_REQUEST_UNKNOWN, check the call’s initiationState shortly after instead of resubmitting. To track the call, use Look up a call by ID or Events of outbound calls.

Authorizations

x-api-key
string
header
required

Project-bound Platform API key (abl_...). The key must carry outbound_calls.initiate for write operations (initiate, terminate) or outbound_calls.read for read operations (lookup, list, summary, search, event stream).

Path Parameters

projectSlug
string
required

The project's slug.

Minimum string length: 1
env
string
required

Deployment environment segment the call runs under, for example, production, staging, dev.

Minimum string length: 1

Body

application/json
channelConnectionId
string
required

The outbound-capable channel connection (telephony trunk/app) to place the call through.

Minimum string length: 1
to
object
required

Destination for the call — a phone number or a SIP URI.

idempotencyKey
string
required

Caller-supplied key. Repeating this exact request (same key + same body) returns the original call (200) instead of dialing again. The same key with a different body is rejected with 409 IDEMPOTENCY_CONFLICT.

Minimum string length: 1
clientReferenceId
string

Optional caller correlation id, echoed back on the call record and filterable via clientReferenceId.

Required string length: 1 - 256
amdMode
enum<string>

Answering-machine detection behavior. off=disabled, no AMD processing; continue=detect and report via amdResult, but let the call proceed regardless; disconnect=detect and automatically hang up on a machine.

Available options:
off,
continue,
disconnect
sessionMetadata
object

Optional arbitrary key/value metadata attached to the session that's created after the call connects.

Response

Idempotent replay — the original call for this idempotencyKey + body, returned unchanged.

success
boolean
required
data
object
required