Skip to main content
POST
Purchase Phone Number
Changes state - verify before retry
Recommended. This endpoint is part of the public /v1 API reference and is the supported path for new integrations. See the migration guide for versioning guidance.
Purchases a phone number from your telephony provider and provisions it in your DialNexa workspace. The number is immediately available to assign to an agent for handling inbound calls and to use as the outbound caller ID on outbound calls. Numbers are billed monthly, with billing starting on the date of purchase. Use Search Available Numbers first to find a number that fits your needs, then pass the exact E.164 phone_number string to this endpoint.

When to use this

  • New deployments: provisioning the first number for a region or use case.
  • Capacity expansion: adding numbers to spread outbound volume across multiple caller IDs and avoid spam flagging.
  • Per-customer or per-brand numbers: provisioning a dedicated number for a sub-account, partner, or brand.
For India deployments, the recommended path is purchasing through Plivo. For Bring-Your-Own-SIP setups, numbers from your own carrier are connected through SIP trunks rather than purchased here, see Bring Your Own SIP.

Pre-flight checklist

Before purchasing, confirm:
  • The destination country is enabled in Workspace Settings → Telephony Config.
  • For outbound calling in regulated regions (India, US toll-free, certain EU countries), KYC and verification are complete. See KYC and outbound readiness.
  • The number meets the regulatory requirements for the use case (for example, India 10DLC-equivalent compliance, US toll-free verification).

Errors

  • 400 Bad Request is returned when the number is no longer available, the country is not enabled on this workspace, or the format is invalid.
  • 403 Forbidden is returned when the workspace has not completed the KYC required for the destination country.
  • 409 Conflict is returned when the number was claimed by another buyer between the search and the purchase.

Authorizations

Authorization
string
header
required

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

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