List available phone numbers

GET 
/available_phone_numbers

List available phone numbers

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:

• generic

Find numbers starting with the prefix 'FREE'

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

• generic

Find numbers ending with the suffix 'CALL'

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

• generic

Find numbers that contain the word 'FOO' within the last 4 digits

Example: FOO

filter[locality] string

Filter phone numbers by city.

Examples:

• US
• CA
• AU

Example: Chicago

Example: Toronto

Example: Canberra

filter[administrative_area] string

Filter phone numbers by US state/CA province.

filter[country_code] string

Filter phone numbers by ISO alpha-2 country code.

filter[national_destination_code] string

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

Examples:

• US
• CA
• AU

Example: 312

Example: 437

Example: 0251

filter[rate_center] string

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

filter[phone_number_type] string

Possible values: [local, toll_free, mobile, national, shared_cost, landline]

Filter phone numbers by number type.

filter[features] string[]

Possible values: [sms, mms, voice, fax, emergency]

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

filter[limit] integer

Limits the number of results.

filter[best_effort] boolean

Filter to determine if best effort results should be included. Only available in NANPA countries.

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.

filter[reservable] boolean

Filter to exclude phone numbers that cannot be reserved before purchase.

filter[exclude_held_numbers] boolean

Filter to exclude phone numbers that are currently on hold for your account.

Responses

200: Successful response with a list of available phone numbers.

application/json

• Schema
• Example (from schema)

Schema

data

object[]

Array [

record_type string

Possible values: [available_phone_number]

phone_number string

vanity_format string

best_effort boolean

Specifies whether the phone number is an exact match based on the search criteria or not.

quickship boolean

Specifies whether the phone number can receive calls immediately after purchase or not.

reservable boolean

Specifies whether the phone number can be reserved before purchase or not.

region_information

RegionInformation[]

Array [

region_type string

Possible values: [country_code, rate_center, state, location]

region_name string

]

cost_information

object

upfront_cost string

monthly_cost string

currency string

The ISO 4217 code for the currency.

features

Feature[]

Array [

name string

]

]

meta

object

total_results integer

best_effort_results integer

{
  "data": [
    {
      "record_type": "available_phone_number",
      "phone_number": "+19705555098",
      "vanity_format": "",
      "best_effort": false,
      "quickship": true,
      "reservable": true,
      "region_information": [
        {
          "region_type": "country_code",
          "region_name": "US"
        }
      ],
      "cost_information": {
        "upfront_cost": "3.21",
        "monthly_cost": "6.54",
        "currency": "USD"
      },
      "features": [
        {
          "name": "sms"
        },
        {
          "name": "voice"
        }
      ]
    }
  ],
  "meta": {
    "total_results": 100,
    "best_effort_results": 50
  }
}

default: Unexpected error

application/json

• Schema
• Example (from schema)

Schema

errors

Error[]

Array [

code integerrequired

title stringrequired

detail string

source

object

pointer json-pointer

JSON pointer (RFC6901) to the offending entity.

parameter string

Indicates which query parameter caused the error.

meta

object

url string

URL with additional information on the error.

]

{
  "errors": [
    {
      "code": "10007",
      "title": "Unexpected error",
      "detail": "An unexpected error occured.",
      "source": {
        "pointer": "/base",
        "parameter": "string"
      },
      "meta": {
        "url": "https://developers.telnyx.com/docs/overview/errors/10015"
      }
    }
  ]
}

Loading...