# Purchase phone number API Reference

Buys a phone number, payment-first. The system provisions a number and auto-assigns it, unless you pass `phoneNumber` to buy one exact number from `GET /v1/phone-numbers/available`.

Requires usage-based billing (the Usage plan). The maximum number of phone numbers is determined by the user's plan.

### Outcomes

- Usage-based billing active and a payment method on file: the number provisions inline and bills per month on your usage-based invoice (there is no checkout redirect).
- No payment method on file: `402 PAYMENT_REQUIRED`.
- A regulated country: `202` with `status: "kyc_required"` and a `kycUrl`.

### Price

The monthly price is the one `GET /v1/phone-numbers/countries` quotes for that country and `numberType` at the time of purchase, and it is stamped on the number. Later rate-card changes never move a number you already own.


## POST /v1/phone-numbers/purchase

**Purchase phone number**

Buys a phone number, payment-first. The system provisions a number and auto-assigns it, unless you pass `phoneNumber` to buy one exact number from `GET /v1/phone-numbers/available`.

Requires usage-based billing (the Usage plan). The maximum number of phone numbers is determined by the user's plan.

### Outcomes

- Usage-based billing active and a payment method on file: the number provisions inline and bills per month on your usage-based invoice (there is no checkout redirect).
- No payment method on file: `402 PAYMENT_REQUIRED`.
- A regulated country: `202` with `status: "kyc_required"` and a `kycUrl`.

### Price

The monthly price is the one `GET /v1/phone-numbers/countries` quotes for that country and `numberType` at the time of purchase, and it is stamped on the number. Later rate-card changes never move a number you already own.


### Request Body

- **profileId** (required) `string`: Profile for the number, which may already hold other numbers. Without it the number goes to the default profile. The response's `profileId` carries the assignment.

- **country** `string`: ISO 3166-1 alpha-2 country for the number (default US). International numbers require usage-based billing. Tier 3/4 countries return 202 { status: "kyc_required", kycUrl }. The customer must complete KYC at that URL before the number is ordered. See GET /v1/phone-numbers/countries.

- **numberType** `string`: Which of the country's offered number types to order (see `types[]` on GET /v1/phone-numbers/countries). Omitted = the country's default type, always the WhatsApp-safe choice.

Capabilities, price and KYC requirements are per (country, type):

- toll_free can never connect WhatsApp (400 when combined with connectWhatsapp:true).
- wantsSms:true requires an SMS-capable type.
 - one of: local, mobile, national, toll_free
- **areaCode** `string`: Area code (national destination code, e.g. 11 for Sao Paulo) the number must be in. Omit for any area. Get live options from GET /v1/phone-numbers/availability (areaOptions).

Hard constraint: when the area has no deliverable inventory, the purchase fails with 409 code AREA_CODE_UNAVAILABLE instead of assigning a number from another area. Later replacements stay in this area too.

- **claimId** `string`: Keyless calls only: a `claimId` from a keyless GET /v1/phone-numbers/available. The 401 then carries a `claimUrl` for that exact number. Ignored when an API key is sent.

- **phoneNumber** `string`: One exact number to buy, in E.164, taken from GET /v1/phone-numbers/available.

