> ## 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 Numbers

> List, search, buy, register and release SMS and MMS numbers on Vobiz - number fields explained, available countries, inventory search, purchase billing and status, release, and how to bring your own numbers.

A messaging number is the `from` value on SMS and MMS sends and the destination for replies. This page covers the numbers already on your account, searching and buying new ones, what you pay and when, releasing a number, and bringing numbers you already own.

<Tip>
  Building with code? Every step on this page has an API call - start with the [Messaging API overview](/docs/sms/overview) or jump to the [number endpoints](/docs/sms/api/numbers/list-numbers).
</Tip>

In the Vobiz Console the same flows live under **SMS & RCS → Numbers**, with **Buy a number** and **Bring your numbers** tabs.

## Numbers on your account

[List your numbers](/docs/sms/api/numbers/list-numbers) returns every number on your account that can send `sms` or `mms`, sorted by country then number:

```bash cURL theme={null}
curl "https://api.vobiz.ai/api/v1/sms/numbers" \
  -H "X-Auth-ID: MA_XXXXXXXX" \
  -H "X-Auth-Token: YOUR_AUTH_TOKEN"
```

```json Response - 200 OK theme={null}
{
  "numbers": [
    {
      "e164": "+14155550100",
      "provider": "internal",
      "countryCode": "US",
      "channels": ["sms", "mms"],
      "type": "VIRTUAL_LONG_NUMBER",
      "capabilities": ["SMS", "VOICE", "MMS"],
      "tenDlc": {
        "campaignId": "9b2e1c40-8a3d-4f5e-9c1a-7d6b2e8f4a01",
        "campaignName": "Order notifications",
        "stage": "REGISTERED"
      },
      "tollFree": false,
      "registration": {
        "kind": "10dlc",
        "status": "approved",
        "campaignId": "9b2e1c40-8a3d-4f5e-9c1a-7d6b2e8f4a01",
        "campaignName": "Order notifications",
        "stage": "REGISTERED"
      },
      "lastMessage": {
        "status": "delivered",
        "errorCode": "",
        "errorMessage": "",
        "to": "+14155550123",
        "createdAt": "2026-10-16T21:23:02.676996Z"
      },
      "sendable": { "international": true, "usDomestic": true }
    }
  ]
}
```

| Field | Meaning |
| - | - |
| `e164` | The number with a leading `+`. |
| `provider` | Internal routing identifier; do not rely on its value. |
| `countryCode` | ISO 3166-1 alpha-2 country of the number. |
| `channels` | Lower-case channels the number can send: `sms`, `mms`, `rcs`. |
| `type` | Number type, for example `VIRTUAL_LONG_NUMBER`, `TOLL_FREE`, `SHORT_CODE`. |
| `capabilities` | Upper-case capabilities from inventory, for example `SMS`, `MMS`, `VOICE`. |
| `tenDlc` | The most relevant 10DLC or toll-free campaign the number is attached to (`campaignId`, `campaignName`, `stage`), or `null`. |
| `tollFree` | `true` for US toll-free numbers (area codes 800, 833, 844, 855, 866, 877, 888). |
| `registration` | What the number needs and where it stands. `kind` is `10dlc` (US local), `toll_free` (US toll-free) or `none`. `status` is `not_registered`, `draft`, `pending`, `approved`, `rejected` or `not_required`. The campaign fields repeat the campaign that drives the status, or are empty. |
| `lastMessage` | The latest outbound message from this number (`status`, `errorCode`, `errorMessage`, `to`, `createdAt`), or `null`. A quick health check per number. |
| `sendable` | `usDomestic` is `true` when the number is cleared to send to US recipients given its registration. `international` is `true` when it is cleared to send outside the US. |

<Note>
  US numbers must be registered before production traffic. A US local number needs an approved [10DLC campaign](/docs/sms/compliance/us-10dlc-campaigns); a US toll-free number needs [toll-free verification](/docs/sms/compliance/us-toll-free). Until then `registration.status` stays at `not_registered` or `pending` and `sendable.usDomestic` is `false`. Start at the [compliance overview](/docs/sms/compliance/overview).
</Note>

## Where you can buy

[List countries](/docs/sms/api/numbers/list-countries) returns the countries that have numbers in stock right now, with the number types and capabilities on offer:

