Phone Numbers

Buy Phone Number

Purchases the selected provider number (Plivo or Twilio, chosen by telephonyProviderId) and adds it to the authenticated workspace. The workspace KYC must be verified, and a Plivo number in IN needs a compliance ID mapped to the workspace by support. On a workspace with a billing plan, the wallet must hold the plan's rental rate for the provider and country; the first cycle is charged just after the number is set up.

post/v1/organization-phone-numbers/purchase

Request

  • Base URL: https://api.dialnexa.com
  • URL: https://api.dialnexa.com/v1/organization-phone-numbers/purchase
  • Auth: HTTP bearer

Request body

phoneNumberstring 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.

telephonyProviderIdstring required

ID of telephony provider (14-char string)

countryISOstring 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.

Example request

{
  "phoneNumber": "+12025551234",
  "telephonyProviderId": "mh00mke5j83neo",
  "countryISO": "US"
}

Response

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

successtrue required
errorfalse required
statusCodeinteger required
messagestring required
timestampstring date-time required

Example response

{
  "statusCode": 201,
  "message": "Success",
  "data": {
    "message": "Phone number 14155552671 purchase request sent.",
    "organizationPhoneNumber": {
      "id": "phn_mfk3p8z2c4v6bn",
      "phone_number": "9876543210",
      "country_iso": "91",
      "rental_start_date": "2026-09-17",
      "rental_end_date": "2026-10-17"
    }
  }
}

Changes

No recorded changes to this operation across all 1 revision of this API.