> ## 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. # List your numbers > Returns every number on your account that is routed for SMS or MMS, sorted by `countryCode` and then `e164`. Each number carries its US registration state, the last message it sent and a `sendable` summary of where it can send right now. ## OpenAPI ````yaml openapi-sms.yaml GET /numbers openapi: 3.0.3 info: title: Vobiz Messaging API description: > Send and receive SMS, MMS and RCS messages, buy messaging numbers, register for US 10DLC and toll-free, run broadcasts, manage conversations, opt-outs and webhooks. **Base URL:** `https://api.vobiz.ai/api/v1/sms` **Authentication:** every request needs the `X-Auth-ID` and `X-Auth-Token` headers. The account is taken from your credentials; you never put an account ID in a path or body. Field names in this API are camelCase. version: '1.0' contact: email: support@vobiz.ai url: https://vobiz.ai servers: - url: https://api.vobiz.ai/api/v1/sms description: Production security: - AuthID: [] AuthToken: [] tags: - name: Messages description: Send messages and inspect their delivery state. - name: Numbers description: >- Messaging-capable numbers on your account, inventory search, purchase and release. - name: Coverage description: Where you can send, per country. - name: Conversations description: Two-way threads between one of your numbers and a contact. - name: Opt-outs description: Numbers that must not receive messages on a channel. - name: Webhooks description: Subscriptions that deliver message and broadcast events to your server. - name: Broadcasts description: Bulk sends from an uploaded recipient list. - name: RCS Senders description: RCS sender (agent) identities and their message templates. - name: 10DLC Brands description: US 10DLC brand registration. - name: 10DLC Campaigns description: US 10DLC campaigns, toll-free verification and supporting documents. paths: /numbers: get: tags: - Numbers summary: List your numbers description: >- Returns every number on your account that is routed for SMS or MMS, sorted by `countryCode` and then `e164`. Each number carries its US registration state, the last message it sent and a `sendable` summary of where it can send right now. Check `sendable.usDomestic` before you send to US recipients from a US number. To add numbers, search with `GET /numbers/available` and buy with `POST /numbers/purchase`. operationId: list-numbers responses: '200': description: Your messaging numbers, sorted by country then number. content: application/json: schema: $ref: '#/components/schemas/SMSNumberList' example: numbers: - e164: '+14155550100' provider: internal countryCode: US channels: - sms - mms type: VIRTUAL_LONG_NUMBER capabilities: - SMS - VOICE - MMS tenDlc: campaignId: 3f1c7a2e-9d4b-4e8a-b6c5-2a7d9e1f0b43 campaignName: Order notifications stage: REGISTERED tollFree: false registration: kind: 10dlc status: approved campaignId: 3f1c7a2e-9d4b-4e8a-b6c5-2a7d9e1f0b43 campaignName: Order notifications stage: REGISTERED lastMessage: status: delivered errorCode: '' errorMessage: '' to: '+14155550123' createdAt: '2026-10-16T21:23:02Z' sendable: international: true usDomestic: true - e164: '+14155550101' provider: internal countryCode: US channels: - sms - mms type: VIRTUAL_LONG_NUMBER capabilities: - SMS - VOICE - MMS tenDlc: null tollFree: false registration: kind: 10dlc status: not_registered campaignId: '' campaignName: '' stage: '' lastMessage: null sendable: international: true usDomestic: false '401': $ref: '#/components/responses/Unauthorized' '500': $ref: '#/components/responses/ServerError' x-codeSamples: - lang: typescript label: Node SDK source: > import { VobizClient } from "@vobiz/sdk"; const client = new VobizClient({ apiKey: "MA_XXXXXXXX", authToken: "YOUR_AUTH_TOKEN" }); await client.sms.numbers.listNumbers() - lang: python label: Python SDK source: | from vobiz import Vobiz client = Vobiz(api_key="MA_XXXXXXXX", auth_token="YOUR_AUTH_TOKEN") client.sms.numbers.list_numbers() - lang: go label: Go SDK source: | import ( "context" vobiz "github.com/vobiz-ai/Vobiz-Go-SDK" "github.com/vobiz-ai/Vobiz-Go-SDK/client" "github.com/vobiz-ai/Vobiz-Go-SDK/option" "github.com/vobiz-ai/Vobiz-Go-SDK/sms" ) c := client.NewClient( option.WithAPIKey("MA_XXXXXXXX"), option.WithAuthToken("YOUR_AUTH_TOKEN"), ) c.Sms.Numbers.ListNumbers( context.TODO(), ) - lang: java label: Java SDK source: | import com.vobiz.api.VobizApiClient; VobizApiClient client = VobizApiClient .builder() .apiKey("MA_XXXXXXXX") .authToken("YOUR_AUTH_TOKEN") .build(); client.sms().numbers().listNumbers(); - lang: ruby label: Ruby SDK source: > require 'vobiz' client = Vobiz::Client.new(api_key: 'MA_XXXXXXXX', auth_token: 'YOUR_AUTH_TOKEN') client.sms.numbers.list_numbers - lang: csharp label: C# SDK source: | using Vobiz; using Vobiz.Sms; var client = new VobizApiClient("YOUR_AUTH_TOKEN", "MA_XXXXXXXX"); await client.Sms.Numbers.ListNumbersAsync(); - lang: php label: PHP SDK source: > sms->numbers->listNumbers(); components: schemas: SMSNumberList: type: object properties: numbers: type: array description: >- Numbers routed for SMS or MMS, sorted by `countryCode` and then `e164`. Empty array when you have no messaging numbers. items: $ref: '#/components/schemas/SMSNumber' description: The messaging numbers on your account. SMSNumber: type: object description: >- A messaging-capable number on your account, with its registration state and what it can send. properties: e164: type: string example: '+14155550100' description: The number in E.164 format. Use it as `from` when you send. provider: type: string description: Internal routing identifier; do not rely on its value. countryCode: type: string description: >- Upper-case ISO 3166-1 alpha-2 code of the number's country. Empty string when unknown. example: US channels: type: array description: >- Lower-case channels routed on the number: `sms`, `mms` and `rcs`. Defaults to `["sms"]`. items: type: string enum: - sms - mms - rcs example: - sms - mms type: type: string description: >- Inventory type in upper case, for example `VIRTUAL_LONG_NUMBER`, `SHORT_CODE` or `TOLL_FREE`. Empty string when unknown. example: VIRTUAL_LONG_NUMBER capabilities: type: array description: >- Upper-case capability labels, for example `SMS`, `MMS` and `VOICE`. Empty array when unknown. items: type: string example: - SMS - MMS - VOICE tenDlc: allOf: - $ref: '#/components/schemas/SMSNumberTenDlc' description: >- The most relevant US registration campaign attached to the number. `null` when no campaign is attached. tollFree: type: boolean description: >- `true` for US toll-free numbers, which use toll-free verification instead of a 10DLC campaign. registration: allOf: - $ref: '#/components/schemas/SMSNumberRegistration' description: US A2P registration state of the number and the campaign behind it. lastMessage: allOf: - $ref: '#/components/schemas/SMSNumberLastMessage' description: >- The latest outbound message sent from this number. `null` when the number has not sent a message yet. sendable: allOf: - $ref: '#/components/schemas/SMSNumberSendable' description: >- Where the number can send right now, derived from its country and registration state. Error: type: object description: >- The body of every error response: a flat object with one `error` string that explains what went wrong. Use the HTTP status code to decide how to handle the error, and log `error` for diagnosis. required: - error properties: error: type: string example: 'recipient has opted out: +14155550123' description: >- Human-readable explanation of the error, for example `phoneNumber is required` or `recipient has opted out: +14155550123`. Branch on the HTTP status code rather than on this text. SMSNumberTenDlc: type: object nullable: true description: >- The most relevant US registration campaign attached to a number. `null` when no campaign is attached. properties: campaignId: type: string format: uuid example: 3f1c7a2e-9d4b-4e8a-b6c5-2a7d9e1f0b43 description: >- ID of the campaign the number is registered to. Use it with the 10DLC campaign endpoints. campaignName: type: string example: Order notifications description: Name you gave that campaign. stage: type: string description: >- Registry stage of the campaign in upper case, for example `REGISTERED` or `IN_REVIEW`. Treat as an open string. example: REGISTERED SMSNumberRegistration: type: object description: >- US A2P registration state of a number: which registration path applies and how far it has progressed. properties: kind: type: string enum: - 10dlc - toll_free - none description: >- Registration path: `10dlc` for long numbers that need a 10DLC campaign, `toll_free` for toll-free numbers that need toll-free verification, `none` when no US registration applies. status: type: string enum: - not_registered - draft - pending - approved - rejected - not_required description: >- Progress of that registration: `not_registered` (no campaign attached), `draft` (campaign not submitted), `pending` (under review), `approved` (cleared to send to US recipients), `rejected` (fix and resubmit) or `not_required`. campaignId: type: string description: >- ID of the campaign the number is attached to. Empty string when none. example: 3f1c7a2e-9d4b-4e8a-b6c5-2a7d9e1f0b43 campaignName: type: string description: Name of that campaign. Empty string when none. example: Order notifications stage: type: string description: >- Registry stage of that campaign in upper case, for example `REGISTERED`. Treat as an open string; empty string when none. example: REGISTERED SMSNumberLastMessage: type: object nullable: true description: >- The latest outbound message sent from a number, for a quick health check. `null` when the number has not sent a message yet. properties: status: type: string enum: - scheduled - sent - delivered - failed - received - unknown description: >- Delivery status of that message: `scheduled`, `sent`, `delivered`, `failed`, `received` or `unknown`. errorCode: type: string description: >- Error code reported for the message. Empty string unless the message failed. errorMessage: type: string description: >- Human-readable reason for the failure. Empty string unless the message failed. to: type: string example: '+14155550123' description: Recipient of that message in E.164 format. createdAt: type: string format: date-time example: '2026-10-16T21:23:02Z' description: When that message was created (ISO 8601). SMSNumberSendable: type: object description: >- Where a number can send right now, derived from its country and registration state. Check it before you send. properties: international: type: boolean description: '`true` when the number can send to recipients outside the US.' usDomestic: type: boolean description: >- `true` when the number can send to US recipients. A US number needs an approved 10DLC campaign or completed toll-free verification before this becomes `true`. responses: Unauthorized: description: Missing or invalid `X-Auth-ID` / `X-Auth-Token`. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: missing or invalid credentials ServerError: description: Unexpected error. Retry with the same idempotency key where one applies. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: internal error securitySchemes: AuthID: type: apiKey in: header name: X-Auth-ID description: Your Vobiz account Auth ID (`MA_XXXXXXXX`). AuthToken: type: apiKey in: header name: X-Auth-Token description: Your Vobiz account Auth Token. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.