Buy a Phone Number on Vobiz – Step-by-Step Guide

A phone number (a DID - Direct Inward Dialing number) is the entry point for every inbound call and the caller ID for outbound calls. This guide walks you through buying one on Vobiz two ways - in the console (point-and-click) and via the API (scriptable) - then routing it so it can take calls.

You cannot port a number from another provider (including Plivo) into Vobiz. There is no number transfer/porting flow. To run on Vobiz, buy a new Vobiz number from inventory using the steps below, then point your call flows at it. If you are migrating from Plivo, see the Plivo migration guide.

Before you start

Create an account

Find your API credentials

Your Auth ID (MA_…) and Auth Token are on the dashboard. You need them for every API request as the X-Auth-ID and X-Auth-Token headers.

Check your balance

Buying a number debits a setup fee + the first monthly fee immediately. Make sure your balance covers both before you purchase.

Option A - buy in the console

The fastest way to get a number is the dashboard.

Open the DID section

Vobiz console DID section showing available phone numbers with a country filter

Filter to the number you want

Filter by country/region to narrow the list. Check each number’s capabilities (Vobiz numbers are voice-first) and its setup fee and monthly fee before you commit.

Purchase

Click Buy on the number you want. The setup fee and first monthly fee are debited from your account balance, and the number is assigned to your account immediately.

Route the number

A freshly purchased number is owned but not yet routed. Attach it to an XML Application (to drive call flows via your webhook) or assign it to a SIP trunk. See Route your number below.

Option B - buy via the API

Buying programmatically is a two-call flow: browse inventory, then purchase by E.164.

1. Browse inventory

List numbers available for purchase, filtered by country and an optional substring search against the E.164 number.

cURL

curl -X GET "https://api.vobiz.ai/api/v1/Account/{auth_id}/inventory/numbers?country=IN&search=80&page=1&per_page=25" \
  -H "X-Auth-ID: {auth_id}" \
  -H "X-Auth-Token: {auth_token}"

A response item looks like this - inspect setup_fee, monthly_fee, currency, and capabilities before buying:

Response (truncated)

{
  "items": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "e164": "+918065551234",
      "country": "IN",
      "region": "Karnataka",
      "status": "active",
      "setup_fee": 100,
      "monthly_fee": 1.0,
      "currency": "INR"
    }
  ],
  "page": 1,
  "per_page": 25,
  "total": 500
}

See List Inventory Numbers for the full parameter set. There is no separate search endpoint - use country + search here.

2. Purchase by E.164

Purchase a number by passing its e164 in the request body. Keep the literal + (it is in the JSON body, so no URL-encoding). This debits setup_fee + monthly_fee immediately.

curl -X POST "https://api.vobiz.ai/api/v1/Account/{auth_id}/numbers/purchase-from-inventory" \
  -H "X-Auth-ID: {auth_id}" \
  -H "X-Auth-Token: {auth_token}" \
  -H "Content-Type: application/json" \
  -d '{"e164": "+918065551234"}'

import requests

auth_id = "{auth_id}"
resp = requests.post(
    f"https://api.vobiz.ai/api/v1/Account/{auth_id}/numbers/purchase-from-inventory",
    headers={
        "X-Auth-ID": auth_id,
        "X-Auth-Token": "{auth_token}",
        "Content-Type": "application/json",
    },
    json={"e164": "+918065551234"},
)
resp.raise_for_status()
print(resp.json()["number"]["e164"], "purchased")

const authId = "{auth_id}";
const resp = await fetch(
  `https://api.vobiz.ai/api/v1/Account/${authId}/numbers/purchase-from-inventory`,
  {
    method: "POST",
    headers: {
      "X-Auth-ID": authId,
      "X-Auth-Token": "{auth_token}",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ e164: "+918065551234" }),
  }
);
console.log(await resp.json());

A successful purchase returns the number object with account_id set:

Response - 200 OK

