---
title: "Search the provider catalogue for numbers to buy"
method: GET
path: "/api/v1/phone-numbers/available"
tags: ["Phone numbers"]
---

# Search the provider catalogue for numbers to buy

`GET /api/v1/phone-numbers/available`

## Request

- Base URL: `https://wardenpoint.com` (the document declares no server; this is the origin it was published from)
- URL: `https://wardenpoint.com/api/v1/phone-numbers/available`
- Auth: API key in header `X-API-Key`

What could be bought in one country, priced the way the dashboard prices it — the platform markup is already applied, so the figures here are what the company would actually be charged. Read-only: **this API cannot buy a number.** Buying spends the company's credit balance, is not refundable, and is deliberately left to a human in the dashboard; the point of this endpoint is to be able to tell that human what to buy. Country is required because the catalogue lives at the provider and an unscoped lookup costs a request without answering anything. Two things about the answer that are easy to get wrong: entries are **number classes, not individual numbers** — the provider sells by area code and kind, and `number` is a mask ending in `XXXX`, with the actual digits assigned at purchase; and the current provider **ignores `city_id` and `type`**, returning the whole country either way, so treat those two as hints for the future and filter what you show yourself.

## Query parameters

- `country_code` string, required
- `city_id` string
- `type` 'local' | 'mobile' | 'tollfree'

## Response `200`

Number classes on offer.

- object
  - `data` object[]
    - `number` string: A MASK, not a number you can dial or buy: country code plus area code plus `XXXX`. The real digits are assigned by the provider at purchase.
    - `country_code` string
    - `country` string
    - `city` string, nullable
    - `monthly_cost` number, float: Platform markup already applied.
    - `setup_fee` number, float: Platform markup already applied. Charged once, on purchase.
    - `type` 'local' | 'mobile' | 'tollfree' | 'national': Derived by us from the provider's wording, so `national` appears here even though the `type` query parameter does not accept it.
    - `currency` string
    - `capabilities` string[]: What the number can carry, e.g. voice, sms.
    - `direction_id` integer: The provider-side identifier of this number class, and the thing the dashboard purchase form actually sends — quote it when telling somebody what to buy, because `number` is only a mask. Present only for providers that use one.

## Other responses

- `401`: API key missing, invalid, revoked or expired.
- `403`: API key lacks the config.read ability.
- `422`: country_code missing or not two letters, or an unknown value in type.
- `429`: Too many catalogue lookups in a short window. The catalogue lives at the provider.
- `500`: The provider could not be reached or answered with an error. Worth retrying — nothing about the request was wrong.

---

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