---
title: "Search available numbers"
method: GET
path: "/v1/phone-numbers/available"
tags: ["Phone Numbers"]
---

# Search available numbers

`GET /v1/phone-numbers/available`

Search the provider's inventory for numbers available to purchase in a
country (default US). Optional filters narrow the results. The country
must be offerable (see GET /v1/phone-numbers/countries). Voice
capability is always required; pass `sms=true` to only see numbers that
can also text (SMS support is per-number, not per-country). Numbers a
purchase would refuse are left out, and any result's `phoneNumber` can
be bought exactly by passing it to POST /v1/phone-numbers/purchase.

## Query parameters

- `country` string
- `type` string
- `prefix` string
- `locality` string
- `contains` string
- `sms` boolean
- `limit` integer

## Response `200`

Available numbers.

- object
  - `country` string
  - `numberType` string
  - `requireSms` boolean — Echo of the `sms` filter applied to this search.
  - `numbers` object[]
    - `phoneNumber` string — E.164. Pass it as `phoneNumber` on POST /v1/phone-numbers/purchase to buy this exact number.
    - `features` string[] — Provider capability list for this number (e.g. voice, sms, mms).
    - `locality` string — Town or rate center the number belongs to, as the carrier names it (e.g. WACO).
    - `bestEffort` boolean — true when the carrier added this number because too few matched your filters, so it may be outside the requested prefix or locality.

## Other responses

- `400` — Country not available
- `401` — Unauthorized

## Changes

- **2026-09-10** `e70ed06e7150` — 2 info
  - added the optional property `numbers/items/bestEffort` to the response with the `200` status
  - added the optional property `numbers/items/locality` to the response with the `200` status

[Change history](https://skmtc.dev/zernio/apis/zernio-api/changes/v1/phone-numbers/available/get.md)

---

[API](https://skmtc.dev/zernio/apis/zernio-api.md) · [All operations](https://skmtc.dev/zernio/apis/zernio-api/llms.txt) · [OpenAPI document](https://skmtc.dev/zernio/apis/zernio-api/revisions/be448f13ecdc?raw)