---
title: "Search available phone numbers"
method: GET
path: "/v1/phone-numbers/available"
---

# Search available phone numbers

`GET /v1/phone-numbers/available`

## Request

- Base URL: `https://api.zavu.dev`
- URL: `https://api.zavu.dev/v1/phone-numbers/available`
- Auth: HTTP bearer

Search for available phone numbers to purchase by country and type.

## Query parameters

- `countryCode` string, required
- `type` 'local' | 'national' | 'tollFree' | 'mobile': Type of phone number. `mobile` is stocked in countries where no geographic (`local`) or non-geographic (`national`) inventory exists, and in several markets it is the only type that can receive SMS.
- `contains` string
- `capabilities` string
- `limit` integer

## Response `200`

List of available phone numbers. An empty `items` means the country is served but nothing matched these filters, including a number type the country does not sell (retry with another `type`) and a `contains` pattern no number matches.

- object
  - `items` AvailablePhoneNumber[], required
    - `phoneNumber` string, required
    - `friendlyName` string
    - `locality` string
    - `region` string
    - `capabilities` PhoneNumberCapabilities, required
      - `sms` boolean
      - `voice` boolean
      - `mms` boolean
    - `pricing` PhoneNumberPricing, required
      - `monthlyPrice` number: Monthly price in USD.
      - `upfrontPrice` number: One-time purchase price in USD.
      - `isFreeEligible` boolean: Whether this number qualifies as the plan-included number: a US or Canadian number (a +1 number) costing $20 a month or less. The benefit is one per account: it is never offered again once claimed, not even after the number is released.

## Other responses

- `400`: Invalid query parameters, or `country_restricted`: phone numbers in this country are not sold self-service and need a minimum commitment. The message names who to contact. A `contains` pattern the inventory refused is answered `invalid_request` with `details.field` set to `contains`; one that only matched nothing is a `200` with empty `items`.
- `401`: Unauthorized.
- `404`: `country_unavailable`: we do not currently stock numbers in this country. Distinct from an empty `items` array, which means the country is served but nothing matched your filters — retry with another `type`.
- `502`: The number inventory could not be reached, or refused a search it should accept. Retry; do not treat this as no stock.

## Changes

> 80 revisions in range; 1 not diffed.

- **2026-11-03** `75bc777b0ffb`: 1 info
  - added the non-success response with the status `502`
- **2026-09-08** `b343da23d9f4`: 2 info
  - added the new enum value `mobile` to the `query` request parameter `type`
  - added the non-success response with the status `404`
- **2026-07-27** `7bedd013ec33`: 1 info
  - added the new optional `query` request parameter `capabilities`
- **2026-07-07** `f467a4da6cd2`: 1 breaking, 1 info
  - removed the enum value `mobile` from the `query` request parameter `type`
  - added the new enum value `national` to the `query` request parameter `type`

[Operation history](https://skmtc.dev/zavudev/apis/zavu-unified-messaging-layer-api/changes/v1/phone-numbers/available/get.md)

---

[API](https://skmtc.dev/zavudev/apis/zavu-unified-messaging-layer-api.md) - [All operations](https://skmtc.dev/zavudev/apis/zavu-unified-messaging-layer-api/llms.txt) - [OpenAPI document](https://skmtc.dev/zavudev/apis/zavu-unified-messaging-layer-api/revisions/75bc777b0ffb?raw)