Phone Numbers
List Account Phone Numbers
Retrieve all phone numbers purchased and assigned to your Vobiz account - capabilities, billing, status, and application assignments across 130+ countries.
GET
/
api
/
v1
/
Account
/
{auth_id}
/
numbers
List phone numbers
curl --request GET \
--url https://api.vobiz.ai/api/v1/Account/{auth_id}/numbers \
--header 'X-Auth-ID: <api-key>' \
--header 'X-Auth-Token: <api-key>'import requests
url = "https://api.vobiz.ai/api/v1/Account/{auth_id}/numbers"
headers = {
"X-Auth-ID": "<api-key>",
"X-Auth-Token": "<api-key>"
}
response = requests.get(url, headers=headers)
print(response.text)const options = {
method: 'GET',
headers: {'X-Auth-ID': '<api-key>', 'X-Auth-Token': '<api-key>'}
};
fetch('https://api.vobiz.ai/api/v1/Account/{auth_id}/numbers', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));{
"items": [
{
"id": "aabbccdd-1234-5678-90ab-cdef12345678",
"account_id": "MA_XXXXXXXX",
"e164": "+919876543210",
"country": "IN",
"region": "Karnataka",
"capabilities": {
"voice": true,
"sms": false,
"mms": false,
"fax": false
},
"status": "active",
"provider": "",
"setup_fee": 100,
"monthly_fee": 300,
"currency": "INR",
"application_id": "20577609616603585",
"voice_enabled": true,
"tags": [],
"purchased_at": "2026-03-25T06:58:38.796024Z",
"is_blocked": false,
"created_at": "2026-03-25T18:30:00Z",
"updated_at": "2026-03-25T06:58:54.752187Z",
"is_trial_number": false,
"last_billing_date": "2026-03-25T06:58:38.796024Z",
"next_billing_date": "2026-04-25T06:58:38.796024Z",
"minimum_commitment_months": 0,
"aadhaar_verification_required": false,
"aadhaar_verified": false,
"source": "purchased"
},
{
"id": "11223344-5566-7788-99aa-bbccddeeff00",
"account_id": "MA_XXXXXXXX",
"e164": "+912271263984",
"country": "IN",
"region": "Mumbai",
"capabilities": {
"voice": true,
"sms": false,
"mms": false,
"fax": false
},
"status": "active",
"provider": "",
"setup_fee": 100,
"monthly_fee": 200,
"currency": "INR",
"application_id": "31985999331899218",
"voice_enabled": true,
"tags": [],
"purchased_at": "2026-03-25T10:25:30.672202Z",
"is_blocked": false,
"created_at": "2026-03-25T09:30:04.541115Z",
"updated_at": "2026-03-25T10:29:35.330503Z",
"is_trial_number": false,
"last_billing_date": "2026-03-25T10:25:30.672202Z",
"next_billing_date": "2026-04-25T10:25:30.672202Z",
"minimum_commitment_months": 0,
"aadhaar_verification_required": false,
"aadhaar_verified": false,
"source": "purchased"
}
],
"page": 1,
"per_page": 25,
"total": 24
}GET https://api.vobiz.ai/api/v1/Account/{auth_id}/numbers
Overview
Use this endpoint to see the numbers your account owns. For each number it returns:- the number in E.164 format (
e164), itscountryandregion - its
capabilities(voice, SMS, MMS, fax) andstatus - its rental cost (
setup_fee,monthly_fee,currency) and billing dates - the application it is routed to (
application_id)
page and per_page, and you can narrow them to one number with search.
Authentication required:
X-Auth-ID- Your Auth ID (e.g.,{auth_id})X-Auth-Token- Your account Auth TokenContent-Type: application/json
Query Parameters
| Field | Type | Required | Description |
|---|---|---|---|
page | integer | No | Page number, starting at 1. Default: 1. |
per_page | integer | No | Number of records per page. Default: 25. |
search | string | No | Filter by phone number. Include the country code. For an E.164 number, URL-encode the leading + as %2B or use --data-urlencode. |
The request and response both use
page and per_page. The limit and offset parameters do not control pagination for this endpoint.Use
search to filter by phone number.Master Accounts (MA_): results from a master account include numbers owned by its sub-accounts (
SA_). Each item’s account_id tells you which account owns it.Request
cURL
curl --get "https://api.vobiz.ai/api/v1/Account/{auth_id}/numbers" \
--data-urlencode "page=1" \
--data-urlencode "per_page=20" \
-H "X-Auth-ID: {auth_id}" \
-H "X-Auth-Token: {auth_token}"
Search owned numbers
Use--data-urlencode to preserve the leading + in an E.164 number. Writing a raw + in a query string can decode as a space.
cURL
curl --get "https://api.vobiz.ai/api/v1/Account/{auth_id}/numbers" \
--data-urlencode "page=1" \
--data-urlencode "per_page=20" \
--data-urlencode "search=+919876543210" \
-H "X-Auth-ID: {auth_id}" \
-H "X-Auth-Token: {auth_token}"
Response Example
Success Response (200 OK)
{
"items": [
{
"id": "aabbccdd-1234-5678-90ab-cdef12345678",
"account_id": "MA_XXXXXXXX",
"e164": "+919876543210",
"country": "IN",
"region": "Karnataka",
"capabilities": {
"voice": true,
"sms": false,
"mms": false,
"fax": false
},
"status": "active",
"provider": "",
"setup_fee": 100,
"monthly_fee": 300,
"currency": "INR",
"application_id": "20577609616603585",
"voice_enabled": true,
"tags": [],
"purchased_at": "2026-03-25T06:58:38.796024Z",
"is_blocked": false,
"created_at": "2026-03-25T18:30:00Z",
"updated_at": "2026-03-25T06:58:54.752187Z",
"is_trial_number": false,
"last_billing_date": "2026-03-25T06:58:38.796024Z",
"next_billing_date": "2026-04-25T06:58:38.796024Z",
"minimum_commitment_months": 0,
"aadhaar_verification_required": false,
"aadhaar_verified": false,
"source": "purchased"
}
],
"page": 1,
"per_page": 25,
"total": 24
}
Response structure
| Field | Description |
|---|---|
items | Array of phone number objects purchased by your account. |
page | Current page number. |
per_page | Number of items per page. |
total | Total count of purchased phone numbers. |
Phone number fields
Each object initems has these fields. Descriptions come from The Account Phone Number Object.
| Field | Type | Example | Description |
|---|---|---|---|
id | string | "aabbccdd-1234-5678-90ab-cdef12345678" | UUID identifier for the phone number. |
account_id | string | "MA_XXXXXXXX" | Auth ID (MA_ or SA_) of the account that owns this number. On a master account, this tells you whether a number belongs to the master or one of its sub-accounts. |
e164 | string | "+919876543210" | Phone number in E164 format (e.g., “+14155551234”). |
country | string | "IN" | Country code (e.g., “US”, “IN”). |
region | string | "Karnataka" | State/region code (e.g., “CA”, “MH”). Optional. |
capabilities | object | object | Object containing boolean flags for each capability: voice, sms, mms, fax. |
capabilities.voice | boolean | true | Whether the number supports voice calling. |
capabilities.sms | boolean | false | Whether the number supports SMS messaging. |
capabilities.mms | boolean | false | Whether the number supports MMS messaging. |
capabilities.fax | boolean | false | Whether the number supports fax. |
status | string | "active" | Current status of the number. One of: “active”, “pending_purchase”, “pending_release”, “released”, “blocked”. |
provider | string | "" | Upstream carrier/provider identifier. Often an empty string for Vobiz-stocked numbers. |
setup_fee | number | 100 | One-time setup fee charged when purchasing the number. |
monthly_fee | number | 300 | Monthly recurring fee for the number. |
currency | string | "INR" | Currency code for fees (e.g., “USD”, “INR”). |
application_id | string | "20577609616603585" | ID of the application the number is attached to, if any. Optional. |
voice_enabled | boolean | true | Whether voice routing is enabled for the number. |
tags | array | [] | Free-form string tags applied to the number. |
purchased_at | string | "2026-03-25T06:58:38.796024Z" | ISO 8601 timestamp when the number was purchased. Optional. |
is_blocked | boolean | false | Whether the number is currently blocked. |
created_at | string | "2026-03-25T18:30:00Z" | ISO 8601 timestamp when the number record was created. |
updated_at | string | "2026-03-25T06:58:54.752187Z" | ISO 8601 timestamp when the number record was last updated. |
is_trial_number | boolean | false | Whether the number was provisioned as a trial number. |
last_billing_date | string | "2026-03-25T06:58:38.796024Z" | ISO 8601 timestamp of the most recent monthly-fee billing. Optional. |
next_billing_date | string | "2026-04-25T06:58:38.796024Z" | ISO 8601 timestamp of the next scheduled monthly-fee billing. Optional. |
minimum_commitment_months | integer | 0 | Minimum commitment period in months. 0 if none. |
aadhaar_verification_required | boolean | false | Whether Aadhaar verification is required for this number (India). |
aadhaar_verified | boolean | false | Whether Aadhaar verification has been completed. |
source | string | "purchased" | How the number entered the account (e.g., purchased, inventory). |
Number status values
status | Meaning |
|---|---|
active | Number is active and available. |
pending_purchase | Purchase in progress. |
pending_release | Release in progress. |
released | Number has been released. |
blocked | Number is blocked. |
Only phone numbers owned by an account (with a populated
account_id) are returned. Numbers still in inventory (auth_id=NULL) are not included - browse those with List Inventory Numbers.Authorizations
Query Parameters
Was this page helpful?
⌘I
List phone numbers
curl --request GET \
--url https://api.vobiz.ai/api/v1/Account/{auth_id}/numbers \
--header 'X-Auth-ID: <api-key>' \
--header 'X-Auth-Token: <api-key>'import requests
url = "https://api.vobiz.ai/api/v1/Account/{auth_id}/numbers"
headers = {
"X-Auth-ID": "<api-key>",
"X-Auth-Token": "<api-key>"
}
response = requests.get(url, headers=headers)
print(response.text)const options = {
method: 'GET',
headers: {'X-Auth-ID': '<api-key>', 'X-Auth-Token': '<api-key>'}
};
fetch('https://api.vobiz.ai/api/v1/Account/{auth_id}/numbers', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));{
"items": [
{
"id": "aabbccdd-1234-5678-90ab-cdef12345678",
"account_id": "MA_XXXXXXXX",
"e164": "+919876543210",
"country": "IN",
"region": "Karnataka",
"capabilities": {
"voice": true,
"sms": false,
"mms": false,
"fax": false
},
"status": "active",
"provider": "",
"setup_fee": 100,
"monthly_fee": 300,
"currency": "INR",
"application_id": "20577609616603585",
"voice_enabled": true,
"tags": [],
"purchased_at": "2026-03-25T06:58:38.796024Z",
"is_blocked": false,
"created_at": "2026-03-25T18:30:00Z",
"updated_at": "2026-03-25T06:58:54.752187Z",
"is_trial_number": false,
"last_billing_date": "2026-03-25T06:58:38.796024Z",
"next_billing_date": "2026-04-25T06:58:38.796024Z",
"minimum_commitment_months": 0,
"aadhaar_verification_required": false,
"aadhaar_verified": false,
"source": "purchased"
},
{
"id": "11223344-5566-7788-99aa-bbccddeeff00",
"account_id": "MA_XXXXXXXX",
"e164": "+912271263984",
"country": "IN",
"region": "Mumbai",
"capabilities": {
"voice": true,
"sms": false,
"mms": false,
"fax": false
},
"status": "active",
"provider": "",
"setup_fee": 100,
"monthly_fee": 200,
"currency": "INR",
"application_id": "31985999331899218",
"voice_enabled": true,
"tags": [],
"purchased_at": "2026-03-25T10:25:30.672202Z",
"is_blocked": false,
"created_at": "2026-03-25T09:30:04.541115Z",
"updated_at": "2026-03-25T10:29:35.330503Z",
"is_trial_number": false,
"last_billing_date": "2026-03-25T10:25:30.672202Z",
"next_billing_date": "2026-04-25T10:25:30.672202Z",
"minimum_commitment_months": 0,
"aadhaar_verification_required": false,
"aadhaar_verified": false,
"source": "purchased"
}
],
"page": 1,
"per_page": 25,
"total": 24
}