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.
Authentication
Your Dial API key, sent as Authorization: Bearer sk_live_...
Headers
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
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. A replaced number’s ID calls from the number that replaced it (see replacedBy); its E.164 no longer works and returns 404. Provide exactly one of fromNumber or fromNumberId.
ID of the Dial number to call from. Legacy alternative to fromNumber — provide exactly one of the two.
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.
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.
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.
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.