Skip to main content
POST
Purchase a phone number from the specified provider (V1 alias)
Legacy endpoint - deprecated. Unversioned endpoints are scheduled for removal on July 31, 2026. Use Buy Phone Number for new /v1 purchase integrations. This endpoint remains available for existing integrations until then.
Creates a phone number order for the selected telephony provider and provisions the resulting number in the workspace. Use this v1 order path for new integrations.
The older /organization-phone-numbers/purchase path remains documented for existing integrations during the legacy transition.

Authorizations

Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Headers

x-organization-id
string
required

RSA encrypted organization ID (base64 format)

Example:

"BASE64_ENCRYPTED_ORG_ID_HERE"

Body

application/json
phoneNumber
string
required

Phone number to purchase

Example:

"+1234567890"

telephonyProviderId
string
required

ID of telephony provider (14-char string)

Example:

"plivo_123456"

countryISO
string
required

Country ISO code (e.g., US, IN)

Example:

"US"

Response

Phone number purchase initiated and record created

phoneNumber
string
required

Phone number

Example:

"+1234567890"

status
enum<string>
required

Status of the phone number

Available options:
active,
pending
message
string

Status message

organizationPhoneNumber
object

Organization phone number record