Skip to main content
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

1

Create an account

Sign up at console.vobiz.ai. New accounts get free starter credit to explore.
2

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

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

Open the DID section

Sign in to console.vobiz.ai and open the DID (Numbers) section from the sidebar.
Vobiz console DID section showing available phone numbers with a country filter
2

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

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

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"}'
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

ChargeWhenNotes
Setup feeOnce, at purchaseOne-time setup_fee shown on the inventory item.
Monthly feeAt purchase, then monthlymonthly_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:
SeriesUse for
140Promotional / outbound marketing calls.
160Service / transactional calls.
1600Toll-free (transactional).
92High-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 returns it to inventory and stops the monthly fee. This is irreversible - you may not get the same digits back.
  • 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

ProblemCauseFix
404 not_found on purchaseNumber already owned, released, or never stockedRe-browse inventory and pick an available e164.
500 failed to purchase numberBalance debit failed (setup_fee + monthly_fee)Top up balance and retry.
401 UnauthorizedMissing/incorrect headers or wrong path casingSend X-Auth-ID + X-Auth-Token; use /Account/ (capital A).
Number bought but calls don’t arriveNumber not routedAttach 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.