Advanced Number Search

This guide will cover everything you need to know about performing advanced number searches.

When performing your search, * matches any character; TELE matches "8353"; && matches "11", "22", etc. You can also use consecutive to search for numbers in sequence e.g. xxx-xxx-1234, xxx-xxx-1235.

How to perform an advanced number search

To show all available filters, see the full documentation here

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[features][]=sms&filter[limit][]=2"

Note: Sample results can vary depending on the available numbers at a given moment.

{
  "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": "+18728880024",
      "record_type": "available_phone_number",
      "region_information": [
        {
          "region_name": "US",
          "region_type": "country_code"
        },
        {
          "region_name": "IL",
          "region_type": "state"
        },
        {
          "region_name": "CHICAGO ZONE 02",
          "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": "+18728880026",
      "record_type": "available_phone_number",
      "region_information": [
        {
          "region_name": "US",
          "region_type": "country_code"
        },
        {
          "region_name": "IL",
          "region_type": "state"
        },
        {
          "region_name": "CHICAGO ZONE 02",
          "region_type": "rate_center"
        }
      ],
      "reservable": false,
      "vanity_format": null
    }
  ],
  "metadata": {
    "best_effort_results": 0,
    "total_results": 2
  },
  "url": "/v2/available_phone_numbers"
}

Some example payloads for advanced search requests are detailed below.

Advanced 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.

Note: *The phone_number filter can only be used once per search. For example, if you want to search for a number that starts with "12" and ends with "AB" you could use a starts_with search passing in the following value "12**AB"

The below search is looking for any digits for the first 3 digits (the NPA), followed by a 2, and then a repeated digit.

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][]=877&filter[phone_number][starts_with]=***2&&&filter[limit][]=2"

Advanced Region

Search for numbers in a region with additional filters. The FDN (Fixed Dialer Number) refers to the 4 digits that follow the NXX. Each DID is typically made up of NPA-NXX-FDN. FDN can be searched for using the ends_with parameter.

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[phone_number][ends_with]=ABC*&filter[limit][]=2"

Advanced Rate Center

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[rate_center][]=CHICAGO HEIGHTS&filter[administrative_area][]=IL&filter[limit][]=2"

Limiting Search Results

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"

Feature Search

Limits search results to having certain features. For example, you can choose to search for only SMS enabled numbers by limiting the features parameter to just "sms".

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[features][]=sms&filter[limit][]=2"

You could also search for number with SMS and MMS capabilities.

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[features][]=sms&filter[features][]=mms&filter[limit][]=2"

Possible features: "sms", "mms", "voice", "fax"

Disabling Best Effort Search

By default, best_effort is enabled on all searches. To omit best effort results, set the best_effort key to false in your search request:

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[best_effort][]=false&filter[limit][]=2"