• Choose:

Number Search - Finding The Perfect Phone Number

You can search for numbers by region, number, prefix, rate center, type, or enabled features.

The example below shows a generic number search for two phone numbers.

Check out the Development Environment Setup guide to set up the Telnyx Python SDK and your development environment for this guide.

import telnyx

telnyx.api_key = "YOUR_API_KEY"

response = telnyx.AvailablePhoneNumber.list(
  filter={"locality": "Chicago", "administrative_area": "IL", "limit": 2}
)

print(response)

Note: Don't forget to update YOUR_API_KEY here.

Sample Response

{
  "data": [
    {
      "best_effort": false,
      "cost_information": {
        "currency": "USD",
        "monthly_cost": "1.00000",
        "upfront_cost": "1.00000"
      },
      "features": [
        {
          "name": "fax"
        },
        {
          "name": "voice"
        },
        {
          "name": "sms"
        }
      ],
      "phone_number": "+17732490564",
      "record_type": "available_phone_number",
      "region_information": [
        {
          "region_name": "US",
          "region_type": "country_code"
        },
        {
          "region_name": "IL",
          "region_type": "state"
        },
        {
          "region_name": "CHICAGO ZONE 11",
          "region_type": "rate_center"
        }
      ],
      "reservable": false,
      "vanity_format": null
    },
    {
      "best_effort": false,
      "cost_information": {
        "currency": "USD",
        "monthly_cost": "1.00000",
        "upfront_cost": "1.00000"
      },
      "features": [
        {
          "name": "fax"
        },
        {
          "name": "voice"
        },
        {
          "name": "sms"
        }
      ],
      "phone_number": "+17732490565",
      "record_type": "available_phone_number",
      "region_information": [
        {
          "region_name": "US",
          "region_type": "country_code"
        },
        {
          "region_name": "IL",
          "region_type": "state"
        },
        {
          "region_name": "CHICAGO ZONE 11",
          "region_type": "rate_center"
        }
      ],
      "reservable": false,
      "vanity_format": null
    }
  ],
  "metadata": {
    "best_effort_results": 0,
    "total_results": 2
  },
  "url": "/v2/available_phone_numbers"
}

Note that searches for international numbers may have additional requirements. This is covered in depth in our International Number Search & Order guide.

Some example payloads for search requests are detailed below.

Search by NPA/NXX

"NPA" stands for Number Plan Area, commonly called Area Code. "NXX" refers to the three digits of a phone number immediately following the area code, also called the "exchange" or the Central Switching Office Designation. Each DID is typically made up of NPA-NXX-FDN. The FDN (Fixed Dialer Number) refers to the 4 digits that follow the NXX.

The national_destination_code parameter can be set to search by NPA.

import telnyx
telnyx.api_key = "YOUR_API_KEY"

telnyx.AvailablePhoneNumber.list(
  filter={"country_code": "US", "national_destination_code": "312", "limit": 2}
)

Searching for NPA and NXX:

import telnyx
telnyx.api_key = "YOUR_API_KEY"

telnyx.AvailablePhoneNumber.list(
  filter={"country_code": "US", "national_destination_code": "312", "starts_with": "359", "limit": 2}
)

Search by City

Specifying a country and city.

import telnyx
telnyx.api_key = "YOUR_API_KEY"

telnyx.AvailablePhoneNumber.list(
  filter={"country_code": "US", "locality": "Chicago", "administrative_area": "IL", "limit": 2}
)

Search by Region

import telnyx
telnyx.api_key = "YOUR_API_KEY"

telnyx.AvailablePhoneNumber.list(
  filter={"country_code": "US", "administrative_area": "IL", "limit": 2}
)

Search by Toll-Free Prefix

"800", "888", etc…

import telnyx
telnyx.api_key = "YOUR_API_KEY"

telnyx.AvailablePhoneNumber.list(
  filter={"country_code": "US", "number_type": "toll-free", "national_destination_code": "877", "limit": 2}
)
Was this page helpful?