Numbers API - Vobiz

GET

api

messaging

numbers

availability

Numbers API

curl --request GET \
  --url https://api.vobiz.ai/api/v1/messaging/numbers/whatsapp/availability \
  --header 'Content-Type: application/json' \
  --header 'X-Auth-Token: <api-key>' \
  --data '
{
  "country_code": "<string>",
  "region": "<string>",
  "number_type": "<string>",
  "currency": "<string>",
  "phone_number": "<string>",
  "verification_method": "<string>",
  "otp_code": "<string>"
}
'

import requests

url = "https://api.vobiz.ai/api/v1/messaging/numbers/whatsapp/availability"

payload = {
    "country_code": "<string>",
    "region": "<string>",
    "number_type": "<string>",
    "currency": "<string>",
    "phone_number": "<string>",
    "verification_method": "<string>",
    "otp_code": "<string>"
}
headers = {
    "X-Auth-Token": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.get(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'GET',
  headers: {'X-Auth-Token': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    country_code: '<string>',
    region: '<string>',
    number_type: '<string>',
    currency: '<string>',
    phone_number: '<string>',
    verification_method: '<string>',
    otp_code: '<string>'
  })
};

fetch('https://api.vobiz.ai/api/v1/messaging/numbers/whatsapp/availability', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "id": "<string>",
  "account_id": "<string>",
  "country_code": "<string>",
  "region": "<string>",
  "number_type": "<string>",
  "selected_phone_number": "<string>",
  "provider_order_id": "<string>",
  "provider_name": "<string>",
  "status": "<string>",
  "monthly_cost": 123,
  "setup_cost": 123,
  "currency": "<string>",
  "failure_reason": "<string>",
  "created_at": "<string>",
  "updated_at": "<string>"
}

Base URL: https://api.vobiz.ai/api/v1/messaging Authentication: every request requires X-Auth-ID: MA_XXXXXXXX and X-Auth-Token: <token> headers (a Authorization: Bearer <JWT> header is also accepted). Send Content-Type: application/json on requests with a body. Get your credentials from console.vobiz.ai.

BYON verification flow

If you already have a WhatsApp Business number, the BYON (Bring Your Own Number) flow verifies ownership via OTP before connecting it to Vobiz.

Request OTP

Enter your phone number and select sms or voice verification with the verify endpoint.

Confirm OTP

Receive the OTP code on your number and submit it to the confirm endpoint.

Connect

Once verified, connect the number with Create Channel.

List available numbers

GET https://api.vobiz.ai/api/v1/messaging/numbers/whatsapp/availability

Search for WhatsApp-capable phone numbers available for purchase.

string

required

ISO country code (e.g. IN, US).

string

State/region filter.

cURL

curl -X GET \
  "https://api.vobiz.ai/api/v1/messaging/numbers/whatsapp/availability?country=IN&region=MH" \
  -H "X-Auth-ID: MA_XXXXXXXX" \
  -H "X-Auth-Token: {auth_token}"

200 OK

{
  "items": [
    {
      "e164": "+919876543210",
      "country": "IN",
      "region": "MH",
      "setup_fee": 500,
      "monthly_fee": 250,
      "currency": "INR"
    }
  ]
}

Create number order

POST https://api.vobiz.ai/api/v1/messaging/numbers/whatsapp/orders

Purchase a new WhatsApp-capable phone number. After the order is fulfilled, use Create Channel to connect it to your WABA. Returns 201 Created.

string

required

ISO country code (e.g. IN).

string

required

State/region for the number.

string

required

Number type. Currently local.

string

Preferred number in E.164 format. Optional.

string

required

Billing currency: INR or USD.

cURL

curl -X POST \
  "https://api.vobiz.ai/api/v1/messaging/numbers/whatsapp/orders" \
  -H "X-Auth-ID: MA_XXXXXXXX" \
  -H "X-Auth-Token: {auth_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "country_code": "IN",
    "region": "MH",
    "number_type": "local",
    "preferred_number": "+919876543210",
    "currency": "INR"
  }'

201 Created

{
  "id": "b3d1c4a2-5f6e-4a8b-9c0d-1e2f3a4b5c6d",
  "account_id": "MA_XXXXXXXX",
  "country_code": "IN",
  "region": "MH",
  "number_type": "local",
  "selected_phone_number": "+919876543210",
  "provider_order_id": "ord_meta_8841",
  "provider_name": "meta_direct",
  "status": "pending",
  "monthly_cost": 250,
  "setup_cost": 500,
  "currency": "INR",
  "failure_reason": null,
  "created_at": "2026-03-01T10:00:00Z",
  "updated_at": "2026-03-01T10:00:00Z"
}

