Provision a phone number
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.
Billing. Pay-as-you-go accounts are charged the first ownership month from their credit balance immediately, and the request is rejected with 402 when the balance can’t cover it. On a flat-rate subscription the number is added to the subscription instead — the quantity goes up by one and Stripe invoices the prorated difference. The one exception: a subscription always bills at least one number, so if you hold no numbers (you released them all) the first number you provision back adds no charge — the quantity is already there. Either way the new number is covered by the subscription the moment this call returns.
Include imessage in capabilities to provision an iMessage number. iMessage provisioning is asynchronous: the response is 202 with the number in setupStatus: provisioning. Wait for the number.status_changed event to report a terminal status (ready, or degraded when a channel failed) before sending from it or calling from it — polling List phone numbers works too, but the event tells you the moment it happens, and its capabilities say which channels made 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
Your Dial API key, sent as Authorization: Bearer sk_live_...
Request
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.
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.
Whether calling is switched on for the new number. Defaults to true. Pass false to provision a messaging-only line: inbound calls are not connected and Place a call from it is refused, with no window in which the line answers calls. Changeable later with Update a phone number.
Also connect WhatsApp to the new line. Valid only with capabilities: ["sms", "call", "imessage"] — WhatsApp rides on an iMessage line, so there is no standard-number combination (any other combination is rejected with 400).
WhatsApp is in beta and enabled per account: without access this field is rejected with 404, because to such an account the capability does not exist. Contact support to request it.
The number arrives with WhatsApp already set up and warmed: whatsapp.status is ready in this response, and no WhatsApp number.status_changed follows it. setupStatus is unaffected and behaves as for any iMessage number. areaCode is not honored for WhatsApp numbers.
When no WhatsApp number is available right now, the request is refused with 503 whatsapp_unavailable: nothing was bought or charged, so retrying is safe. See WhatsApp lines.
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.
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.
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.
Preferred US area code. Optional — when omitted, any available US number is provisioned. Only US numbers can be provisioned at this time.
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. Still applied to the subscription when the purchase raises no charge at all (the free first number described above), so it discounts the following invoices instead.
Response
Number provisioned (synchronous — SMS/call numbers).