Skip to main content

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 (excludes NDC if used with national_destination_code filter).

    Examples:

    Find numbers starting with the pattern. Can be numbers or letters e.g '8226' or 'TACO'

    Example: TACO

    filter[phone_number][ends_with] string

    Filter numbers ending with a pattern (excludes NDC if used with national_destination_code filter).

    Examples:

    Find numbers ending with the pattern. Can be numbers or letters e.g '8226' or 'TACO'

    Example: TACO

    filter[phone_number][contains] string

    Filter numbers containing a pattern (excludes NDC if used with national_destination_code filter).

    Examples:

    Find numbers that contain the pattern. Can be numbers or letters e.g '8226' or 'TACO'

    Example: TACO

    filter[locality] string

    Filter phone numbers by city.

    Examples:

    Example: Chicago

    filter[administrative_area] string

    Find numbers in a particular US state or CA province.

    Examples:

    Must use 2 letter state/province code.

    Example: IL

    filter[country_code] string

    Filter phone numbers by country.

    Examples:

    Must use 2 letter ISO alpha-2 country code

    Example: US

    filter[national_destination_code] string

    Filter by the national destination code of the number.

    Examples:

    Example: 312

    filter[rate_center] string

    Filter phone numbers by rate center. This filter is only applicable to USA and Canada numbers.

    Examples:

    Example: Chicago Heights

    filter[phone_number_type] string

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

    Filter phone numbers by number type.

    filter[features] string[]

    Possible values: [sms, mms, voice, fax, emergency, hd_voice, international_sms, local_calling]

    Filter phone numbers with specific features.

    Examples:

    This filter will also accept a list of features

    Example: voice,sms,hd_voice

    filter[limit] integer

    Limits the number of results.

    Examples:

    Example: 100

    filter[best_effort] boolean

    Filter to determine if best effort results should be included. Only available in USA/CANADA.

    Examples:

    If no numbers are found in specified area, try return numbers from a similar location.

    Example: true

    filter[quickship] boolean

    Filter to exclude phone numbers that need additional time after to purchase to activate. Only applicable for +1 toll_free numbers.

    Examples:

    Example: true

    filter[reservable] boolean

    Filter to ensure only numbers that can be reserved are included in the results.

    Examples:

    Example: true

    filter[exclude_held_numbers] boolean

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

    Examples:

    Example: true

Responses​

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

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

default: Unexpected error

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.

  • ]

Request samples

curl -L 'https://api.telnyx.com/v2/available_phone_numbers' \
-H 'Accept: application/json' \
-H 'Authorization: Bearer <TOKEN>'

Response samples

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