> ## Documentation Index
> Fetch the complete documentation index at: https://www.vobiz.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Vobiz Messaging API - Numbers
> List the SMS and MMS numbers on your Vobiz account, see where each one can send, search the inventory by country and area code, buy and release numbers, and read their billing history.
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](/docs/sms/api/numbers/purchase-number) and [Release a number](/docs/sms/api/numbers/release-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`](/docs/sms/api/numbers/list-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`](/docs/sms/api/numbers/list-numbers) | List the messaging numbers on your account, with registration state and where each can send. |
| `GET` | [`/numbers/countries`](/docs/sms/api/numbers/list-countries) | List the countries where numbers are in stock, with types and capabilities. |
| `GET` | [`/numbers/available`](/docs/sms/api/numbers/search-available-numbers) | Search the inventory in one country, with prices in your wallet currency. |
| `POST` | [`/numbers/purchase`](/docs/sms/api/numbers/purchase-number) | Buy a number and route it to your account. Spends money. |
| `GET` | [`/numbers/purchases`](/docs/sms/api/numbers/list-purchases) | List the numbers you have bought, newest first, with every wallet charge. |
| `POST` | [`/numbers/{e164}/release`](/docs/sms/api/numbers/release-number) | Release a number you bought. Permanent, no refund. |
## How buying a number works
Call [`GET /numbers/countries`](/docs/sms/api/numbers/list-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](/docs/sms/compliance/india-dlt)).
Call [`GET /numbers/available`](/docs/sms/api/numbers/search-available-numbers) 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`.
Send the chosen `e164` and `country` to [`POST /numbers/purchase`](/docs/sms/api/numbers/purchase-number). 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](/docs/sms/compliance/us-10dlc-campaigns) or complete [toll-free verification](/docs/sms/compliance/us-toll-free), then confirm `sendable.usDomestic` is `true`.
### Search example
```bash cURL theme={null}
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"
```
```json Response theme={null}
{
"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`](/docs/sms/api/numbers/list-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.
## Related
Buy, register and bring your own numbers, with console steps.
Attach US long numbers to an approved campaign.
Verify toll-free numbers for US traffic.
Registration rules by country before you send.
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.