```json GET /numbers/countries - 200 OK theme={null}
{
  "countries": [
    { "country": "CA", "name": "Canada", "types": ["local"], "capabilities": ["SMS", "MMS", "VOICE"] },
    { "country": "GB", "name": "United Kingdom", "types": ["local"], "capabilities": ["SMS"] },
    { "country": "US", "name": "United States", "types": ["local"], "capabilities": ["SMS", "MMS", "VOICE"] }
  ],
  "updatedAt": "2026-10-18T03:19:11.016753Z",
  "ready": true
}
```

* `ready` is `true` once the stock snapshot has been taken. Until then `countries` is empty and `updatedAt` is `null`; retry shortly.
* The snapshot is refreshed every 12 hours; `updatedAt` tells you when.
* `types` values are `local`, `mobile`, `tollfree` or `shortcode`.
* Self-serve purchase is available in the United States, Canada and the United Kingdom. This endpoint is always the live list.
* India does not appear here. Indian traffic uses DLT-registered sender IDs instead of long codes - see [India DLT](/docs/sms/compliance/india-dlt).

## Buy a number

<Warning>
  Buying a number debits your balance immediately (setup fee plus the first month) and starts a monthly renewal. Run the purchase call only with your own credentials and when you intend to own the number.
</Warning>

<Steps>
  <Step title="Search available numbers">
    Call [Search available numbers](/docs/sms/api/numbers/search-available-numbers). `country` is required; the other filters narrow the results.

    ```bash cURL theme={null}
    curl -G "https://api.vobiz.ai/api/v1/sms/numbers/available" \
      -H "X-Auth-ID: MA_XXXXXXXX" \
      -H "X-Auth-Token: YOUR_AUTH_TOKEN" \
      --data-urlencode "country=US" \
      --data-urlencode "capabilities=SMS,MMS" \
      --data-urlencode "areaCode=415" \
      --data-urlencode "limit=10"
    ```

    | Query | Notes |
    | - | - |
    | `country` | Required. ISO 3166-1 alpha-2, for example `US`, `CA`, `GB`. |
    | `capabilities` | Comma-separated `SMS` and/or `MMS`. Default `SMS`. |
    | `areaCode` | Exactly 3 digits. US and CA only. |
    | `contains` | 1-15 digits that must appear in the number. |
    | `limit` | 1-100, default 10. Results are capped at 10 per request. |

    ```json Response - 200 OK theme={null}
    {
      "numbers": [
        {
          "e164": "+14155550100",
          "numberKey": "",
          "countryCode": "US",
          "type": "VIRTUAL_LONG_NUMBER",
          "capabilities": ["MMS", "SMS", "VOICE"],
          "network": "",
          "setupPrice": 1,
          "monthlyPrice": 1,
          "currency": "USD",
          "providerRequiresDocuments": false
        }
      ],
      "page": 0,
      "limit": 10,
      "hasMore": false
    }
    ```

    `setupPrice` and `monthlyPrice` are in your account `currency`. `numberKey` is an opaque inventory key that some countries need at purchase; pass it back unchanged when it is non-empty. `providerRequiresDocuments: true` means the country asks for regulatory documents - contact support before buying.

    Searching `country=IN` returns an empty list with a hint: `"hint": "India uses DLT sender IDs, not long codes"`. A country outside the self-serve list returns `422 {"error":"SMS numbers are not sold for country XX"}`.
  </Step>

  <Step title="Purchase">
    Call [Purchase a number](/docs/sms/api/numbers/purchase-number) with the `e164` and `country` from the search result, plus `numberKey` when the result had one.

    <CodeGroup>
      ```bash cURL theme={null}
      curl -X POST "https://api.vobiz.ai/api/v1/sms/numbers/purchase" \
        -H "X-Auth-ID: MA_XXXXXXXX" \
        -H "X-Auth-Token: YOUR_AUTH_TOKEN" \
        -H "Content-Type: application/json" \
        -d '{ "e164": "+14155550100", "country": "US" }'
      ```

      ```python Python theme={null}
      import requests

      resp = requests.post(
          "https://api.vobiz.ai/api/v1/sms/numbers/purchase",
          headers={
              "X-Auth-ID": "MA_XXXXXXXX",
              "X-Auth-Token": "YOUR_AUTH_TOKEN",
              "Content-Type": "application/json",
          },
          json={"e164": "+14155550100", "country": "US"},
      )
      resp.raise_for_status()
      purchase = resp.json()["purchase"]
      print(purchase["e164"], purchase["status"], purchase["nextBillingAt"])
      ```

      ```javascript Node theme={null}
      const resp = await fetch("https://api.vobiz.ai/api/v1/sms/numbers/purchase", {
        method: "POST",
        headers: {
          "X-Auth-ID": "MA_XXXXXXXX",
          "X-Auth-Token": "YOUR_AUTH_TOKEN",
          "Content-Type": "application/json",
        },
        body: JSON.stringify({ e164: "+14155550100", country: "US" }),
      });
      const { purchase, number } = await resp.json();
      console.log(purchase.status, number.e164);
      ```
    </CodeGroup>

    ```json Response - 201 Created theme={null}
    {
      "purchase": {
        "id": "9b2e1c40-8a3d-4f5e-9c1a-7d6b2e8f4a01",
        "accountId": "MA_XXXXXXXX",
        "provider": "internal",
        "e164": "+14155550100",
        "countryCode": "US",
        "type": "VIRTUAL_LONG_NUMBER",
        "capabilities": ["VOICE", "SMS", "MMS"],
        "setupAmount": 1,
        "monthlyAmount": 1,
        "currency": "USD",
        "status": "purchased",
        "purchasedAt": "2026-10-18T09:06:44.490815Z",
        "nextBillingAt": "2026-11-18T09:06:44.490815Z",
        "releasedAt": null,
        "createdAt": "2026-10-18T09:06:42.929265Z",
        "updatedAt": "2026-10-18T09:06:44.491587Z",
        "charges": [
          {
            "purchaseId": "9b2e1c40-8a3d-4f5e-9c1a-7d6b2e8f4a01",
            "kind": "purchase",
            "periodStart": "2026-10-18T09:06:42.933584Z",
            "amount": 2,
            "currency": "USD",
            "status": "paid",
            "reference": "sms_number_purchase:9b2e1c40-8a3d-4f5e-9c1a-7d6b2e8f4a01",
            "attempts": 1,
            "attemptedAt": "2026-10-18T09:06:42.933584Z"
          }
        ]
      },
      "number": {
        "id": 42,
        "e164": "+14155550100",
        "provider": "internal",
        "channelCapabilities": ["sms", "mms"],
        "accountId": "MA_XXXXXXXX",
        "countryCode": "US",
        "createdAt": "2026-10-18T09:06:44.400000Z"
      }
    }
    ```

    The number is routed to your account at once and appears in [List your numbers](/docs/sms/api/numbers/list-numbers). A `numbers.updated` event with `action: "purchased"` is pushed over the [WebSocket](/docs/sms/websocket).
  </Step>

  <Step title="Register it (US)">
    Attach a US local number to a 10DLC campaign with [Add campaign numbers](/docs/sms/api/10dlc/add-campaign-numbers), or submit a US toll-free number for [toll-free verification](/docs/sms/compliance/us-toll-free). Watch `registration.status` on the number until it reads `approved`.
  </Step>

  <Step title="Send">
    Use the number as `from` on [Send a message](/docs/sms/api/messages/send-message). See [SMS](/docs/sms/channels/sms) and [MMS](/docs/sms/channels/mms).
  </Step>
