Vobiz Messaging API - Numbers

The Numbers endpoints manage the phone numbers you send SMS and MMS from. You use them to see which numbers are on your account and where each one can send, to search the inventory and buy new numbers, and to release numbers you no longer need. Every purchase keeps its full billing history, so the same endpoints also let you reconcile setup and rental charges.

Purchase a number and Release a number move money. A purchase debits the setup fee and first month from your wallet, and rental renews every month until you release. A release is permanent and is not refunded. Run them only with your own credentials, after you have confirmed the number and the price.

The number object

GET /numbers returns each messaging number on your account in this shape.

Field	Type	Meaning
`e164`	string	The number in E.164 format. Use it as `from` when you send.
`countryCode`	string	Upper-case ISO 3166-1 alpha-2 code, for example `US`. Empty when unknown.
`channels`	string[]	Channels routed on the number: `sms`, `mms`, `rcs`.
`type`	string	Inventory type, for example `VIRTUAL_LONG_NUMBER`, `SHORT_CODE` or `TOLL_FREE`.
`capabilities`	string[]	Upper-case labels such as `SMS`, `MMS`, `VOICE`.
`tollFree`	boolean	`true` for US toll-free numbers.
`tenDlc`	object or `null`	The most relevant US campaign attached: `campaignId`, `campaignName`, `stage`.
`registration`	object	US registration state: `kind` (`10dlc`, `toll_free`, `none`), `status`, and the campaign fields.
`lastMessage`	object or `null`	The latest outbound message: `status`, `errorCode`, `errorMessage`, `to`, `createdAt`.
`sendable`	object	Where the number can send right now: `international` and `usDomestic` booleans.
`provider`	string	Internal routing identifier; do not rely on its value.

registration.status is one of not_registered, draft, pending, approved, rejected or not_required. A US number reports sendable.usDomestic: true only once its 10DLC campaign is approved or its toll-free verification is complete.

Endpoints

Method	Endpoint	What it does
`GET`	`/numbers`	List the messaging numbers on your account, with registration state and where each can send.
`GET`	`/numbers/countries`	List the countries where numbers are in stock, with types and capabilities.
`GET`	`/numbers/available`	Search the inventory in one country, with prices in your wallet currency.
`POST`	`/numbers/purchase`	Buy a number and route it to your account. Spends money.
`GET`	`/numbers/purchases`	List the numbers you have bought, newest first, with every wallet charge.
`POST`	`/numbers/{e164}/release`	Release a number you bought. Permanent, no refund.

How buying a number works

Find a country

Call GET /numbers/countries. The list is a snapshot that refreshes in the background; while ready is false, retry after a few seconds. India is not listed, because Indian traffic uses DLT-registered sender IDs (see India DLT).

Search the inventory

Call GET /numbers/available with country, and optionally capabilities (SMS, MMS), areaCode (US and CA) and contains. Each search returns up to 10 numbers with setupPrice, monthlyPrice and currency.

Buy it

Send the chosen e164 and country to POST /numbers/purchase. Include numberKey when the search result has a non-empty one, as Canadian and UK numbers do; US numbers are bought by e164 alone.

A new US number can send internationally straight away. To reach US recipients, attach it to an approved 10DLC campaign or complete toll-free verification, then confirm sendable.usDomestic is true.

Search example

cURL

curl "https://api.vobiz.ai/api/v1/sms/numbers/available?country=US&capabilities=SMS,MMS&areaCode=415" \
  -H "X-Auth-ID: MA_XXXXXXXX" \
  -H "X-Auth-Token: YOUR_AUTH_TOKEN"

Response

{
  "numbers": [
    {
      "e164": "+14155550100",
      "numberKey": "",
      "countryCode": "US",
      "type": "VIRTUAL_LONG_NUMBER",
      "capabilities": ["SMS", "MMS", "VOICE"],
      "network": "",
      "setupPrice": 1,
      "monthlyPrice": 1,
      "currency": "USD",
      "providerRequiresDocuments": false
    }
  ],
  "page": 0,
  "limit": 10,
  "hasMore": false
}

Search rules

Parameter	Rule	Error (`400`)
`country`	Required ISO 3166-1 alpha-2 code, case-insensitive.	`country is required` / `country must be an ISO 3166-1 alpha-2 code`
`capabilities`	`SMS`, `MMS` or `SMS,MMS`. Defaults to `SMS`.	`capabilities must be SMS and/or MMS`
`areaCode`	Exactly three digits, US and CA only.	`areaCode must be 3 digits` / `areaCode is only supported for US and CA`
`contains`	1 to 15 digits; a leading `+` is ignored.	`contains must be 1-15 digits`
`limit`	`1` to `100`, default `10`. At most 10 numbers come back per search.	`limit must be between 1 and 100`
`page`	Zero-based, default `0`.	`page must be >= 0`

A country Vobiz does not sell numbers in returns 422 with SMS numbers are not sold for country XX. A search for country=IN returns an empty list and a hint.

Billing and lifecycle

Each purchase in GET /numbers/purchases has a status and a charges array.

Purchase `status`	Meaning
`pending`	Created, not yet charged.
`debited`	Setup fee and first month charged; the purchase is in progress.
`purchased`	Active on your account and renewing monthly on `nextBillingAt`.
`past_due`	A monthly renewal has been failing for more than 7 days. Top up your balance to clear it.
`failed`	The purchase did not complete.
`refunded`	The charge was returned to your wallet after a failed purchase.
`released`	You released the number. `releasedAt` is set and `nextBillingAt` is `null`.

Each charge has kind (purchase for setup plus first month, rental for each renewal) and status (pending, paid, failed, refunded). Released numbers stay in the list, so it is a complete billing history. To release a number, URL-encode the + in the path as %2B, for example POST /numbers/%2B14155550100/release. The number stops sending and receiving immediately. Numbers that were not bought through Vobiz return 409; contact support to release those.

Numbers guide

Buy, register and bring your own numbers, with console steps.

US 10DLC campaigns

Attach US long numbers to an approved campaign.

US toll-free verification

Verify toll-free numbers for US traffic.

Messaging compliance

Registration rules by country before you send.

Getting Started

API Reference

Guides

Vobiz Messaging API - Numbers

The number object

Endpoints

How buying a number works

Search example

Search rules

Billing and lifecycle

Numbers guide

US 10DLC campaigns

US toll-free verification

Messaging compliance

​The number object

​Endpoints

​How buying a number works

​Search example

​Search rules

​Billing and lifecycle

​Related

Numbers guide

US 10DLC campaigns

US toll-free verification

Messaging compliance

The number object

Endpoints

How buying a number works

Search example

Search rules

Billing and lifecycle

Related