---
title: "Purchase a phone number"
method: POST
path: "/v1/phone-numbers"
---

# Purchase a phone number

`POST /v1/phone-numbers`

Purchase an available phone number. Requires a paid plan: the Free plan cannot purchase phone numbers and receives `402` with code `paid_plan_required`. Paid plans include one US number at no charge. The included number is one per account and is granted once: claiming it spends the benefit for good, so releasing that number does not make another one free, and numbers the account already bought do not consume it.

## Request body

- PhoneNumberPurchaseRequest
  - `phoneNumber` string, required — Phone number in E.164 format.
  - `name` string — Optional custom name for the phone number.

## Response `201`

Phone number purchased successfully.

- PhoneNumberResponse
  - `phoneNumber` OwnedPhoneNumber, required
    - `id` string, required
    - `phoneNumber` string, required
    - `name` string — Optional custom name for the phone number.
    - `capabilities` string[], required
    - `status` 'active' | 'suspended' | 'pending', required
    - `senderId` string — Sender ID if the phone number is assigned to a sender.
    - `pricing` OwnedPhoneNumberPricing, required
      - `monthlyPrice` number — Monthly price in USD.
      - `upfrontCost` number — One-time purchase cost in cents.
      - `monthlyCost` number — Monthly cost in cents.
      - `isFreeNumber` boolean — Whether this is a free number.
    - `nextRenewalDate` string, date-time
    - `createdAt` string, date-time, required
    - `updatedAt` string, date-time

## Other responses

- `400` — Invalid request or phone number no longer available.
- `401` — Unauthorized.
- `402` — Payment required. Either the balance cannot cover the purchase (code `insufficient_balance`) or the team is on the Free plan (code `paid_plan_required`): buying phone numbers requires a paid plan, which includes one US number.

---

[API](https://skmtc.net/zavudev/apis/zavu-unified-messaging-layer-api.md) · [All operations](https://skmtc.net/zavudev/apis/zavu-unified-messaging-layer-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/zavudev/zavu-unified-messaging-layer-api/revisions/5a69a1777f6f/schema)