</Steps>

### Purchase errors

| Status | When |
| - | - |
| `400` | `e164 must be a number in E.164 format`, `country is required`, `country must be an ISO 3166-1 alpha-2 code`, `number does not belong to the given country`. |
| `402` | `insufficient balance` - top up and retry. |
| `409` | `you already have this number`, `number is not available`, `number is no longer available`, `a purchase of this number is already in progress`. |
| `422` | `India uses DLT sender IDs, not long codes`, `SMS numbers are not sold for country XX`, `this country needs regulatory documents; contact support`, `number is not SMS-capable`. |
| `502` | The upstream purchase did not complete. The message states whether your wallet was refunded automatically or the refund is being processed by support. |
| `503` | `billing is unavailable; try again later` - retry with the same request. |

## Billing

| Charge | When | `charges[].kind` |
| - | - | - |
| Setup fee + first month | At purchase, debited from your balance before the number is bought | `purchase` |
| Monthly renewal | Every month from `purchasedAt`; the next date is `nextBillingAt` | `rental` |

* A renewal that fails for lack of balance is retried. `charges[].attempts` and `attemptedAt` show the retry history, and the charge `status` moves from `pending` to `paid` or `failed`.
* After 7 days of failed renewal the purchase `status` becomes `past_due`. The number is not released automatically. Top up your balance and the next retry clears the charge, returning the purchase to `purchased`.
* If the upstream purchase fails after the debit, the charge is refunded and the purchase ends in `refunded` or `failed`.

