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

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

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

## 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.dev/getdial/apis/rest-api.md) · [All operations](https://skmtc.dev/getdial/apis/rest-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/getdial/rest-api/revisions/2e0d1adb85a6/schema)