> ## 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. # Search available numbers > Searches the inventory for numbers you can buy in one country, with their setup and monthly prices in your wallet currency. Each search returns up to 10 numbers. ## OpenAPI ````yaml openapi-sms.yaml GET /numbers/available 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/available: get: tags: - Numbers summary: Search available numbers description: >- Searches the inventory for numbers you can buy in one country, with their setup and monthly prices in your wallet currency. Each search returns up to 10 numbers. Pass the chosen `e164`, the `country` and any non-empty `numberKey` to `POST /numbers/purchase`. For `country=IN` the list is empty and `hint` explains that Indian traffic uses DLT-registered sender IDs. A country outside the set Vobiz sells numbers in returns `422`. operationId: search-available-numbers parameters: - name: country in: query required: true description: >- Country to search, as an ISO 3166-1 alpha-2 code such as `US`, `CA` or `GB`. Case-insensitive. A value that is not two letters returns `400` with `country must be an ISO 3166-1 alpha-2 code`. schema: type: string pattern: ^[A-Za-z]{2}$ example: US - name: capabilities in: query description: >- Comma-separated capabilities the number must have: `SMS`, `MMS`, or `SMS,MMS`. Case-insensitive, defaults to `SMS`. Any other value returns `400` with `capabilities must be SMS and/or MMS`. schema: type: string default: SMS example: SMS,MMS - name: areaCode in: query description: >- Three-digit area code to search in, for example `415`. Accepted only when `country` is `US` or `CA`; other countries return `400` with `areaCode is only supported for US and CA`. schema: type: string pattern: ^[0-9]{3}$ example: '415' - name: limit in: query description: >- Maximum number of results, from `1` to `100`. Defaults to `10`, and each search returns at most 10 numbers whatever you pass. A value outside the range returns `400` with `limit must be between 1 and 100`. schema: type: integer minimum: 1 maximum: 10 default: 10 responses: '200': description: Numbers you can buy. content: application/json: schema: $ref: '#/components/schemas/AvailableNumbersResponse' examples: us: summary: US search value: 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 india: summary: India value: numbers: [] page: 0 limit: 10 hasMore: false hint: India uses DLT sender IDs, not long codes '400': description: A query parameter is invalid. content: application/json: schema: $ref: '#/components/schemas/Error' examples: country-missing: value: error: country is required country-format: value: error: country must be an ISO 3166-1 alpha-2 code capabilities: value: error: capabilities must be SMS and/or MMS areaCode: value: error: areaCode is only supported for US and CA limit: value: error: limit must be between 1 and 100 '401': $ref: '#/components/responses/Unauthorized' '422': description: >- The country or your wallet currency is outside the current sales set. content: application/json: schema: $ref: '#/components/schemas/Error' examples: country: value: error: SMS numbers are not sold for country FR pricing: value: error: >- SMS numbers in GB cannot be priced in EUR yet; contact support '500': $ref: '#/components/responses/ServerError' '502': description: The upstream inventory rejected the search or could not be reached. content: application/json: schema: $ref: '#/components/schemas/Error' examples: rejected: value: error: 'number provider: invalid area code' unavailable: value: error: number provider unavailable; try again later '503': description: Number search is paused or busy. Retry after a short wait. content: application/json: schema: $ref: '#/components/schemas/Error' examples: busy: value: error: number search is busy; try again in a few seconds billing: value: error: billing is unavailable; try again later purchasing: value: error: number purchasing is not available 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.searchAvailableNumbers({ country: "US", capabilities: "SMS,MMS", areaCode: "415" }) - lang: python label: Python SDK source: | from vobiz import Vobiz client = Vobiz(api_key="MA_XXXXXXXX", auth_token="YOUR_AUTH_TOKEN") client.sms.numbers.search_available_numbers( country="US", capabilities="SMS,MMS", area_code="415", ) - 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"), ) request := &sms.SearchAvailableNumbersRequest{ Country: "US", Capabilities: vobiz.String( "SMS,MMS", ), AreaCode: vobiz.String( "415", ), } c.Sms.Numbers.SearchAvailableNumbers( context.TODO(), request, ) - 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().searchAvailableNumbers( SearchAvailableNumbersRequest .builder() .country("US") .capabilities("SMS,MMS") .areaCode("415") .build() ); - lang: ruby label: Ruby SDK source: > require 'vobiz' client = Vobiz::Client.new(api_key: 'MA_XXXXXXXX', auth_token: 'YOUR_AUTH_TOKEN') client.sms.numbers.search_available_numbers( country: "US", capabilities: "SMS,MMS", area_code: "415" ) - lang: csharp label: C# SDK source: | using Vobiz; using Vobiz.Sms; var client = new VobizApiClient("YOUR_AUTH_TOKEN", "MA_XXXXXXXX"); await client.Sms.Numbers.SearchAvailableNumbersAsync( new SearchAvailableNumbersRequest { Country = "US", Capabilities = "SMS,MMS", AreaCode = "415", } ); - lang: php label: PHP SDK source: > sms->numbers->searchAvailableNumbers( new SearchAvailableNumbersRequest([ 'country' => 'US', 'capabilities' => 'SMS,MMS', 'areaCode' => '415', ]), ); components: schemas: AvailableNumbersResponse: type: object properties: numbers: type: array items: $ref: '#/components/schemas/AvailableNumber' description: >- Numbers that match your filters, at most 10 per search. Empty array when nothing matches, and for `country=IN`. page: type: integer example: 0 description: The zero-based page index you requested, echoed back. limit: type: integer example: 10 description: Page size applied to this search, at most `10`. hasMore: type: boolean example: false description: >- Reserved for pagination; `false` on every response. Run a new search with different filters to see other numbers. hint: type: string description: >- Guidance returned only for `country=IN`, explaining that Indian traffic is sent from DLT-registered sender IDs rather than purchased numbers. Absent for every other country. example: India uses DLT sender IDs, not long codes description: One page of inventory search results. 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. AvailableNumber: type: object description: >- A number in the inventory that you can buy, with its type, capabilities and price. properties: e164: type: string example: '+14155550100' description: >- The number in E.164 format. Pass it as `e164` on `POST /numbers/purchase`. numberKey: type: string description: >- Opaque inventory key for the number. Pass it as `numberKey` on `POST /numbers/purchase` when it is not empty; it is empty for US numbers, which are bought by `e164` alone. example: '' countryCode: type: string example: US description: ISO 3166-1 alpha-2 code of the country the number belongs to. type: type: string example: VIRTUAL_LONG_NUMBER description: >- Inventory type of the number in upper case, for example `VIRTUAL_LONG_NUMBER` or `TOLL_FREE`. capabilities: type: array items: type: string example: - MMS - SMS - VOICE description: >- Upper-case capability labels for the number, for example `SMS`, `MMS` and `VOICE`. Order is not significant. network: type: string description: >- Name of the mobile network the number belongs to, when published. Empty string otherwise. example: '' setupPrice: type: number description: One-time setup fee charged at purchase, in `currency`. example: 1 monthlyPrice: type: number description: >- Monthly rental charged at purchase for the first month and then on each renewal, in `currency`. example: 1 currency: type: string description: >- ISO 4217 code of the prices, which is your wallet currency, for example `USD`. example: USD providerRequiresDocuments: type: boolean description: >- `true` when the number needs regulatory documents before it can be activated. Contact support to buy such a number; `POST /numbers/purchase` returns `422` for it. 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.