Provision a phone number | Dial — Communication Stack for AI Agents

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.

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

Authentication

AuthorizationBearer

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

Request

This endpoint expects an object.

explicitProgrammaticConsentstringRequired1-2000 characters

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.

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.

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

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

numberobjectOptional

Errors

400

Bad Request Error

401

Unauthorized Error

402

Payment Required Error

403

Forbidden Error

$	curl -X POST https://api.getdial.ai/api/v1/numbers \
>	-H "Authorization: Bearer <token>" \
>	-H "Content-Type: application/json" \
>	-d '{
>	"explicitProgrammaticConsent": "User modal confirmation"
>	}'

1	{
2	"number": {
3	"id": "a1b2c3d4-e5f6-7890-ab12-cd34ef567890",
4	"number": "+14155550123",
5	"nickname": "Support line",
6	"firstName": "Maya",
7	"lastName": "Chen",
8	"avatarUrl": "https://getdial.ai/public-media/9f2c47a1b8d3e6f0a1b2c3d4.png",
9	"country": "US",
10	"capabilities": [
11	"sms",
12	"call"
13	],
14	"setupStatus": "ready",
15	"setupError": "",
16	"inboundInstruction": "You are Dial's receptionist. Greet the caller and find out what they need.",
17	"inboundVoiceGender": "female",
18	"inboundLanguage": "es-ES",
19	"accountId": "acc_9876543210abcdef",
20	"createdAt": "2024-01-15T09:30:00Z",
21	"maxCallDurationSeconds": 3600,
22	"tenDlc": {
23	"status": "in_review",
24	"kind": "business",
25	"submittedAt": "2024-01-15T09:30:00Z",
26	"reviewedAt": "2024-01-20T15:45:00Z",
27	"reason": "The message flow describes a checkout page rather than the SMS consent step. Say where the consent wording and the checkbox appear, and that the box starts unchecked."
28	}
29	}
30	}