---
title: "Check country availability"
method: GET
path: "/v1/phone-numbers/availability"
tags: ["Phone Numbers"]
---

# Check country availability

`GET /v1/phone-numbers/availability`

Pre-purchase check, so you can warn BEFORE a customer invests in KYC
(regulated review is async, 1-3 days). Tells you whether we have
deliverable inventory, and what address the customer needs:
  - `addressConstraint: geo`  → the registered address MUST be in one of
    the returned `areas` (the only place we have stock). A different-area
    address passes pre-approval but the number can never be assigned.
  - `addressConstraint: country` → any in-country address works.
  - `addressConstraint: none` → field-only / instant country, no address.
Call this before starting the KYC form for regulated countries.

Without an API key it answers from cache only and returns just
`country`, `numberType` and `areaOptions`, for building an area
picker before signup.

## Query parameters

- `country` string, required
- `numberType` 'local' | 'mobile' | 'national' | 'toll_free'
- `sms` boolean

## Response `200`

Availability + address constraint.

- object
  - `country` string
  - `numberType` string
  - `available` boolean — Whether deliverable voice inventory exists right now.
  - `preOrderable` boolean — Nothing deliverable now, but this pair can be pre-ordered: submit KYC as usual and we buy regular stock the moment it returns, otherwise the carrier sources the number (usually 2 to 4 weeks, never guaranteed). Only document tiers (3/4) qualify.
  - `addressConstraint` 'geo' | 'country' | 'none'
  - `areas` string[] — For `geo` only: the area(s) the registered address must be in.
  - `areaOptions` object[] — Live inventory grouped by area code. For US and CA this is the full country inventory (every area code with stock, recognizable metros listed first, then alphabetical); other countries are ordered largest stock first; they list the areas in the latest inventory page (up to 500 numbers, which for most countries is the entire pool). Empty when out of stock (or the area lookup failed). Pass a chosen `ndc` as `areaCode` on POST /v1/phone-numbers/purchase (or on the KYC submit for regulated countries) to require that area.
    - `ndc` string — Area code (national destination code), e.g. "11".
    - `name` string — Area name: "City, ST" for US/CA (e.g. "Miami, FL"), city otherwise (e.g. "Sao Paulo").
    - `count` integer — Numbers available in this area: country-wide count for US/CA, numbers seen on the latest inventory page otherwise.
  - `soldOutAreas` object[] — Areas that had stock in the last 90 days and have none now. Pass one as `areaCode` with `preOrder: true` on the KYC submit when `preOrderable` is true, or watch it with POST /v1/phone-numbers/stock-watches.
    - `ndc` string — Area code (national destination code).
    - `name` string — Area name.
    - `preOrderable` boolean — Whether this area can be pre-ordered: the carrier sources a number in it (usually 2 to 4 weeks, never guaranteed).

## Other responses

- `400` — Country not offerable, or the inventory provider rejected the lookup (its 4xx status is forwarded as-is).
- `401` — Unauthorized
- `502` — The inventory provider was unreachable or returned an unclassified error.

## Changes

- **2026-09-15** `0dba7d004d75` — 1 info
  - added the optional property `soldOutAreas` to the response with the `200` status
- **2026-09-10** `e70ed06e7150` — 1 info
  - added the optional property `preOrderable` to the response with the `200` status

[Change history](https://skmtc.dev/zernio/apis/zernio-api/changes/v1/phone-numbers/availability/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)