Create Outbound Call | SpeechifyAI API

Place an outbound call from an agent to a phone number. LiveKit originates the SIP INVITE through the outbound trunk bound to the agent’s workspace; the agent is dispatched into the call automatically.

The response is returned as soon as LiveKit accepts the INVITE. Poll GET /v1/agents/conversations/{conversation_id} for status transitions: pending → active (answered) → completed.

Requires a Twilio or BYOC trunk. LiveKit-native numbers are inbound-only.

Place an outbound call from an agent to a phone number. LiveKit originates the SIP INVITE through the outbound trunk bound to the agent's workspace; the agent is dispatched into the call automatically. The response is returned as soon as LiveKit accepts the INVITE. Poll `GET /v1/agents/conversations/{conversation_id}` for status transitions: `pending` → `active` (answered) → `completed`. Requires a Twilio or BYOC trunk. LiveKit-native numbers are inbound-only.

Authentication

AuthorizationBearer

Enter your API key with the Bearer prefix, e.g. ‘Bearer sk_…’.

Headers

Idempotency-KeystringOptional<=255 characters

A client-generated key (an opaque string, max 255 chars) that makes a side-effect POST safe to retry: the server runs the operation exactly once and replays the first response (its status and body) for 24 hours. Reusing a key with a different request body, or while the first request is still in flight, returns 409 idempotency_conflict. A replayed response carries the Idempotent-Replayed: true header.

A client-generated key (an opaque string, max 255 chars) that makes a side-effect POST safe to retry: the server runs the operation exactly once and replays the first response (its status and body) for 24 hours. Reusing a key with a different request body, or while the first request is still in flight, returns `409 idempotency_conflict`. A replayed response carries the `Idempotent-Replayed: true` header.

Request

This endpoint expects an object.

agent_idstringRequired

ID of the agent that handles the answered call.

tostringRequired

Destination phone number in E.164 format (e.g. +12025559876).

caller_id_numberstringOptional

The number shown to the callee as caller ID, in E.164 format. Defaults to the first outbound-capable number in the workspace. Useful for multi-number campaigns where you want to rotate caller IDs.

dtmf_prefixstringOptional

DTMF digits dialed automatically after the call is answered, before the agent begins speaking. Use this for IVR navigation (e.g. 1ww2 presses 1, waits two seconds, presses 2). w is a half-second pause; W is a one-second pause.

dynamic_variablesmap from strings to anyOptional

Per-call variable overrides merged on top of the agent’s stored defaults. Keys must not use the reserved system__ prefix. Useful for injecting per-call context (customer name, order ID) into the agent prompt.

ringing_timeout_msintegerOptional

How long to wait for the callee to answer before abandoning, in milliseconds. Defaults to 30000 (30s). Capped at 80000 (80s).

amdobjectOptional

Optional per-call override for the AMD routing config. When set, wholesale-replaces the agent’s stored AMD shape for this single call (PATCH-replace, not merge). Unlocks the batch-campaign pattern: one agent dialling many recipients with per-row tailored voicemail messages via the existing dynamic_variables substitution. Validation rules match the agent-update boundary.

Response headers

X-Request-IDstring

Unique identifier for this request, present on every response (2xx and non-2xx alike). If the caller sends an X-Request-ID request header the server echoes it back (sanitized and length-capped) so one logical request can be traced end-to-end; otherwise the server generates a fresh value. Log it on every response and quote it in support requests - it is the stable handle that ties your observation to Speechify’s server-side logs, and it matches the request_id field in the error envelope.

Unique identifier for this request, present on every response (2xx and non-2xx alike). If the caller sends an `X-Request-ID` request header the server echoes it back (sanitized and length-capped) so one logical request can be traced end-to-end; otherwise the server generates a fresh value. Log it on every response and quote it in support requests - it is the stable handle that ties your observation to Speechify's server-side logs, and it matches the `request_id` field in the error envelope.

RateLimit-Limit-Callsinteger

Active-call concurrency budget: the per-workspace cap on simultaneously-active voice calls (the voice analog of a token axis). Sent on successful call-start responses (web session, outbound call).

RateLimit-Remaining-Callsinteger

Active-call concurrency budget: free active-call slots after this call reserved one. 0 on a 429 that rejected for concurrency exhaustion (concurrency_limit_reached).

Response

The outbound call was accepted by LiveKit.

conversation_idstringformat: "^conv_[0-9a-hjkmnp-tv-z]{26}$"

ID of the conversation created for this call. Use to poll status.

Errors

400

Bad Request Error

401

Unauthorized Error

402

Payment Required Error

403

Forbidden Error

404

Not Found Error

409

Conflict Error

502

Bad Gateway Error

$	curl -X POST https://api.speechify.ai/v1/agents/outbound-calls \
>	-H "Authorization: Bearer <token>" \
>	-H "Content-Type: application/json" \
>	-d '{
>	"agent_id": "agent_01HS...",
>	"to": "+41791234567",
>	"caller_id_number": "+12025551234"
>	}'