---
title: "Purchase a phone number"
method: POST
path: "/accounts/{account_id}/phone_numbers"
tags: ["Phone numbers"]
---

# Purchase a phone number

`POST /accounts/{account_id}/phone_numbers`

Purchase a new phone number for the account. You can specify an exact phone number, search criteria, or let the system select a random number.

When `phone_number` is provided, all other search parameters are ignored.

## Path parameters

- `account_id` string, required — The account for which the phone number should be created.

## Request body

- PhoneNumberPurchaseParams — Parameters for purchasing a new phone number. The system will automatically infer the type in certain cases: - If only area_code is provided, type is inferred from the area code - If only latitude/longitude are provided, type is inferred as 'local' - Otherwise, type must be explicitly specified If phone_number is provided, all other search parameters are ignored.
  - `area_code` string — The desired area code for this phone number. If provided without type, the type will be inferred.
  - `latitude` number — Latitude to search for nearby phone numbers. Must be used with longitude. If provided without type, type will be inferred as 'local'.
  - `longitude` number — Longitude to search for nearby phone numbers. Must be used with latitude. If provided without type, type will be inferred as 'local'.
  - `name` string — A human-readable name for the phone number. If not provided, defaults to the formatted phone number.
  - `phone_number` string, phone-number — The exact phone number to purchase in E.164 format. When provided, all other search parameters are ignored.
  - `type` 'local' | 'toll_free' — Whether the phone number is local or toll-free. Can be omitted if area_code or latitude/longitude are provided.

## Response `201`

Purchased phone number

- PhoneNumber — A phone number that can be used to send and receive messages and calls
  - `campaign` PhoneNumberCampaign, required — Campaign attachment details for a domestic local phone number
    - `attachment_status` 'attached' | 'attachment_pending' | 'detached' | 'detachment_pending', required — The current campaign attachment status for this phone number.
    - `id` string, required — The unique identifier of the campaign this phone number is attached to
  - `campaign_id` string, nullable, required — Deprecated. The unique identifier of the campaign this phone number is attached to, if any
  - `id` string, required — Unique identifier for the phone number
  - `name` string, nullable, required — A human-readable name for the phone number
  - `number` string, phone-number, required — The phone number in E.164 format
  - `type` 'local' | 'short_code' | 'toll_free', required — Whether the phone number is local, toll-free, or short code

## Other responses

- `default` — Error

---

[API](https://skmtc.net/surgeapi/apis/surge.md) · [All operations](https://skmtc.net/surgeapi/apis/surge/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/surgeapi/surge/revisions/b5b0b6f62245/schema)