For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.
Provisions a new phone number. `inboundInstruction` is optional — it becomes the new number's inbound voice-agent prompt, and a default greeting is used if you omit it. Not idempotent — there is no idempotency key, so retrying a failed request can provision an additional number. Confirm via List phone numbers before retrying.
Include `imessage` in `capabilities` to provision an iMessage number. iMessage provisioning is **asynchronous**: the response is `202` with the number in `setupStatus: provisioning`. Poll List phone numbers until `setupStatus` is `ready` before sending from it or calling from it. iMessage numbers are available on **pay-as-you-go only** — an account on a flat-rate subscription is rejected with `403`; switch to pay-as-you-go to add one.
`explicitProgrammaticConsent` is **required** on every provisioning request (standard and iMessage): a short, human-readable attestation that the account holder has explicitly consented to provisioning this number programmatically (e.g. `"User modal confirmation"`). Requests without it are rejected with `400`.
Authentication
AuthorizationBearer
Your Dial API key, sent as Authorization: Bearer sk_live_...
Required. A short, human-readable attestation that the account holder explicitly consented to provisioning this number programmatically. Stored on the number for the provisioning audit trail. Example values: "User modal confirmation" (from the dashboard) or your own consent record reference.
capabilitieslist of enumsOptionalDefaults to ["sms","call"]
What the number should be able to do. Two combinations are accepted: `["sms", "call"]` (the default) for a standard SMS/call number, or `["sms", "call", "imessage"]` for an iMessage number (provisioned asynchronously — see the note above). `areaCode` and `promotionCode` are ignored for iMessage numbers.
Allowed values:
inboundInstructionstringOptional
System prompt for the AI voice agent on inbound calls to this number. Optional — a default greeting is used if omitted. Update later with Update a phone number.
inboundVoiceGenderenumOptional
Voice gender for the AI agent on inbound calls to this number. Optional — when omitted, the voice is female (the default for every language). Pass male to override. Update later with Update a phone number.
Allowed values:
inboundLanguagestringOptional
BCP-47 language tag for the AI voice agent on inbound calls to this number. Optional — when omitted, Dial detects the language from the caller’s country prefix on each call and the agent handles both that language and en-US. Pass an explicit tag to pin every inbound call to a single language. Update later with Update a phone number.
areaCodestringOptional
Preferred US area code. Optional — when omitted, any available US number is provisioned. Only US numbers can be provisioned at this time.
promotionCodestringOptional
Optional customer-facing promotion code (e.g. `LAUNCH20`). Only applies to **subscription** accounts, where adding a number bumps the subscription quantity and bills a prorated amount — the code is handed to Stripe and discounts that charge per the underlying coupon's own scope and duration. Ignored for pay-as-you-go accounts. An invalid, expired, or inapplicable code is rejected with `400`.
Response
Number provisioned (synchronous — SMS/call numbers).
numberobject
Errors
400
Bad Request Error
401
Unauthorized Error
402
Payment Required Error
403
Forbidden Error
Provisions a new phone number. inboundInstruction is optional — it becomes the new number’s inbound voice-agent prompt, and a default greeting is used if you omit it. Not idempotent — there is no idempotency key, so retrying a failed request can provision an additional number. Confirm via List phone numbers before retrying.
Include imessage in capabilities to provision an iMessage number. iMessage provisioning is asynchronous: the response is 202 with the number in setupStatus: provisioning. Poll List phone numbers until setupStatus is ready before sending from it or calling from it. iMessage numbers are available on pay-as-you-go only — an account on a flat-rate subscription is rejected with 403; switch to pay-as-you-go to add one.
explicitProgrammaticConsent is required on every provisioning request (standard and iMessage): a short, human-readable attestation that the account holder has explicitly consented to provisioning this number programmatically (e.g. "User modal confirmation"). Requests without it are rejected with 400.
What the number should be able to do. Two combinations are accepted: ["sms", "call"] (the default) for a standard SMS/call number, or ["sms", "call", "imessage"] for an iMessage number (provisioned asynchronously — see the note above). areaCode and promotionCode are ignored for iMessage numbers.
Optional customer-facing promotion code (e.g. LAUNCH20). Only applies to subscription accounts, where adding a number bumps the subscription quantity and bills a prorated amount — the code is handed to Stripe and discounts that charge per the underlying coupon’s own scope and duration. Ignored for pay-as-you-go accounts. An invalid, expired, or inapplicable code is rejected with 400.
