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 acquire your API Key and set up a Telnyx SDK if applicable.

curl -X GET \
  --header "Accept: application/json" \
  --header "Authorization: Bearer YOUR_API_KEY" \
  --globoff "https://api.telnyx.com/v2/available_phone_numbers?filter[country_code]=us&filter[locality]=Chicago&filter[administrative_area]=IL&filter[limit]=2"

Note: Don't forget to update YOUR_API_KEY here.

Sample Number Search 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.

curl -X GET \
  --header "Accept: application/json" \
  --header "Authorization: Bearer YOUR_API_KEY" \
  --globoff "https://api.telnyx.com/v2/available_phone_numbers?filter[country_code]=US&filter[national_destination_code]=312&filter[limit]=2"

Searching for NPA and NXX:

curl -X GET \
  --header "Accept: application/json" \
  --header "Authorization: Bearer YOUR_API_KEY" \
  --globoff "https://api.telnyx.com/v2/available_phone_numbers?filter[country_code]=US&filter[national_destination_code]=312&filter[phone_number][starts_with]=359&filter[limit]=2"

Search by City

Specifying a country and city.

curl -X GET \
  --header "Accept: application/json" \
  --header "Authorization: Bearer YOUR_API_KEY" \
  --globoff "https://api.telnyx.com/v2/available_phone_numbers?filter[country_code]=US&filter[locality]=Chicago&filter[administrative_area]=IL&filter[limit]=2"

Search by Region

curl -X GET \
  --header "Accept: application/json" \
  --header "Authorization: Bearer YOUR_API_KEY" \
  --globoff "https://api.telnyx.com/v2/available_phone_numbers?filter[country_code]=US&filter[administrative_area]=IL&filter[limit]=2"

Search by Toll-Free Prefix

"800", "888", etc…