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
NoteCheck 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)
NoteDon'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.
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);
NoteDon'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.
const telnyx = require("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:
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}
});
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}
})
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}
});
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}
});
.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);
}
NoteDon'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
})
NoteDon'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}
)