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.
Newly purchased numbers take about 2 minutes to register. Wait a couple of minutes before making calls from the number. A call placed sooner is rejected with From number not owned by account - see the FAQ.
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
A response item looks like this - inspect setup_fee, monthly_fee, currency, and capabilities before buying:
Response (truncated)
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.
A successful purchase returns the number object with account_id set:
Response - 200 OK
See Purchase from Inventory for every field and error case.
A 200 OK means the number is yours, but it takes about 2 minutes to register before you can call from it. If your script buys a number and dials from it in the same run, wait a couple of minutes between the two calls - otherwise the call is rejected with From number not owned by account.

Understand the fees

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: 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

Quick Start

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

Phone Numbers API

Full reference for listing, buying, and releasing numbers.

India compliance

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