Buy Phone Number
Purchase a number through the selected provider.
data carries the number as sent, the provider purchase status (active, or pending while the provider verifies the number), a message, and organizationPhoneNumber, the new workspace record. That record stores the number as country_iso (the calling code, such as 1) plus phone_number (the national digits, such as 4155552671) and shows the stored status at creation (pending). Call Get Phone Number Details for its current status and rental dates.
Use Search Available Numbers first and pass the number exactly as the search returned it. The request accepts digits with an optional leading +; other characters fail request validation before the provider is called.
When To Buy A Phone Number
- New deployments: provisioning the first number for a region or use case.
- Dedicated caller IDs: separate regional, customer, or brand phone numbers.
- Per-customer or per-brand numbers: provisioning a dedicated number for a sub-account, partner, or brand.
Pre-flight checklist
Before purchasing, confirm:- The workspace’s KYC is verified. Otherwise the purchase returns
400. - For an Indian (
IN) Plivo number, DialNexa support has mapped a Plivo compliance ID to the workspace; without it the purchase is refused. - On a workspace with a billing plan, the wallet holds at least the first rental cycle’s cost, and that cost does not take the month’s spend past the monthly spend cap.
- The destination country is enabled in Workspace Settings → Telephony before you place calls from the number.
Verify The Purchase Before Retrying
Readdata.status and data.organizationPhoneNumber.id in the success envelope, then use List Phone Numbers or Get Phone Number Details to confirm the saved number and its status. Check the wallet transactions separately for the first rental charge. If the purchase is pending, wait for activation before routing calls.
Purchasing changes provider inventory and, on a workspace with a billing plan, creates a rental subscription. There is no idempotency key on this operation. After a timeout or uncertain failure, inspect your workspace numbers and provider inventory before retrying; contact support if the provider purchase succeeded but registration failed.
Errors
400 Bad Requestis returned when the workspace’s KYC is not verified, anINPlivo number is requested and no compliance ID is mapped to the workspace, the wallet balance is below the first rental cycle’s cost (the message states the required and available amounts), the first rental would take the month’s spend past the monthly spend cap (This purchase (₹X) would go over your monthly spend cap. ...), number rental is not configured for your billing plan, the number format is invalid, or the provider ID is not supported.- If the provider rejects the purchase, for example because the number was taken between the search and the purchase, the API returns
500with the messageError purchasing phone number:followed by the provider’s reason. After a5xxor a timeout, list your numbers before retrying. countryISOmust be the country of the number being bought. A mismatch fails with500and the messageError purchasing phone number: Invalid phone number or ISO code; contact support before retrying.
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
Phone number to purchase: country code followed by the subscriber number, digits only, with or without a leading plus sign. Both +12025551234 and 12025551234 are accepted.
^\+?[1-9]\d{5,14}$"+12025551234"
ID of telephony provider (14-char string)
"mh00mke5j83neo"
Uppercase two-letter country code of the number being bought, for example US. It must be the number's own country: a mismatch fails with 500 after the provider step.
2^[A-Z]{2}$"US"
Response
Purchase processed. Inspect the active or pending status and confirm the saved number before routing calls.