Number Search API

Number search API

List available phone number blocks

SecuritybearerAuth
Request
query Parameters
filter[phone_number][starts_with]
string

Filter number blocks that start with a pattern (meant to be used after national_destination_code filter has been set).

Example: filter[phone_number][starts_with]=201
filter[phone_number][ends_with]
string

Filter numbers ending with a pattern.

Example: filter[phone_number][ends_with]=8000
filter[phone_number][contains]
string

Filter numbers containing a pattern.

Example: filter[phone_number][contains]=456
filter[locality]
string

Filter phone numbers by city.

Examples:
filter[locality]=Canberra
filter[locality]=Toronto
filter[locality]=Chicago
filter[administrative_area]
string

Filter phone numbers by US state/CA province.

Example: filter[administrative_area]=IL
filter[country_code]
string

Filter phone numbers by ISO alpha-2 country code.

Example: filter[country_code]=US
filter[national_destination_code]
string

Filter by the national destination code of the number. This filter is only applicable to North American numbers.

Examples:
filter[national_destination_code]=0251
filter[national_destination_code]=437
filter[national_destination_code]=312
filter[rate_center]
string

Filter phone numbers by NANP rate center. This filter is only applicable to North American numbers.

Example: filter[rate_center]=CHICAGO HEIGHTS
filter[number_type]
string

Filter phone numbers by number type.

Value: "toll-free"
Example: filter[number_type]=toll-free
filter[features]
Array of strings

Filter if the phone number should be used for voice, fax, mms, sms, emergency.

Items Enum: "sms" "mms" "voice" "fax" "emergency"
Example: filter[features]=voice,sms
filter[minimum_block_size]
integer

Filter number blocks by minimum blocks size

Example: filter[minimum_block_size]=100
filter[limit]
integer

Limits the number of results.

Example: filter[limit]=100
Responses
200

Successful response with a list of available phone numbers blocks.

Response Schema: application/json
Array of objects (AvailablePhoneNumberBlock)
object (AvailablePhoneNumbersMetadata)
default

Unexpected error

Response Schema: application/json
Array of objects (Error)
Array
code
required
string <int>
detail
string
meta
object
object
title
required
string
get/available_phone_number_blocks
Request samples 
Response samples 
application/json
{
  • "data": [
    • {
      • "cost_information": {
        • "currency": "USD",
        • "monthly_cost": "6.54",
        • "upfront_cost": "3.21"
        },
      • "features": [
        • {
          • "name": "sms"
          },
        • {
          • "name": "voice"
          }
        ],
      • "phone_number": "+19705555000",
      • "range": 10,
      • "record_type": "available_phone_number_block",
      • "region_information": [
        • {
          • "region_name": "US",
          • "region_type": "country_code"
          }
        ]
      }
    ],
  • "meta": {
    • "best_effort_results": 50,
    • "total_results": 100
    }
}
List available phone numbers
SecuritybearerAuth 
Request 
query Parameters
filter[phone_number][starts_with]
string
Filter numbers starting with a pattern (exclude NDC from start of this filter if used with national_destination_code filter).


  Examples: 
filter[phone_number][starts_with]=FREE
filter[phone_number][ends_with]
string
Filter numbers ending with a pattern (max length of 4 digits if used with national_destination_code filter).


  Examples: 
filter[phone_number][ends_with]=CALL
filter[phone_number][contains]
string
Filter numbers containing a pattern (must be used with national_destination_code filter and only searches within last 4 digits).


  Examples: 
filter[phone_number][contains]=FOO
filter[locality]
string
Filter phone numbers by city.


  Examples: 
filter[locality]=Canberra
filter[locality]=Toronto
filter[locality]=Chicago
filter[administrative_area]
string
Filter phone numbers by US state/CA province.


 
 Example:  filter[administrative_area]=IL
filter[country_code]
string
Filter phone numbers by ISO alpha-2 country code.


 
 Example:  filter[country_code]=US
filter[national_destination_code]
string
Filter by the national destination code of the number. This filter is only applicable to North American numbers.


  Examples: 
filter[national_destination_code]=0251
filter[national_destination_code]=437
filter[national_destination_code]=312
filter[rate_center]
string
Filter phone numbers by NANP rate center. This filter is only applicable to North American numbers.


 
 Example:  filter[rate_center]=CHICAGO HEIGHTS
filter[phone_number_type]
string
Filter phone numbers by number type.


 Enum: "local" "toll_free" "mobile" "national" "shared_cost" "landline"  
 Example:  filter[phone_number_type]=local
filter[features]
Array of strings
Filter if the phone number should be used for voice, fax, mms, sms, emergency.


Items Enum: "sms" "mms" "voice" "fax" "emergency"  
 Example:  filter[features]=voice,sms
filter[limit]
integer
Limits the number of results.


 
 Example:  filter[limit]=100
filter[best_effort]
boolean
Filter to determine if best effort results should be included. Only available in NANPA countries.


 
 Example:  filter[best_effort]=false
filter[quickship]
boolean
Filter to exclude phone numbers that need additional time after to purchase to receive phone calls. Only available for toll-free numbers.


 
 Example:  filter[quickship]=true
filter[reservable]
boolean
Filter to exclude phone numbers that cannot be reserved before purchase.


 
 Example:  filter[reservable]=true
filter[exclude_held_numbers]
boolean
Filter to exclude phone numbers that are currently on hold for your account.


 
 Example:  filter[exclude_held_numbers]=false
Responses 
200
Successful response with a list of available phone numbers.


Response Schema: application/json
Array of objects (AvailablePhoneNumber) 
 
object (AvailablePhoneNumbersMetadata) 
 
default
Unexpected error


Response Schema: application/json
Array of objects (Error) 
 
 Array 
code
required
string <int> 
 
detail
string
 
meta
object
 
object
 
title
required
string
 
get/available_phone_numbers
Request samples 
import telnyx
telnyx.api_key = "YOUR_API_KEY"

telnyx.AvailablePhoneNumber.list(filter={"rate_center": "CHICAGO HEIGHTS"})
Response samples 
application/json
{
  • "data": [
    • {
      • "best_effort": false,
      • "cost_information": {
        • "currency": "USD",
        • "monthly_cost": "6.54",
        • "upfront_cost": "3.21"
        },
      • "features": [
        • {
          • "name": "sms"
          },
        • {
          • "name": "voice"
          }
        ],
      • "phone_number": "+19705555098",
      • "quickship": true,
      • "record_type": "available_phone_number",
      • "region_information": [
        • {
          • "region_name": "US",
          • "region_type": "country_code"
          }
        ],
      • "reservable": true,
      • "vanity_format": ""
      }
    ],
  • "meta": {
    • "best_effort_results": 50,
    • "total_results": 100
    }
}