Skip to main content
GET
List available numbers
Base URL: https://api.vobiz.ai/api/v1/Account/{auth_id}/WhatsApp Authentication: every request needs the X-Auth-ID: MA_XXXXXXXX and X-Auth-Token: YOUR_AUTH_TOKEN headers, and the {auth_id} in the path must be the account those credentials belong to. 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 with a one-time code. A bring_your_own channel shows verification_status pending until you complete it.
1

Connect

Connect the number with Create Channel, setting number_onboarding_mode to bring_your_own. The channel starts with verification_status pending.
2

Request a code

Send the same phone number, in the same E.164 format, and select sms or voice verification with the verify endpoint. The 6-digit code is valid for 10 minutes.
3

Confirm the code

Submit the code to the confirm endpoint. The channel on that number moves to verification_status verified.

List available numbers

Search Vobiz inventory for WhatsApp-capable phone numbers you can buy, with their fees. Buy one with Create number order.
cURL
200 OK
items is an empty array when no numbers match. Pass a number’s e164 as preferred_number to buy it.

Create number order

Buy preferred_number from Vobiz inventory. Returns 201 Created with the completed order. Then connect the number with Embedded signup (with number_provider set to vobiz) or Create Channel (with number_onboarding_mode set to buy_from_vobiz and the order id as number_order_id).
This buys a real number that is billed to your account. Run it only with your own credentials, when you mean to buy the number.
string
required
ISO country code of the number (e.g. IN).
string
required
Number type, for example local.
string
required
The number to buy, in E.164 format, from List available numbers.
string
State or region of the number, stored on the order.
string
default:"USD"
Billing currency, for example INR or USD. Defaults to USD.
cURL
201 Created
If a required field is missing, or the purchase can’t complete (for example, the number is no longer available or your balance is too low), the request returns 400 with an error message.

Number order object

string
Order ID (UUID). Pass it as number_order_id when you create the channel.
string
Your Vobiz account ID (MA_XXXXXXXX).
string
ISO country code, uppercased.
string
State or region for the number.
string
Number type, e.g. local.
string
The number you bought, in E.164 format.
string
The inventory purchase reference.
string
Name of the inventory the number was bought from.
string
Order state. A successful order returns completed.
number
Recurring monthly cost.
number
One-time setup cost.
string
Currency of the costs.
string
Why the order failed. Omitted when it did not.
string
Creation timestamp (RFC3339 UTC).
string
Last update timestamp (RFC3339 UTC).

Verify BYON - step 1

Start ownership verification for a number you already own. Choose sms or voice as the delivery method. Vobiz issues a 6-digit code that is valid for 10 minutes. Starting again for the same number replaces the earlier code. Returns 200 OK.
string
required
Phone number to verify, in E.164 format. Use the same format as on the channel.
string
required
Code delivery method: sms or voice. Case-insensitive.
cURL
200 OK

Confirm BYON verification - step 2

Submit the code from step 1 to complete verification. On success, the number is verified and a channel on that number moves to verification_status verified. A wrong or expired code returns 400. Returns 200 OK.
string
required
The number you started verifying, exactly as you sent it in step 1.
string
required
The 6-digit code from step 1.
cURL
200 OK

Authorizations

X-Auth-ID
string
header
required

Your Vobiz account Auth ID (MA_XXXXXXXX).

X-Auth-Token
string
header
required

Your Vobiz account Auth Token.

Path Parameters

auth_id
string
required

Your account Auth ID. It must match the X-Auth-ID header.

Example:

"MA_XXXXXXXX"

Query Parameters

country
string

ISO country code in uppercase, for example IN. Omit it to list every country.

Example:

"IN"

region
string

Region exactly as it appears in region, for example Karnataka or 92 Series. The match is case-sensitive.

Example:

"Karnataka"

Response

Numbers you can buy. Empty items when none match.

items
object[]
required

Up to 50 numbers you can buy. Empty array when none match.