Hard constraint: when it is no longer available (bought by someone else, or WhatsApp's buy-time check rejects it), the purchase fails with 409 code PHONE_NUMBER_UNAVAILABLE instead of assigning another number. Search again and pick another.

Only for countries and types that activate instantly: a regulated one (202 kyc_required) returns 400 when phoneNumber is set.

- **connectWhatsapp** `boolean`: A phone number is the unit; WhatsApp is one optional feature. Omitted defaults to the WhatsApp provisioning path.

Pass false to buy a STANDALONE number (Calls/SMS only): provisioning skips the Meta pre-verify/OTP steps and the number activates immediately. WhatsApp can be connected to a standalone number later from the connect flow.

- **wantsSms** `boolean`: SMS capability is per-number, not per-country. Pass true to provision from the SMS-capable inventory pool so the number can actually text (see also GET /v1/phone-numbers/available with sms=true, and smsAvailable on GET /v1/phone-numbers/countries).

- **wantsWhatsapp** `boolean`: Declare WhatsApp intent on a STANDALONE purchase (connectWhatsapp:false). The number still activates and bills immediately.

If WhatsApp's buy-time check rejects the assigned number, it is automatically swapped for a WhatsApp-eligible one during the purchase, instead of being delivered with WhatsApp unavailable.

Ignored on the WhatsApp provisioning path (connectWhatsapp omitted or true), which always delivers a WhatsApp-verified number.

- **purchaseIntentId** `string`: Optional idempotency key. Send the same value when retrying a purchase: if a number was already bought under this key, the API returns { status: "already_purchased", numberId, phoneNumber, profileId } instead of provisioning a second number. Generate a fresh key for each genuinely new purchase.

- **allowMultiple** `boolean`: Any second purchase within 10 minutes of a previous one is rejected with 409 code PURCHASE_VELOCITY as duplicate protection. Pass true to confirm the additional purchase is intentional (e.g. bulk provisioning).


### Responses

#### 200: Either a checkout URL (first number) or the provisioned phone number (subsequent numbers).


**Response Body:**

*One of the following:*
  - **message** `string`: No description
  - **checkoutUrl** `string` (uri): No description
  - **message** `string`: No description
  - **phoneNumber** `object`: 
    - **id** `string`: No description
    - **phoneNumber** `string`: No description
    - **status** `string`: No description
    - **country** `string`: No description
    - **provisionedAt** `string` (date-time): No description
    - **metaPreverifiedId** `string`: No description
    - **metaVerificationStatus** `string`: No description
    - **profileId** `string`: The profile the number was actually assigned to.
  - **status** `string`: No description - one of: already_purchased
  - **numberId** `string`: No description
  - **phoneNumber** `string`: No description
  - **profileId** `string`: The profile the number was actually assigned to.

#### 202: Country requires end-user KYC before the number can be ordered.

**Response Body:**

- **status** `string`: No description - one of: kyc_required
- **country** `string`: No description
- **numberType** `string`: The type that will be ordered after KYC approval.
- **kycUrl** `string`: No description

#### 400: Plan limit reached, profileId required, or country not available

#### 401: Missing or invalid API key.

A call with no key at all gets the purchase back as a claim. `details.claimUrl` is a signup link opening the dashboard's confirm step for the requested `country`, `numberType` and `areaCode` (or for the number behind `claimId`, from a keyless GET /v1/phone-numbers/available).

Hand it to the person who will own the number.


**Response Body:**

- **error** `string`: No description
- **code** `string`: No description
- **details** `object`: 
  - **claimId** `string`: No description
  - **claimUrl** `string`: No description

#### 402: No card on file (usage-based account): code PAYMENT_REQUIRED, add a card, then retry. Balance billing: code insufficient_balance (balance at $0, or below the number's first month while auto top-up cannot refill it) or usage_limit_reached; add funds at `funding_url` (`required_cents` is what the balance must hold), then retry.

#### 403: A paid plan is required

#### 409: The purchase was not made. The code says why:

- PURCHASE_VELOCITY: duplicate-purchase protection, another number was purchased within the last 10 minutes. Retry with allowMultiple: true to confirm.
- AREA_CODE_UNAVAILABLE: the requested areaCode has no deliverable inventory right now. Pick another area or omit areaCode.
- PHONE_NUMBER_UNAVAILABLE: search again and pick another number.
- COUNTRY_OUT_OF_STOCK: this country and type have no orderable numbers right now; pick another.
- NO_WHATSAPP_ELIGIBLE_NUMBER: every number the carrier offered is one WhatsApp refuses. Pass an areaCode or try again for a fresh batch.


**Response Body:**

- **error** `string`: No description
- **code** `string`: No description - one of: PURCHASE_VELOCITY, AREA_CODE_UNAVAILABLE, PHONE_NUMBER_UNAVAILABLE, COUNTRY_OUT_OF_STOCK, NO_WHATSAPP_ELIGIBLE_NUMBER

#### 422: International numbers require usage-based billing (legacy Stripe users are US-only). Response body code: USAGE_BILLING_REQUIRED.

#### 503: The carrier could not take the order just now (code CARRIER_UNAVAILABLE); the number is not taken, retry the same request in a minute.

**Response Body:**

- **error** `string`: No description
- **code** `string`: No description - one of: CARRIER_UNAVAILABLE

---