### Purchase and charge statuses

| Purchase `status` | Meaning |
| - | - |
| `pending` | Created, not yet debited. |
| `debited` | Setup and first month taken; the upstream purchase is in progress. |
| `purchased` | Live on your account and billing monthly. |
| `past_due` | A monthly renewal has been failing for more than 7 days. |
| `failed` | The purchase did not complete. |
| `refunded` | The debit was returned after a failed purchase. |
| `released` | You released the number. `releasedAt` is set and `nextBillingAt` is `null`. |

Charge `status` is one of `pending`, `paid`, `failed`, `refunded`.

### Purchase history

[List purchases](/docs/sms/api/numbers/list-purchases) returns your purchases, newest first, each with its `charges` array - the full billing history of every number you have bought through Vobiz:

```bash cURL theme={null}
curl "https://api.vobiz.ai/api/v1/sms/numbers/purchases" \
  -H "X-Auth-ID: MA_XXXXXXXX" \
  -H "X-Auth-Token: YOUR_AUTH_TOKEN"
```

## Release a number

[Release a number](/docs/sms/api/numbers/release-number) gives the number back and stops future monthly charges. URL-encode the `+` as `%2B`:

```bash cURL theme={null}
curl -X POST "https://api.vobiz.ai/api/v1/sms/numbers/%2B14155550100/release" \
  -H "X-Auth-ID: MA_XXXXXXXX" \
  -H "X-Auth-Token: YOUR_AUTH_TOKEN"
```

The response is `200` with `{"purchase": ...}` in status `released`.

<Warning>
  Release takes effect immediately and there is no refund of the current month. Inbound messages to the number stop as soon as it is released.
</Warning>

| Status | When |
| - | - |
| `404` | `number not found` on your account. |
| `409` | `this number was not bought through the console; contact support to release it` (for example a number you brought yourself), or `the purchase of this number is still in progress`. |
| `502` | `number provider could not release the number; try again later`. |

A `numbers.updated` event with `action: "released"` is pushed over the [WebSocket](/docs/sms/websocket).

## Bring your own numbers

If you already own SMS-capable numbers with another carrier, you can move them to Vobiz instead of buying new ones.

<Steps>
  <Step title="Submit the request">
    In the Vobiz Console, open **SMS & RCS → Numbers → Bring your numbers**, list the numbers and the country, and submit. This opens a support ticket on your account.
  </Step>

  <Step title="Review">
    The request is reviewed in 1-3 business days. Support may ask for proof of ownership or a letter of authorisation.
  </Step>

  <Step title="Provisioning">
    Provisioning takes 3-14 days depending on the country and the losing carrier. Your numbers keep working with the current provider until cutover, so there is no gap in service.
  </Step>

  <Step title="Cutover">
    After cutover the numbers appear in [List your numbers](/docs/sms/api/numbers/list-numbers) and work as `from` values straight away. US numbers still need [10DLC or toll-free registration](/docs/sms/compliance/overview) before production traffic.
  </Step>
</Steps>

Numbers you bring are managed by support rather than the purchase API: they have no entry in [List purchases](/docs/sms/api/numbers/list-purchases), and releasing one is a support request.

## Build it with the Messaging API

<CardGroup cols={2}>
  <Card title="Send your first SMS" icon="rocket" href="/docs/sms/quickstart">
    Use a number from your account as `from`.
  </Card>

  <Card title="Number endpoints" icon="code" href="/docs/sms/api/numbers/list-numbers">
    List, search, buy and release numbers by API.
  </Card>

  <Card title="Sending SMS" icon="message" href="/docs/sms/channels/sms">
    Segments, idempotency and statuses.
  </Card>

  <Card title="Messaging webhooks" icon="webhook" href="/docs/sms/webhooks">
    Get delivery receipts and replies on your server.
  </Card>
</CardGroup>

## Related

<CardGroup cols={2}>
  <Card title="Compliance and registration" icon="shield-check" href="/docs/sms/compliance/overview">
    10DLC, toll-free and India DLT - what each number needs.
  </Card>

  <Card title="SMS" icon="message" href="/docs/sms/channels/sms">
    Send from your new number.
  </Card>

  <Card title="Coverage" icon="globe" href="/docs/sms/api/coverage/list-coverage">
    Sender types and registration rules by destination country.
  </Card>

  <Card title="WebSocket" icon="bolt" href="/docs/sms/websocket">
    Live `numbers.updated` events for your dashboard.
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.