{
  "message": "Number purchased successfully",
  "number": {
    "id": "aabbccdd-1234-5678-90ab-cdef12345678",
    "account_id": "MA_XXXXXXXX",
    "e164": "+918065551234",
    "country": "IN",
    "region": "Karnataka",
    "capabilities": { "voice": true, "sms": false, "mms": false, "fax": false },
    "status": "active",
    "setup_fee": 100,
    "monthly_fee": 1.0,
    "currency": "INR",
    "voice_enabled": true,
    "purchased_at": "2026-03-25T10:00:00Z",
    "source": "inventory"
  }
}

See Purchase from Inventory for every field and error case.

Understand the fees

Charge	When	Notes
Setup fee	Once, at purchase	One-time `setup_fee` shown on the inventory item.
Monthly fee	At purchase, then monthly	`monthly_fee` recurs to keep the number active.

Both are debited in the number’s currency (often INR for India numbers). For a sub-account (SA_) purchase, the parent master account (MA_) is charged - not the sub-account.

If your balance can’t cover setup_fee + monthly_fee, the purchase is rolled back and the number stays in inventory. A failed debit currently surfaces as a 500; a number that isn’t in inventory returns a 404. Check your balance first.

India number series

India DIDs follow TRAI series rules - pick the series that matches your use case:

Series	Use for
140	Promotional / outbound marketing calls.
160	Service / transactional calls (BFSI sector only).
1800	Toll-free inbound.
92	High-pickup mobile-style numbers.

Some India numbers require Aadhaar verification (aadhaar_verification_required on the number object). Review India compliance before you purchase, and register on DLT where required - see DLT registration.

Route your number

A purchased number is owned but not yet routed. Pick one:

Attach to an XML Application

Point inbound calls at your webhook (answer_url) to drive call flows with VobizXML.

Assign to a SIP trunk

Route inbound calls to your PBX or AI platform over SIP.

Hand to a sub-account

Move the DID into a sub-account’s pool (mind the 15-day cool-off on unassign).

Make your first call

Use the number as the from on an outbound call.

Manage and release

See what you own - List Account Phone Numbers.
Release a number - Unrent a Number stops the monthly rental fee and charges the number-release fee configured for your account. A standard release can be cancelled during its 24-hour pending window, which refunds the release fee. An immediate release cannot be cancelled, and you may not get the same digits again.
Sub-account 15-day cool-off - unassigning a recently used DID from a sub-account is blocked for 15 days (409 did_cool_off_in_effect); see Phone Numbers.

Troubleshooting

Problem	Cause	Fix
`404 not_found` on purchase	Number already owned, released, or never stocked	Re-browse inventory and pick an available `e164`.
`500 failed to purchase number`	Balance debit failed (`setup_fee + monthly_fee`)	Top up balance and retry.
`401 Unauthorized`	Missing/incorrect headers or wrong path casing	Send `X-Auth-ID` + `X-Auth-Token`; use `/Account/` (capital A).
Number bought but calls don’t arrive	Number not routed	Attach it to an application or assign it to a trunk.

Quick Start

The 4-step path from sign-up to your first call.

Phone Numbers API

Full reference for listing, buying, and releasing numbers.

Migrating from Plivo?

You can’t port numbers - buy new Vobiz numbers and re-point your flows.

India compliance

Number series, DLT, and KYC rules before you buy.

Getting Started

Using Vobiz Platform

Compliance (India)

Tools

Buy a Phone Number on Vobiz – Step-by-Step Guide

Before you start

Option A - buy in the console

Option B - buy via the API

1. Browse inventory

2. Purchase by E.164

Understand the fees

India number series

Route your number

Attach to an XML Application

Assign to a SIP trunk

Hand to a sub-account

Make your first call

Manage and release

Troubleshooting

Quick Start

Phone Numbers API

Migrating from Plivo?

India compliance

​Before you start

​Option A - buy in the console

​Option B - buy via the API

​1. Browse inventory

​2. Purchase by E.164

​Understand the fees

​India number series

​Route your number

Attach to an XML Application

Assign to a SIP trunk

Hand to a sub-account

Make your first call

​Manage and release

​Troubleshooting

​Related

Quick Start

Phone Numbers API

Migrating from Plivo?

India compliance

Before you start

Option A - buy in the console

Option B - buy via the API

1. Browse inventory

2. Purchase by E.164

Understand the fees

India number series

Route your number

Manage and release

Troubleshooting

Related