---
title: "List Available Numbers"
method: GET
path: "/v1/numbers/available"
tags: ["numbers"]
---

# List Available Numbers

`GET /v1/numbers/available`

Search purchasable phone numbers before buying one.

Pick a number here, then buy it by passing the same `phoneNumber` to
`POST /v1/numbers`. Searching with no criteria returns a page of whatever
is currently in stock.

**Results are not reserved.** This is live inventory, so a number can be
bought by someone else between your search and your purchase. When that
happens the purchase returns `409` with fresh alternatives in this same
shape; pick another and retry rather than treating it as fatal.

Criteria support varies by account, and there is no single rule that
holds everywhere:

- `areaCode` is the most broadly supported filter.
- `city`, `state` and `zip` work on some accounts and not others.
  Where they aren't supported they are ignored rather than rejected, so
  check what comes back instead of assuming the filter applied.
- `state` on its own is honored on some accounts and rejected with `400`
  on others. Pair it with `city` for consistent behavior.

Returns `404` when number search isn't available on your account at all,
and `422` when it isn't configured yet. If you need location search and
aren't getting it, contact support.

Giving a Canadian area code searches Canada even though `country`
defaults to `US`.

`country=UK` (or `GB`) returns United Kingdom mobile numbers on accounts
where they're available. UK numbers are SMS-only and have no area codes,
so location filters are rejected for UK searches.

If `widened` is true, your exact criteria were out of stock and these are
nearby alternatives instead.

## Query parameters

- `areaCode` string, nullable — 3-digit area code, e.g. "415". The most broadly supported filter.
- `city` string, nullable — City name. Pair with state. Support varies by account.
- `state` string, nullable — 2-letter state code, e.g. "CA". Pair with city for consistent results; standalone support varies by account.
- `zip` string, nullable — 5-digit ZIP. Support varies by account.
- `country` string — "US", "CA", or "UK" ("GB" is accepted as an alias). United Kingdom availability varies by account.
- `limit` integer — Max results, 1-30.

## Response `200`

Successful Response

- AvailableNumberListResponse
  - `data` AvailableNumber[], required
    - `phoneNumber` string, required
    - `city` string, nullable
    - `state` string, nullable
    - `rateCenter` string, nullable
    - `areaCode` string, nullable
  - `widened` boolean

## Other responses

- `422` — Validation Error

## Changes

- **2026-09-11** `b04628c8f090` — 1 info
  - endpoint added

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

---

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