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

Works without an API key. Keyless calls get up to 12 results with the
middle digits masked (`maskedNumber`), each with a `claimId` and a
`claimUrl`: a signup link that lands a person on the dashboard's
confirm step with that number picked, so an agent can search for a
user and hand them one link. Keyless calls are rate limited per IP and
results are cached for a few minutes. With an API key you get full
numbers and no claim fields.

## Query parameters

- `country` string
- `numberType` 'local' | 'mobile' | 'national' | 'toll_free'
- `areaCode` string
- `type` string
- `prefix` string
- `locality` string
- `contains` string
- `sms` boolean
- `limit` integer
- `masked` boolean

## 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.
    - `maskedNumber` string — Keyless calls only, in place of `phoneNumber`: the number with its middle digits masked, e.g. +44 20 •••• 0123.
    - `numberType` string — Keyless calls only. Without a `numberType` filter a keyless search mixes every type the country sells, so each result names its own.
    - `claimId` string — Keyless calls only. Opaque, expires after 7 days. Pass it as `claimId` on a keyless POST /v1/phone-numbers/purchase.
    - `claimUrl` string — Keyless calls only. Signup link that opens the dashboard's confirm step for this number. The number is not held: if it is gone by then, the buyer picks another in the same area.
  - `masked` boolean — true on keyless calls.
  - `near` string, nullable — With `country=auto`: the caller's city the results were narrowed to, or null when there was no stock there.
  - `claimId` string — Keyless calls only: a claim for any number matching this search's country, type and area.
  - `claimUrl` string — Keyless calls only: signup link for any number matching this search.

## Other responses

- `400` — Country not offerable, numberType outside the four offered, or a query parameter this endpoint does not know (the message lists the accepted ones; nothing is silently ignored).
- `401` — Unauthorized
- `429` — Keyless rate limit reached. Retry later or send an API key.

## Changes

- **2026-09-25** `2c04683ce694` — 10 info
  - added the new optional `query` request parameter `masked`
  - added the non-success response with the status `429`
  - added the optional property `claimId` to the response with the `200` status
  - added the optional property `claimUrl` to the response with the `200` status
  - …6 more
- **2026-09-23** `dd3865482f9f` — 4 info
  - added the new optional `query` request parameter `areaCode`
  - added the new optional `query` request parameter `numberType`
  - `query` request parameter `prefix` was deprecated
  - `query` request parameter `type` was deprecated
- **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/b2325332041a?raw)