---
title: "Search available Canadian phone numbers to provision"
method: GET
path: "/v1/phone-numbers/search"
tags: ["Phone Numbers"]
---

# Search available Canadian phone numbers to provision

`GET /v1/phone-numbers/search`

## Request

- Base URL: `https://api.honkio.ca`
- URL: `https://api.honkio.ca/v1/phone-numbers/search`
- Auth: one of:
  - HTTP bearer
  - API key in header `X-API-Key`

Optionally filtered by `area_codes`: up to 25 distinct codes (repeats count once), each an active Canadian area code (GET /v1/phone-numbers/area-codes) or a toll-free prefix (833, 844, 855, 866, 877, 888). Toll-free prefixes are accepted although the area-code list does not include them: they are sold at the toll-free tier, and searching by prefix is how to find one. 1-800 numbers are not offered yet, so 800 is refused like an unknown code. More than 25 codes returns 422 TOO_MANY_AREA_CODES; any other code returns 422 VALIDATION_ERROR naming it in `details.area_codes`. Each account may search 30 times a minute; beyond that, 429 RATE_LIMITED with Retry-After.

Requires `phone_numbers:r`.

## Query parameters

- `area_codes` string
- `limit` integer

## Response `200`

Available numbers. A bare array, not wrapped in data.

- PhoneNumberSearchResult[]: Available numbers. A bare array, not wrapped in data.
  - `phone_number` string, required: E.164
  - `country_code` string, required
  - `area_code` string, nullable, required
  - `region` string, nullable, required: Province or territory, when the area code maps to one.
  - `capabilities` string[], required
  - `monthly_cost_cents` integer, required: Recurring rent in CAD cents, at the tier (local or toll-free) this number would be sold at.
  - `upfront_cost_cents` integer, required: The first month's rent, charged when the number is provisioned.
  - `activation_fee_cents` integer, required: One-time activation fee charged with the first month. Not refunded on release.
  - `currency` 'CAD', required

## Other responses

- `401`: Missing, invalid, revoked or expired API key.
- `402`: The account has no balance, or a LIVE key was used before the first top-up.
- `403`: The API key lacks the permission this operation requires, or the account is suspended or closed.
- `422`: VALIDATION_ERROR (details.area_codes names any code not sold) or TOO_MANY_AREA_CODES.
- `429`: RATE_LIMITED: 30 searches a minute per account, or 100 requests per second.
- `500`: Unexpected server error.
- `502`: NUMBER_SEARCH_FAILED: the carrier search failed.

---

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