---
title: "Load exact numbers from the carrier for one country and number type, optionally narrowed by area code or region. A safe read: nothing is reserved, ordered or charged. A recent identical search is answered from the loaded snapshot or its cooldown instead of reading the carrier again"
method: POST
path: "/v1/available-numbers/search"
---

# Load exact numbers from the carrier for one country and number type, optionally narrowed by area code or region. A safe read: nothing is reserved, ordered or charged. A recent identical search is answered from the loaded snapshot or its cooldown instead of reading the carrier again

`POST /v1/available-numbers/search`

## Request

- Base URL: `https://api.skysay.ai`
- URL: `https://api.skysay.ai/v1/available-numbers/search`
- Auth: none declared

## Request body

- object
  - `area_code` string: Only numbers in this area code, for example 212
  - `country` string, required: ISO country code, for example US
  - `limit` integer
  - `number_type` string
  - `region` string: Only numbers in this state or region, by name or code, for example Texas, TX or US-TX

## Response `200`

The rows as GET /v1/available-numbers returns them, the area_code and region searched, refresh_status (succeeded|fresh_cache|cooldown|failed|blocked) and expires_at. Only succeeded and fresh_cache mean the rows are current carrier inventory; cooldown and failed return no rows

## Other responses

- `400`: country is missing, area_code is not 1-6 digits, region is longer than 64 characters, or limit is not an integer

---

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