---
title: "Search available phone numbers"
method: GET
path: "/v1/phone-number/available"
tags: ["Phone Number"]
---

# Search available phone numbers

`GET /v1/phone-number/available`

## Request

- Base URL: `https://api.roark.ai`
- URL: `https://api.roark.ai/v1/phone-number/available`
- Auth: HTTP bearer

Returns US or Canadian numbers the carrier has for sale, local or toll-free, narrowed by area code or by digits the number must contain. When an area code has no numbers, nearby ones are returned flagged bestEffort; an empty list means nothing matched. Buy one with POST /v1/phone-number, or let Roark pick with autoPick.

## Query parameters

- `country` 'US' | 'CA': ISO 3166-1 alpha-2 country of the number: US or CA
- `numberType` 'LOCAL' | 'TOLL_FREE': LOCAL for a number in an area code, TOLL_FREE for one from the shared US and Canada toll-free pool
- `areaCode` string: Three-digit area code, or a toll-free prefix such as 800. When it has no numbers, nearby ones are returned instead, flagged bestEffort.
- `contains` string: Digits or letters the number must contain (1 to 7, * matches any digit)
- `limit` integer: Maximum number of results (default: 20, max: 100)

## Response `200`

Numbers available to buy

- object
  - `data` AvailablePhoneNumberResponse[], required
    - `e164` string, required: The number in E.164 format
    - `region` string, nullable, required: Region the carrier lists, e.g. a state code
    - `locality` string, nullable, required: Locality the carrier lists, e.g. a city
    - `bestEffort` boolean, required: True when the area code asked for had no numbers and the carrier offered this nearby one instead

## Other responses

- `400`: Bad Request
- `401`: Unauthorized
- `403`: Forbidden
- `500`: Internal Server Error

## Changes

> 187 revisions in range; 1 not diffed.

- **2026-10-28** `f7faf263170a`: 4 info
  - added the new optional `query` request parameter `country`
  - added the new optional `query` request parameter `numberType`
  - for the `query` request parameter `limit`, the max was increased from `50.00` to `100.00`
  - added the required property `data/items/bestEffort` to the response with the `200` status
- **2026-10-26** `0fb1c3b1940a`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/roarkhq/apis/roark-analytics-api/changes/v1/phone-number/available/get.md)

---

[API](https://skmtc.dev/roarkhq/apis/roark-analytics-api.md) - [All operations](https://skmtc.dev/roarkhq/apis/roark-analytics-api/llms.txt) - [OpenAPI document](https://skmtc.dev/roarkhq/apis/roark-analytics-api/revisions/1a91a5c90e44?raw)