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

## Request

- Base URL: `https://api.surge.app`
- URL: `https://api.surge.app/accounts/{account_id}/phone_numbers`
- Auth: HTTP bearer

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'.
  - `metadata` Metadata: Set of key-value pairs that will be stored with the object.
  - `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
  - `metadata` Metadata, required: Set of key-value pairs that will be stored with the object.
  - `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

## Changes

- **2026-10-16** `912b2a3101fc`: 2 info
  - added the new optional request property `metadata`
  - added the required property `metadata` to the response with the `201` status
- **2026-07-14** `efe962c31996`: 1 info
  - added the new optional request property `phone_number`
- **2026-07-14** `645782889002`: 2 info
  - response property `campaign_id` deprecated
  - added the required property `campaign` to the response with the `201` status
- **2026-04-22** `844ecbfa0d5b`: 2 info
  - added the new optional request property `name`
  - added the required property `name` to the response with the `201` status
- **2026-03-11** `347377dfecf0`: 1 info
  - added the required property `campaign_id` to the response with the `201` status

[Operation history](https://skmtc.dev/surgeapi/apis/surge/changes/accounts/:account_id/phone_numbers/post.md)

---

[API](https://skmtc.dev/surgeapi/apis/surge.md) - [All operations](https://skmtc.dev/surgeapi/apis/surge/llms.txt) - [OpenAPI document](https://skmtc.dev/surgeapi/apis/surge/revisions/bb534713d694?raw)