---
title: "Search available numbers"
method: GET
path: "/v1/telephony/available"
tags: ["Telephony"]
---

# Search available numbers

`GET /v1/telephony/available`

## Request

- Base URL: `https://api.pyai.com`
- URL: `https://api.pyai.com/v1/telephony/available`
- Auth: one of:
  - HTTP bearer
  - API key in header `x-api-key`

Search PyAI's managed number inventory in the US, Canada, or India. `country` selects the market (US default; India numbers are subject to regulatory review). Filter by `area_code` (NPA, US and Canada) or a `contains` digit pattern. Monthly line prices are $1 for US and Canada numbers and $6 for India numbers. The response's `provisioning` field reports whether automated ordering is available or assisted ordering is required. Requires the `telephony:manage` scope.

## Query parameters

- `country` 'US' | 'CA' | 'IN'
- `area_code` string
- `contains` string
- `limit` integer

## Response `200`

Available numbers

- object
  - `object` string
  - `data` TelephonyAvailableNumber[]
    - `object` string
    - `phone_number` string: E.164.
    - `country` string
    - `area_code` string, nullable
    - `locality` string, nullable
    - `region` string, nullable
    - `capabilities` object
      - `voice` boolean
      - `sms` boolean
    - `monthly_cost_cents` integer: Monthly line price in USD cents ($1 for US/Canada, $6 for India).
  - `provisioning` TelephonyProvisioningStatus
    - `mode` 'automated' | 'assisted', required
    - `capability` string, required
    - `message` string, required

## Other responses

- `401`: Missing or invalid API key (`code: unauthorized`)
- `404`: Telephony is not enabled for this deployment.

---

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