Vobiz Messaging 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.

Building with code? Every step on this page has an API call - start with the Messaging API overview or jump to the number endpoints.

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 returns every number on your account that can send sms or mms, sorted by country then number:

cURL

curl "https://api.vobiz.ai/api/v1/sms/numbers" \
  -H "X-Auth-ID: MA_XXXXXXXX" \
  -H "X-Auth-Token: YOUR_AUTH_TOKEN"

Response - 200 OK

{
  "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.

US numbers must be registered before production traffic. A US local number needs an approved 10DLC campaign; a US toll-free number needs toll-free verification. Until then registration.status stays at not_registered or pending and sendable.usDomestic is false. Start at the compliance overview.

Where you can buy

List countries returns the countries that have numbers in stock right now, with the number types and capabilities on offer:

GET /numbers/countries - 200 OK

{
  "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.

Buy a number

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.

Search available numbers

Call Search available numbers. country is required; the other filters narrow the results.

cURL

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.

Response - 200 OK

{
  "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"}.

Purchase

Call Purchase a number with the e164 and country from the search result, plus numberKey when the result had one.

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" }'

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"])

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);

Response - 201 Created

{
  "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. A numbers.updated event with action: "purchased" is pushed over the WebSocket.

Attach a US local number to a 10DLC campaign with Add campaign numbers, or submit a US toll-free number for toll-free verification. Watch registration.status on the number until it reads approved.

Send

Use the number as from on Send a message. See SMS and MMS.

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 returns your purchases, newest first, each with its charges array - the full billing history of every number you have bought through Vobiz:

cURL

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 gives the number back and stops future monthly charges. URL-encode the + as %2B:

cURL

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.

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.

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.

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.

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.

Review

The request is reviewed in 1-3 business days. Support may ask for proof of ownership or a letter of authorisation.

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.

Cutover

After cutover the numbers appear in List your numbers and work as from values straight away. US numbers still need 10DLC or toll-free registration before production traffic.

Numbers you bring are managed by support rather than the purchase API: they have no entry in List purchases, and releasing one is a support request.

Build it with the Messaging API

Send your first SMS

Use a number from your account as from.

Number endpoints

List, search, buy and release numbers by API.

Sending SMS

Segments, idempotency and statuses.

Messaging webhooks

Get delivery receipts and replies on your server.

Compliance and registration

10DLC, toll-free and India DLT - what each number needs.

SMS

Send from your new number.

Coverage

Sender types and registration rules by destination country.

WebSocket

Live numbers.updated events for your dashboard.

Getting Started

Using Vobiz Platform

Messaging (SMS & RCS)

Compliance (India)

Tools

Vobiz Messaging Numbers

Numbers on your account

Where you can buy

Buy a number

Purchase errors

Billing

Purchase and charge statuses

Purchase history

Release a number

Bring your own numbers

Build it with the Messaging API

Send your first SMS

Number endpoints

Sending SMS

Messaging webhooks

Compliance and registration

SMS

Coverage

WebSocket

​Numbers on your account

​Where you can buy

​Buy a number

​Purchase errors

​Billing

​Purchase and charge statuses

​Purchase history

​Release a number

​Bring your own numbers

​Build it with the Messaging API

Send your first SMS

Number endpoints

Sending SMS

Messaging webhooks

​Related

Compliance and registration

SMS

Coverage

WebSocket

Numbers on your account

Where you can buy

Buy a number

Purchase errors

Billing

Purchase and charge statuses

Purchase history

Release a number

Bring your own numbers

Build it with the Messaging API

Related