REST APICalls

Place an AI voice call

View as Markdown
Places an outbound voice call handled by an AI voice agent using the supplied instruction. Supports idempotent retries via the optional `Idempotency-Key` header: replaying the same key returns the original call (`200`) instead of dialing again, and a duplicate that arrives while the original is still processing waits for it. A non-2xx response guarantees no live call: if the call already fired when the failure happened, Dial cancels it before responding. Without the header the request is not idempotent — retrying can place a duplicate call; on an ambiguous failure, confirm via List calls before retrying. Choose the from-number with exactly one of `fromNumber` (phone-number ID, one of your numbers in E.164 format, or a nickname) or the legacy `fromNumberId` (ID only) — both, or neither, is rejected with `400`.

Authentication

AuthorizationBearer

Your Dial API key, sent as Authorization: Bearer sk_live_...

Headers

Idempotency-KeystringOptional<=255 characters

A unique client-generated key (e.g. a UUID) identifying this call attempt. Reuse the same key when retrying a failed or ambiguous request: if the original attempt placed the call, the retry returns that call with 200 instead of placing a second one. Keys are scoped to your account.

Request

This endpoint expects an object.
tostringRequired
Recipient phone number in E.164 format.
outboundInstructionstringRequired
System prompt for the AI voice agent during the call.
fromNumberstringOptional

The Dial number to call from, referenced flexibly: a phone-number ID, one of your numbers in E.164 format, or a number’s nickname. A nickname shared by more than one of your numbers is rejected with 400. Provide exactly one of fromNumber or fromNumberId.

fromNumberIdstringOptional

ID of the Dial number to call from. Legacy alternative to fromNumber — provide exactly one of the two.

languagestringOptional

BCP-47 language tag for the voice agent. Optional — when omitted, Dial detects the language from the destination number’s country prefix and the agent handles both that language and en-US. Pass an explicit tag to pin the call to a single language.

maxCallDurationSecondsintegerOptional60-3600
Optional per-call cap on this call's length, in seconds. Highest priority: when set it is the effective cap, overriding the number and account caps (it can raise or lower the limit). Must be between 60 and 3600 seconds (1 minute to 1 hour); a value outside that range returns 400. Omit to fall back to the number cap, then the account cap, then the global default. When a cap is active, Dial automatically injects a warning to the agent ~40 seconds before the hard cut, prompting it to wrap up naturally.
voiceGenderenumOptional

Gender of the AI voice agent for this call. Optional — when omitted, the voice is female (the default for every language). Pass male or female to choose explicitly; the choice also tells the agent how to refer to itself in gendered languages.

Allowed values:
transferTostringOptional

Forward-to number in E.164 format. Optional — when set, the agent waits for a real human (riding out hold music and IVR menus) and then cold-transfers the call to this number. Must differ from both to and the call’s from number. When the hand-off occurs, the call’s transferredAt is stamped.

Response

A call with this Idempotency-Key was already placed — returns the original call instead of dialing again.

callobject

Errors

400
Bad Request Error
401
Unauthorized Error
402
Payment Required Error
404
Not Found Error
409
Conflict Error