Phone Numbers
Buy Phone Number
Purchase a number through the selected provider.
POST
Purchase Phone Number
Changes state - verify before retry
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
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.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.
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 Requestis returned when the number is no longer available, the country is not enabled on this workspace, or the format is invalid.403 Forbiddenis returned when the workspace has not completed the KYC required for the destination country.409 Conflictis returned when the number was claimed by another buyer between the search and the purchase.
Related endpoints
- Search Available Numbers: find a number to purchase.
- List Phone Numbers: confirm the purchased number appears in your workspace.
- Get Phone Number Details: inspect the purchased number by ID.
- Delete Phone Number: remove a number you no longer use.
- Purchase a Phone Number guide: end-to-end provisioning walkthrough.
- KYC and outbound readiness: verification required before purchasing in regulated regions.
Authorizations
Bearer authentication header of the form Bearer <token>, where <token> is your auth token.
Body
application/json
Purchase Phone Number