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.

Check out the Development Environment Setup guide to acquire your API Key and set up a Telnyx SDK if applicable.

Copy
Copied
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: After pasting the above content, Kindly check and remove any new line added

Note: Don't forget to update YOUR_API_KEY here.

Sample Number Search Response

Copy
Copied
{
  "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: After pasting the above content, Kindly check and remove any new line added

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.

Copy
Copied
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"

Note: After pasting the above content, Kindly check and remove any new line added

Searching for NPA and NXX:

Copy
Copied
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"

Note: After pasting the above content, Kindly check and remove any new line added

Search by City

Specifying a country and city.

Copy
Copied
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: After pasting the above content, Kindly check and remove any new line added

Search by Region

Copy
Copied
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"

Note: After pasting the above content, Kindly check and remove any new line added

Search by Toll-Free Prefix

"800", "888", etc…

Copy
Copied
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"

Note: After pasting the above content, Kindly check and remove any new line added

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.

Copy
Copied
import telnyx

telnyx.api_key = "YOUR_API_KEY"

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

print(response)

Note: After pasting the above content, Kindly check and remove any new line added

Note: Don't forget to update YOUR_API_KEY here.

Sample Response

Copy
Copied
{
  "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: After pasting the above content, Kindly check and remove any new line added

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.

Copy
Copied
import telnyx
telnyx.api_key = "YOUR_API_KEY"

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

Note: After pasting the above content, Kindly check and remove any new line added

Searching for NPA and NXX:

Copy
Copied
import telnyx
telnyx.api_key = "YOUR_API_KEY"

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

Note: After pasting the above content, Kindly check and remove any new line added

Search by City

Specifying a country and city.

Copy
Copied
import telnyx
telnyx.api_key = "YOUR_API_KEY"

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

Note: After pasting the above content, Kindly check and remove any new line added

Search by Region

Copy
Copied
import telnyx
telnyx.api_key = "YOUR_API_KEY"

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

Note: After pasting the above content, Kindly check and remove any new line added

Search by Toll-Free Prefix

"800", "888", etc…

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

Note: After pasting the above content, Kindly check and remove any new line added

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.

Copy
Copied
const telnyx = require("telnyx")("YOUR_API_KEY");

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

console.log(numbersList);

Note: After pasting the above content, Kindly check and remove any new line added

Note: Don't forget to update YOUR_API_KEY here.

Sample Response

Copy
Copied
{
  "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: After pasting the above content, Kindly check and remove any new line added

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.

Copy
Copied
const telnyx = require("telnyx")("YOUR_API_KEY")

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

Note: After pasting the above content, Kindly check and remove any new line added

Searching for NPA and NXX:

Copy
Copied
const telnyx = require("telnyx")("YOUR_API_KEY")

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

Note: After pasting the above content, Kindly check and remove any new line added

Search by City

Specifying a country and city.

Copy
Copied
const telnyx = require("telnyx")("YOUR_API_KEY")

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

Note: After pasting the above content, Kindly check and remove any new line added

Search by Region

Copy
Copied
const telnyx = require("telnyx")("YOUR_API_KEY")

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

Note: After pasting the above content, Kindly check and remove any new line added

Search by Toll-Free Prefix

"800", "888", etc…

Copy
Copied
const telnyx = require("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}
});

Note: After pasting the above content, Kindly check and remove any new line added

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

Copy
Copied
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: After pasting the above content, Kindly check and remove any new line added

Note: Don't forget to update YOUR_API_KEY here.

Sample Response

Copy
Copied
{
  "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: After pasting the above content, Kindly check and remove any new line added

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.

Copy
Copied
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);
}

Note: After pasting the above content, Kindly check and remove any new line added

Searching for NPA and NXX:

Copy
Copied
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);
}

Note: After pasting the above content, Kindly check and remove any new line added

Search by City

Specifying a country and city.

Copy
Copied
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);
}

Note: After pasting the above content, Kindly check and remove any new line added

Search by Region

Copy
Copied
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);
}

Note: After pasting the above content, Kindly check and remove any new line added

Search by Toll-Free Prefix

"800", "888", etc…

Copy
Copied
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);
}

Note: After pasting the above content, Kindly check and remove any new line added

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.

Copy
Copied
require "telnyx"

Telnyx.api_key = "YOUR_API_KEY"

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

Note: After pasting the above content, Kindly check and remove any new line added

Note: Don't forget to update YOUR_API_KEY here.

Sample Response

Copy
Copied
{
  "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: After pasting the above content, Kindly check and remove any new line added

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.

Copy
Copied
require "telnyx"

Telnyx.api_key = "YOUR_API_KEY"

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

Note: After pasting the above content, Kindly check and remove any new line added

Searching for NPA and NXX:

Copy
Copied
require "telnyx"

Telnyx.api_key = "YOUR_API_KEY"

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

Note: After pasting the above content, Kindly check and remove any new line added

Search by City

Specifying a country and city.

Copy
Copied
require "telnyx"

Telnyx.api_key = "YOUR_API_KEY"

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

Note: After pasting the above content, Kindly check and remove any new line added

Search by Region

Copy
Copied
require "telnyx"

Telnyx.api_key = "YOUR_API_KEY"

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

Note: After pasting the above content, Kindly check and remove any new line added

Search by Toll-Free Prefix

"800", "888", etc…

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

Note: After pasting the above content, Kindly check and remove any new line added