v53

latestOpenAPI 3.1.1raw.githubusercontent.com2026-07-264065213.4 KB

Phone numbers

Purchase a phone number

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.

post/accounts/{account_id}/phone_numbers

Path parameters

account_idstring required

The account for which the phone number should be created.

Example:acct_01j9a43avnfqzbjfch6pygv1td

Request body

area_codestring

The desired area code for this phone number. If provided without type, the type will be inferred.

latitudenumber

Latitude to search for nearby phone numbers. Must be used with longitude. If provided without type, type will be inferred as 'local'.

longitudenumber

Longitude to search for nearby phone numbers. Must be used with latitude. If provided without type, type will be inferred as 'local'.

namestring

A human-readable name for the phone number. If not provided, defaults to the formatted phone number.

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

Example request

{
  "description": "Purchase any available local number",
  "summary": "Random local number",
  "value": {
    "type": "local"
  }
}

Response

Purchased phone number

campaign_idstring nullable required

Deprecated. The unique identifier of the campaign this phone number is attached to, if any

idstring required

Unique identifier for the phone number

namestring nullable required

A human-readable name for the phone number

numberstring 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

Example response

{
  "campaign": {
    "attachment_status": "attached",
    "id": "cpn_01jjnn7s0zfx5tdcsxjfy93et2"
  },
  "campaign_id": "cpn_01jjnn7s0zfx5tdcsxjfy93et2",
  "id": "pn_01jsjwe4d9fx3tpymgtg958d9w",
  "name": "(801) 555-1234",
  "number": "+18015551234",
  "type": "local"
}