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

# Check country availability

`GET /v1/messaging/phone-numbers/availability`

## Request

- Base URL: `https://apihub.co.il`
- URL: `https://apihub.co.il/v1/messaging/phone-numbers/availability`
- Auth: HTTP bearer

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.


**Billing:** Read (free unless it says otherwise) · **Rate limit:** 120/min

## Query parameters

- `sms` boolean: Pass true when the buyer wants SMS: availability, areas, and areaOptions then describe the SMS-capable pool (an SMS purchase orders from it), not the wider voice-only pool.
- `country` string, required: ISO-2 country code.
- `numberType` 'local' | 'mobile' | 'national' | 'toll_free': Check a specific offered type (stock and address constraints are per type). Omitted = the country's default type.

## Headers

- `Idempotency-Key` string
- `X-Tag` string

## Response `200`

Completed

- object
  - `id` string: Execution id — stable across internal retries; use it with GET /v1/executions/{id}
  - `status` 'pending' | 'processing' | 'completed' | 'partial' | 'failed' | 'cancelled' | 'timeout'
  - `operation` string
  - `tag` string, nullable: Your X-Tag, if sent
  - `created_at` string, date-time
  - `completed_at` string, date-time, nullable
  - `output` object: Operation result (see each operation). While a Studio render is processing: `stage` (queued · transcribing · downloading · preparing · cleaning_voice · mixing_audio · rendering · finishing), `phase` (the engine's: download · prepare · voice · audio · encode · qa · upload, or null), `progress` (a percent, 0–100) and `progress_fraction` (0–1), `eta_seconds` (seconds left, never below 0) and `estimate_seconds`
    - `areas` string[]: For `geo` only: the area(s) the registered address must be in.
    - `country` string
    - `available` boolean: Whether deliverable voice inventory exists right now.
    - `numberType` string
    - `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. Equal to `areaAvailability.inStock`.
      - `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.
    - `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.
    - `soldOutAreas` object[]: Every area of the country's numbering plan with nothing deliverable now: `areaAvailability.preOrder` plus `areaAvailability.outOfStock`, kept for older clients. 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).
    - `areaAvailability` object: Every area of the country's numbering plan (Google libphonenumber geocoding, one row per city: Madrid covers 910 to 919), in one of three states, refreshed every 6 hours from the carrier's own inventory counts. The same answer the dashboard picker and the public country pages show. Empty lists mean the pair has no cached coverage yet, not that the country has no areas.
      - `inStock` object[]: Deliverable numbers now, deepest first. Pass `ndc` as `areaCode` to hold the order to it.
        - `ndc` string
        - `name` string
        - `ndcs` string[]: Every area code of the city, deepest first (Madrid: 915, 911, 910, ...). `ndc` is the one an order is placed against.
        - `count` integer: Numbers we can sell there: the carrier count minus the numbers we hold back (WhatsApp refused them or another order holds them).
        - `aliases` string[]: Other names the area answers to, present only when it has some (Milano for Milan, Sevilla for Seville).
      - `preOrder` object[]: The carrier lists nothing there and the number type is a document tier: submit KYC with `areaCode` and `preOrder: true`, the carrier sources one (usually 2 to 4 weeks, never guaranteed), nothing is billed until it is active.
        - `ndc` string
        - `name` string
        - `ndcs` string[]: Every area code of the city, deepest first (Madrid: 915, 911, 910, ...). `ndc` is the one an order is placed against.
        - `aliases` string[]: Other names the area answers to, present only when it has some (Milano for Milan, Sevilla for Seville).
      - `outOfStock` object[]: Nothing deliverable and no pre-order: `listed` > 0 is stock the carrier shows that WhatsApp refused recently (held back until it clears), 0 is a dry area of an instant tier. A stock watch (POST /v1/phone-numbers/stock-watches with `areaCode`) is the way to hear when it is back.
        - `ndc` string
        - `name` string
        - `ndcs` string[]: Every area code of the city, deepest first (Madrid: 915, 911, 910, ...). `ndc` is the one an order is placed against.
        - `listed` integer
        - `aliases` string[]: Other names the area answers to, present only when it has some (Milano for Milan, Sevilla for Seville).
    - `addressConstraint` 'geo' | 'country' | 'none'
  - `error` string, nullable
  - `usage` object
    - `credits_charged` number, nullable
    - `credits_reserved` number
    - `estimated_credits` number
    - `cost_source` 'provider_reported' | 'calculated' | 'estimated' | 'null', nullable
    - `provider_usage` object, nullable: Normalised consumption, e.g. { VIDEO_SECOND: 22.4 }
  - `balance` object
    - `available` number
    - `reserved` number

## Other responses

- `400`: Invalid input
- `402`: Insufficient credits / project budget
- `404`: Resource not found (or not yours)
- `429`: Rate limited
- `503`: Service temporarily paused

---

[API](https://skmtc.dev/apihub/apis/apihub-one-api-for-chat-image-video-ai.md) · [All operations](https://skmtc.dev/apihub/apis/apihub-one-api-for-chat-image-video-ai/llms.txt) · [OpenAPI document](https://skmtc.dev/apihub/apis/apihub-one-api-for-chat-image-video-ai/revisions/a8caa42835ce?raw)