Skip to main content

Quickstart - Number Search

| cURL | Python | Node | .NET | Ruby |

cURL ​

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.

Sample number search request ​

Note

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"

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…

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[number_type]=toll-free&filter[national_destination_code]=877&filter[limit]=2"

Python ​

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}
)

Node ​

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 Node SDK and your development environment for this guide.

import Telnyx from 'telnyx';

const telnyx = new Telnyx("YOUR_API_KEY");

const { data: numbersList } = await telnyx.availablePhoneNumbers.list({
    filter: {"locality": "Chicago", "administrative_area": "IL", "limit": 2}
});

console.log(numbersList);
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 from 'telnyx';

const telnyx = new Telnyx("YOUR_API_KEY");

const { data: numberList } = await telnyx.availablePhoneNumber.list({
  filter:{"country_code": "US", "national_destination_code": "312", "limit": 2}
});

Searching for NPA and NXX:

import Telnyx from 'telnyx';

const telnyx = new Telnyx("YOUR_API_KEY");

const { data: numberList } = await 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 from 'telnyx';

const telnyx = new Telnyx("YOUR_API_KEY");

const { data: numberList } = await telnyx.availablePhoneNumber.list({
  filter:{"country_code": "US", "locality": "Chicago", "administrative_area": "IL", "limit": 2}
})

Search by Region ​

import Telnyx from 'telnyx';

const telnyx = new Telnyx("YOUR_API_KEY");

const { data: numberList } = await telnyx.availablePhoneNumber.list({
  filter:{"country_code": "US", "administrative_area": "IL", "limit": 2}
});

Search by Toll-Free prefix ​

"800", "888", etc…

import Telnyx from 'telnyx';

const telnyx = new Telnyx("YOUR_API_KEY");

const { data: numberList } = await telnyx.availablePhoneNumber.list({
  filter:{"country_code": "US", "number_type": "toll-free", "national_destination_code": "877", "limit": 2}
});

.NET ​

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 .NET SDK and your development environment for this guide.

using System;
using Telnyx.net.Services.VerifyAPI;
private static string TELNYX_API_KEY ="TELNYX_API_KEY";

Telnyx.TelnyxConfiguration.SetApiKey(TELNYX_API_KEY);
VerificationService verifyService = new VerificationService();

static void NumberSearch ()  {
    var numberSearchService = new Telnyx.NumberSearchService();
    var numberSearchOptions = new Telnyx.NumberSearchOptions(){
        Locality = "Chicago",
        AdministrativeArea = "IL",
        Limit = 2
    };
    numberSearchService.List(numberSearchOptions);
}
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.

using System;
using Telnyx.net.Services.VerifyAPI;
private static string TELNYX_API_KEY ="TELNYX_API_KEY";

Telnyx.TelnyxConfiguration.SetApiKey(TELNYX_API_KEY);
VerificationService verifyService = new VerificationService();

static void NumberSearch ()  {
    var numberSearchService = new Telnyx.NumberSearchService();
    var numberSearchOptions = new Telnyx.NumberSearchOptions(){
        CountryCode = "USA",
        NationalDestinationCode = "312",
        Limit = 2
    };
    numberSearchService.List(numberSearchOptions);
}

Searching for NPA and NXX:

using System;
using Telnyx.net.Services.VerifyAPI;
private static string TELNYX_API_KEY ="TELNYX_API_KEY";

Telnyx.TelnyxConfiguration.SetApiKey(TELNYX_API_KEY);
VerificationService verifyService = new VerificationService();

static void NumberSearch ()  {
    var numberSearchService = new Telnyx.NumberSearchService();
    var numberSearchOptions = new Telnyx.NumberSearchOptions(){
        CountryCode = "USA",
        NationalDestinationCode = "312",
        StartsWith = "359",
        Limit = 2
    };
    numberSearchService.List(numberSearchOptions);
}

Search by city ​

Specifying a country and city.

using System;
using Telnyx.net.Services.VerifyAPI;
private static string TELNYX_API_KEY ="TELNYX_API_KEY";

Telnyx.TelnyxConfiguration.SetApiKey(TELNYX_API_KEY);
VerificationService verifyService = new VerificationService();

static void NumberSearch ()  {
    var numberSearchService = new Telnyx.NumberSearchService();
    var numberSearchOptions = new Telnyx.NumberSearchOptions(){
        CountryCode = "USA",
        AdministrativeArea = "IL",
        Limit = 2
    };
    numberSearchService.List(numberSearchOptions);
}

Search by region ​

using System;
using Telnyx.net.Services.VerifyAPI;
private static string TELNYX_API_KEY ="TELNYX_API_KEY";

Telnyx.TelnyxConfiguration.SetApiKey(TELNYX_API_KEY);
VerificationService verifyService = new VerificationService();

static void NumberSearch ()  {
    var numberSearchService = new Telnyx.NumberSearchService();
    var numberSearchOptions = new Telnyx.NumberSearchOptions(){
        CountryCode = "USA",
        AdministrativeArea = "IL",
        Limit = 2
    };
    numberSearchService.List(numberSearchOptions);
}

Search by Toll-Free prefix ​

"800", "888", etc…

using System;
using Telnyx.net.Services.VerifyAPI;
private static string TELNYX_API_KEY ="TELNYX_API_KEY";

Telnyx.TelnyxConfiguration.SetApiKey(TELNYX_API_KEY);
VerificationService verifyService = new VerificationService();

static void NumberSearch ()  {
    var numberSearchService = new Telnyx.NumberSearchService();
    var numberSearchOptions = new Telnyx.NumberSearchOptions(){
        CountryCode = "USA",
        NumberType = "toll-free",
        NationalDestinationCode = "877",
        Limit = 2
    };
    numberSearchService.List(numberSearchOptions);
}

Ruby ​

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 Ruby SDK and your development environment for this guide.

require "telnyx"

Telnyx.api_key = "YOUR_API_KEY"

Telnyx::AvailablePhoneNumber.list({
  locality: "Chicago", 
  administrative_area: "IL", 
  limit: 2
})
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.

require "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:

require "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.

require "telnyx"

Telnyx.api_key = "YOUR_API_KEY"

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

Search by region ​

require "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…

require "telnyx"

Telnyx.api_key = "YOUR_API_KEY"

Telnyx::AvailablePhoneNumber.list(
  filter:{country_code: "US", number_type: "toll-free", national_destination_code: "877", limit: 2}
)