---
title: "Provision a phone number"
method: POST
path: "/api/v1/numbers"
tags: ["phoneNumbers"]
---

# Provision a phone number

`POST /api/v1/numbers`

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

## Headers

- `Authorization` string, required

## Request body

- object
  - `explicitProgrammaticConsent` string, 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.
  - `capabilities` ApiV1NumbersPostRequestBodyContentApplicationJsonSchemaCapabilitiesItems[] — 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.
  - `inboundInstruction` string — 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.
  - `inboundLanguage` string — 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.
  - `areaCode` string — Preferred US area code. Optional — when omitted, any available US number is provisioned. Only US numbers can be provisioned at this time.
  - `promotionCode` string — 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 `201`

Number provisioned (synchronous — SMS/call numbers).

- PhoneNumbersProvisionNumberResponse201
  - `number` PhoneNumber
    - `id` string
    - `number` string — The number in E.164 format.
    - `nickname` string, nullable — Optional human-readable label for the number, e.g. "Support line". Free text, at most 100 characters, not required to be unique. Null when unset. Set and cleared with Update a phone number.
    - `firstName` string, nullable — iMessage display first name — with `lastName` and the avatar photo, the identity shown beside this number's messages in recipients' Messages apps. At most 30 characters. Null when unset, and always null on numbers without the `imessage` capability. Set and cleared with Update a phone number.
    - `lastName` string, nullable — iMessage display last name. At most 30 characters. Null when unset, and always null on numbers without the `imessage` capability. Set and cleared with Update a phone number.
    - `avatarUrl` string, nullable — Public URL of the number's current iMessage avatar photo, hosted by Dial. Null when no photo has been set, and always null on numbers without the `imessage` capability. Set with Update a phone number; the photo can be replaced but not removed.
    - `country` string — ISO-3166-1 alpha-2 country code of the number. Always `US` — only US numbers can be provisioned at this time.
    - `capabilities` PhoneNumberCapabilitiesItems[] — Channels the number supports. `["sms","call"]` for a standard number; `["sms","call","imessage"]` for an iMessage number (which sends iMessage with automatic fallback to RCS/SMS). Mirrors the `capabilities` accepted when provisioning.
    - `setupStatus` 'provisioning' | 'ready' | 'failed' — Whether the number is ready to use. An SMS/call number is always `ready`. An `imessage` number is `provisioning` while it's being set up and only becomes usable for sending or calling once `ready` (`failed` on a setup error). Poll List phone numbers to await `ready`.
    - `setupError` string, nullable — Human-readable reason when `setupStatus` is `failed`; null otherwise.
    - `inboundInstruction` string, nullable — System prompt the AI voice agent uses on inbound calls to this number. Set at provisioning time and changeable with Update a phone number. Null for numbers provisioned before this field existed — those reject inbound calls until an instruction is set.
    - `inboundVoiceGender` 'male' | 'female' — Voice gender the AI agent uses on inbound calls to this number. Null when unset — the voice then uses the default, female. Set and cleared with Update a phone number.
    - `inboundLanguage` string, nullable — BCP-47 language tag the AI voice agent uses on inbound calls to this number. Null when unset — the language is then detected from the caller's country prefix on each call, with the agent handling both that language and `en-US`. Set and cleared with Update a phone number.
    - `accountId` string
    - `createdAt` string, date-time
    - `maxCallDurationSeconds` integer, nullable — Call-length cap in seconds; the effective cap on a call is the first one set in priority order — per-call, then number, then account — falling back to the global default. A higher-priority level overrides a lower one. Null means this level sets no cap. Free accounts (never added credit, never subscribed) are additionally hard-capped at 300 seconds regardless of any configured cap.
    - `tenDlc` PhoneNumberTenDlc — US 10DLC carrier registration for this number. Null when 10DLC does not apply to it — a non-US number, a number with the `imessage` capability (those send over Apple Messages for Business, not carrier SMS), or a number on an account that isn't pay-as-you-go and has no registration yet. Otherwise an object whose `status` says where the registration stands, starting at `not_registered`. US carriers block outbound SMS and MMS sent from an unregistered 10-digit number to US phone numbers. Registering lifts that block for this number. Inbound texts, voice calls in either direction, and messaging to numbers outside the US are unaffected.
      - `status` 'not_registered' | 'in_review' | 'with_carrier' | 'approved' | 'rejected', required — Where this number's registration stands. - `not_registered` — 10DLC applies to this number but nothing has been submitted. Outbound US SMS/MMS is blocked by carriers. - `in_review` — submitted; Dial is checking the details before filing them with the carrier registry. - `with_carrier` — filed with the carrier registry; a decision usually lands within 3–5 business days. - `approved` — registered. The number can send outbound SMS and MMS to US phone numbers. - `rejected` — changes are needed before it can be registered. See `reason`, then resubmit (no additional fee). The brand and the campaign are vetted separately, and this is the combined outcome: `approved` means both cleared, and `rejected` means either was turned down.
      - `kind` 'sole_proprietor' | 'business', required — Who the number was registered as. Null while `status` is `not_registered`.
      - `submittedAt` string, date-time, nullable, required — When the current submission was sent. Null while `status` is `not_registered`. A resubmission after a rejection updates this.
      - `reviewedAt` string, date-time, nullable, required — When the registration was approved or rejected. Null until then.
      - `reason` string, nullable, required — What needs to change, verbatim as shown to the account owner. Non-null only when `status` is `rejected`.

## Other responses

- `400` — The request body failed validation.
- `401` — Missing or invalid API key.
- `402` — Insufficient Dial credit. The number is pay-as-you-go and the account's credit balance is at or below zero. Add credit or start a subscription. (error code `insufficient_credit`.)
- `403` — iMessage numbers aren't available for this account — either the account isn't eligible for iMessage yet, or it's on a flat-rate subscription (iMessage is pay-as-you-go only).

---

[API](https://skmtc.net/getdial/apis/rest-api.md) · [All operations](https://skmtc.net/getdial/apis/rest-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/getdial/rest-api/revisions/5f4eb30ac29a/schema)