v4

OpenAPI 3.1.02026-08-0255174167.5 KB

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.

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