Number order object

string

Unique order identifier (UUID).

string

Your Vobiz account ID (MA_XXXXXXXX).

string

ISO country code.

string

State/region for the number.

string

Number type, e.g. local.

string

Allocated phone number in E.164 format.

string

Upstream provider’s order identifier.

string

Upstream provider name.

string

Order status: pending, completed, failed, or cancelled.

number

Recurring monthly cost.

number

One-time setup cost.

string

Billing currency.

string

Reason the order failed, if status is failed. Otherwise null.

string

Creation timestamp (RFC3339 UTC).

string

Last update timestamp (RFC3339 UTC).

Verify BYON - step 1

POST https://api.vobiz.ai/api/v1/messaging/numbers/whatsapp/bring-your-own/verify

Initiate OTP verification for a number you already own. Choose sms or voice as the delivery method. Returns 200 OK.

string

required

Phone number to verify, in E.164 format.

string

required

OTP delivery method: sms or voice.

cURL

curl -X POST \
  "https://api.vobiz.ai/api/v1/messaging/numbers/whatsapp/bring-your-own/verify" \
  -H "X-Auth-ID: MA_XXXXXXXX" \
  -H "X-Auth-Token: {auth_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "phone_number": "+919876543210",
    "verification_method": "sms"
  }'

200 OK

{
  "id": "a1c2e3f4-5678-49ab-bcde-f01234567890",
  "phone_number": "+919876543210",
  "status": "pending",
  "expires_at": "2026-03-01T10:10:00Z"
}

Confirm BYON verification - step 2

POST https://api.vobiz.ai/api/v1/messaging/numbers/whatsapp/bring-your-own/confirm

Submit the OTP received in step 1 to complete verification. On success, the number is confirmed and ready to connect via Create Channel. Returns 200 OK.

string

required

Phone number being verified, in E.164 format.

string

required

The OTP code received in step 1.

cURL

curl -X POST \
  "https://api.vobiz.ai/api/v1/messaging/numbers/whatsapp/bring-your-own/confirm" \
  -H "X-Auth-ID: MA_XXXXXXXX" \
  -H "X-Auth-Token: {auth_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "phone_number": "+919876543210",
    "otp_code": "123456"
  }'

200 OK

{
  "status": "verified",
  "message": "Number verified successfully"
}

Numbers API

curl --request GET \
  --url https://api.vobiz.ai/api/v1/messaging/numbers/whatsapp/availability \
  --header 'Content-Type: application/json' \
  --header 'X-Auth-Token: <api-key>' \
  --data '
{
  "country_code": "<string>",
  "region": "<string>",
  "number_type": "<string>",
  "currency": "<string>",
  "phone_number": "<string>",
  "verification_method": "<string>",
  "otp_code": "<string>"
}
'

import requests

url = "https://api.vobiz.ai/api/v1/messaging/numbers/whatsapp/availability"

payload = {
    "country_code": "<string>",
    "region": "<string>",
    "number_type": "<string>",
    "currency": "<string>",
    "phone_number": "<string>",
    "verification_method": "<string>",
    "otp_code": "<string>"
}
headers = {
    "X-Auth-Token": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.get(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'GET',
  headers: {'X-Auth-Token': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    country_code: '<string>',
    region: '<string>',
    number_type: '<string>',
    currency: '<string>',
    phone_number: '<string>',
    verification_method: '<string>',
    otp_code: '<string>'
  })
};

fetch('https://api.vobiz.ai/api/v1/messaging/numbers/whatsapp/availability', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "id": "<string>",
  "account_id": "<string>",
  "country_code": "<string>",
  "region": "<string>",
  "number_type": "<string>",
  "selected_phone_number": "<string>",
  "provider_order_id": "<string>",
  "provider_name": "<string>",
  "status": "<string>",
  "monthly_cost": 123,
  "setup_cost": 123,
  "currency": "<string>",
  "failure_reason": "<string>",
  "created_at": "<string>",
  "updated_at": "<string>"
}

​BYON verification flow

​List available numbers

​Create number order

​Number order object

​Verify BYON - step 1

​Confirm BYON verification - step 2

BYON verification flow

List available numbers

Create number order

Number order object

Verify BYON - step 1

Confirm BYON verification - step 2