Skip to main content
POST
Buy Phone Number
Changes state - verify before retry Purchases a phone number from your telephony provider and provisions it in your DialNexa workspace. Confirm that the saved number is active before assigning it for inbound or outbound calls; a provider purchase can remain pending while verification completes. On a workspace with a billing plan, the price is the plan’s rental rate for the provider and country (in INR), not the reference price in List Phone Number Pricing. On such a workspace, the first rental cycle is charged from your wallet just after the number is set up, and later cycles are charged automatically when they come due. If the first charge does not go through, DialNexa retries it on the next renewal run, and the rental expires if the balance is still too low. The cycle length comes from your billing plan and is 30 days unless the plan says otherwise. A workspace without a billing plan is not charged a rental. Use Search Available Numbers first to find a number that fits your needs, then pass the number back exactly as the search returned it. Providers differ on the leading plus sign, so this endpoint accepts the country code and subscriber number with or without it. Anything other than digits and an optional leading plus is rejected before a provider call is made. The response 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.
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 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

Read data.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 Request is returned when the workspace’s KYC is not verified, an IN Plivo 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 500 with the message Error purchasing phone number: followed by the provider’s reason. After a 5xx or a timeout, list your numbers before retrying.
  • countryISO must be the country of the number being bought. A mismatch fails with 500 and the message Error purchasing phone number: Invalid phone number or ISO code; contact support before retrying.

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: country code followed by the subscriber number, digits only, with or without a leading plus sign. Both +12025551234 and 12025551234 are accepted.

Pattern: ^\+?[1-9]\d{5,14}$
Example:

"+12025551234"

telephonyProviderId
string
required

ID of telephony provider (14-char string)

Example:

"mh00mke5j83neo"

countryISO
string
required

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.

Required string length: 2
Pattern: ^[A-Z]{2}$
Example:

"US"

Response

Purchase processed. Inspect the active or pending status and confirm the saved number before routing calls.

success
enum<boolean>
required
Available options:
true
error
enum<boolean>
required
Available options:
false
statusCode
integer
required
Example:

201

message
string
required
Example:

"Success"

data
object
required
timestamp
string<date-time>
required