---
title: "Search for Available Phone Numbers"
method: POST
path: "/phone-numbers/search"
tags: ["phoneNumbers"]
---

# Search for Available Phone Numbers

`POST /phone-numbers/search`

## Request

- Base URL: `https://api.pinnacle.sh`
- URL: `https://api.pinnacle.sh/phone-numbers/search`
- Auth: API key in header `PINNACLE-API-KEY`

Search for available phone numbers that match your exact criteria.

## Request body

- SearchSchema: Search criteria for finding available phone numbers that match your specific requirements. <br> Combine filters to narrow down results to numbers that fit your business needs.
  - `features` PHONEFEATURES[]
  - `location` SearchPhoneNumberByLocation: Filter your search by geographic location to find numbers in specific regions. <br> Toll-free numbers ignore city and state filters.
    - `city` string: Search for numbers in your target city.
    - `countryCode` 'US': Currently, only US numbers are supported.
    - `nationalDestinationCode` string: Narrow your search to a specific area or exchange code. <br> For US numbers, this is usually the 3-digit area code.
    - `state` string: Search for numbers in your target state or province using a two-letter code.
  - `number` SearchPhoneNumberByDigits: Filter your search by digit pattern.
    - `contains` string: Your search will return only numbers that contain this digit sequence anywhere within them.
    - `endsWith` string: Your search will return only numbers that end with these digits.
    - `startsWith` string: Your search will return only numbers that begin with these digits.
  - `options` SearchPhoneNumberOptions: Extra search settings to control how many results you get.
    - `limit` integer: Set the maximum number of phone numbers to return.
  - `type` PHONETYPESSCHEMA[], required: Types of phone numbers to return in your search.

## Response `200`

Returns a **list** of available phone numbers that match the search criteria. <br>

Use our [buy endpoint](./buy) to purchase any amount of phone numbers that you like.

- PhoneNumber[]
  - `number` string, required: Phone number in E.164 format.
  - `phone_type` 'LOCAL' | 'TOLL_FREE', required: Classification of phone number types based on their billing and geographic properties. <br> Determines pricing structure and availability patterns.
  - `cost` PhoneNumberCost, required: Pricing details for the phone number.
    - `monthly` number, double, required: Recurring monthly fee covering number ownership and basic services.
    - `upfront` number, double, required: One-time activation or setup fee charged at purchase.
    - `currency` string, required: Three-letter currency code for all pricing values.
  - `features` PHONEFEATURES[], required: Supported communication capabilities associated with the number.
  - `region` PhoneNumberRegion, required: Geographic and routing information for the phone number.
    - `country` string, required: Two-letter country code where the number is registered.
    - `state` string: State or province code applicable to local numbers.
    - `city` string: Primary city or metropolitan area served by the number.
    - `rateCenter` string: Telecommunications rate center used for call routing and billing, defining local calling area boundaries.

## Other responses

- `400`: Validation failed. The payload has missing required fields and/or invalid types. <br> See https://zod.dev/error-formatting for more information.
- `401`: The request lacks valid authentication credentials or the provided credentials are invalid. <br> Ensure you're including a valid API key in the request headers and that your account has the necessary permissions to access this endpoint.
- `403`: Your subscription does not include access to this feature. <br> This occurs when attempting to use functionality that requires a higher subscription tier. Please upgrade your subscription to access this feature.
- `500`: An unexpected error occurred on Pinnacle's servers while processing your request. <br> If this error persists, please contact support with the request details.

---

[API](https://skmtc.dev/pinnacle/apis/pinnacle-2.md) - [All operations](https://skmtc.dev/pinnacle/apis/pinnacle-2/llms.txt) - [OpenAPI document](https://skmtc.dev/pinnacle/apis/pinnacle-2/revisions/45416dadab79?raw)