Skip to main content
POST
/
organization-phone-numbers
/
purchase
Purchase a phone number
curl --request POST \
  --url https://api.dialnexa.com/v1/organization-phone-numbers/purchase \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "phone_number": "+912234567890",
  "provider": "<string>"
}
'
{
  "id": "phn_abc123",
  "phone_number": "+912234567890",
  "label": "Main Support Line",
  "agent_id": "agt_abc123",
  "status": "active",
  "provider": "twilio",
  "created_at": "2024-03-01T10:00:00.000Z",
  "nickname": "Sales Line"
}
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).

​
Body parameters

FieldDescription
phone_numberE.164 number returned by Search Available Numbers.

​
Request example

{
  "phone_number": "+912234567890"
}

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

​
Request

curl -X POST "https://api.dialnexa.com/v1/organization-phone-numbers/purchase" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"phone_number": "+912234567890"}'

​
Response

{
  "id": "phn_f7w2kx5mb9qz",
  "phone_number": "+912234567890",
  "country_code": "IN",
  "type": "local",
  "monthly_cost_usd": "1.15",
  "capabilities": ["voice"],
  "inbound_agent_id": null,
  "created_at": "2024-01-15T07:00:00.000Z"
}

Authorizations

​
Authorization
string
header
required

Pass your API key as a Bearer token in the Authorization header.

Body

application/json
​
phone_number
string
required

The exact number to purchase, in E.164 format.

Example:

"+912234567890"

​
provider
string

Telephony provider (e.g. twilio, plivo). Defaults to your account configured provider.

Response

Phone number purchased and provisioned.

​
id
string
Example:

"phn_abc123"

​
phone_number
string
Example:

"+912234567890"

​
label
string | null
Example:

"Main Support Line"

​
agent_id
string | null
Example:

"agt_abc123"

​
status
enum<string>

Phone number provisioning status.

Available options:
pending,
active
Example:

"active"

​
provider
string
Example:

"twilio"

​
created_at
string<date-time>
Example:

"2024-03-01T10:00:00.000Z"

​
nickname
string | null

Human-readable nickname shown in dashboard selectors and phone number tables.

Maximum string length: 255
Example:

"Sales Line"