Sign in
phoneNumbers

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.

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.

post/api/v1/numbers

Headers

Authorizationstring required

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

Request body

explicitProgrammaticConsentstring required

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.

capabilitiesApiV1NumbersPostRequestBodyContentApplicationJsonSchemaCapabilitiesItems[]

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.

inboundInstructionstring

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.

inboundVoiceGender'male' | 'female'

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.

inboundLanguagestring

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.

areaCodestring

Preferred US area code. Optional — when omitted, any available US number is provisioned. Only US numbers can be provisioned at this time.

promotionCodestring

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).

Changes