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.

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

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

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:

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.

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

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…

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.

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

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

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:

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.

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

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…

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.

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

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

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:

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.

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

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…

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.

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

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

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:

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.

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

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…

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.

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

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

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:

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.

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

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…

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

On this page