v4

OpenAPI 3.1.02026-08-0255174167.5 KB

calls

Place an AI voice call

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.

post/api/v1/calls

Headers

Authorizationstring required

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

Idempotency-Keystring

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 body

tostring required

Recipient phone number in E.164 format.

fromNumberstring

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.

fromNumberIdstring

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

outboundInstructionstring required

System prompt for the AI voice agent during the call.

languagestring

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.

maxCallDurationSecondsinteger

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. Free accounts — accounts that have never added credit and never subscribed — are capped at 300 seconds (5 minutes), reported as limits.maxCallDurationSeconds on the account: a higher value sent here returns 400, and a cap inherited from the number or account is clamped to 300. 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.

voiceGender'male' | 'female'

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.

transferTostring

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.