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

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

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

---

[API](https://skmtc.net/zernio/apis/zernio-api.md) · [All operations](https://skmtc.net/zernio/apis/zernio-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/zernio/zernio-api/versions/51932b099b2f/schema)