Sign in

v2

latestOpenAPI 3.1.02026-08-075421692.0 MB
Voice

Place an outbound phone call

Dials to FROM one of your voice-enabled numbers and, on answer, bridges the callee to the number's stored forward destination, or to the per-call forwardTo override. Destinations can be your own AI voice agent (Vapi/Retell), a phone, or a SIP endpoint. An optional greeting is spoken to the callee before the bridge.

The 200 response means the call is dialing; the lifecycle continues asynchronously (track it via GET /v1/voice/calls/{id} or the call.* webhooks). Outbound calls are capped per rolling hour (429 when hit).

Idempotency: send an Idempotency-Key header to make retries safe; same key + same body replays the original response instead of dialing (and billing) a second call.

post/v1/voice/calls

Headers

Idempotency-Keystring

Optional client-generated unique key (e.g. a UUID) that makes retries safe. Same key + same body replays the original response; same key + different body → 422; key still processing → 409.

Request body

tostring required

Destination to dial, E.164 with leading +.

fromNumberstring

Which of your voice-enabled numbers to dial from. Optional when you have exactly one.

forwardTostring

Per-call agent override (tel:+E164, sip:..., or wss://...); defaults to the number's stored forward destination.

greetingstring

Spoken to the callee when they answer, before the bridge.

recordOverrideboolean

Per-call recording toggle; defaults to the number's setting.

transcribeOverrideboolean

Per-call transcription toggle; defaults to the number's setting.

transcriptionLanguage'auto' | 'en' | 'es'

'auto' derives from the callee's country; 'en'/'es' force it.

amdboolean

Answering-machine detection; defers the bridge until human vs machine is known.

voicemailDropMessagestring

Spoken to a detected machine, then hang up (implies amd). For outbound voicemail drops.

Response

Call originated; lifecycle continues asynchronously.

successboolean
callIdstring

Internal Call doc ID

telnyxCallControlIdstring
status'dialing'
direction'outbound'
fromstring
tostring
forwardTostring
greetingstring nullable
recordingEnabledboolean
transcriptionEnabledboolean
transcriptionLanguage'auto' | 'en' | 'es'