Search Available Phone Numbers with the Telnyx CLI

The telnyx available-phone-numbers list command searches Telnyx's number inventory by country, region, number type, and features. It is a read-only search: it does not reserve or purchase anything.

What you will build

A set of CLI searches that narrow the inventory from "any US number" down to local numbers in one state that support both SMS and voice, plus the responses you get for empty and invalid searches.

filters (country, state, type, features, limit)
        |
        v
telnyx available-phone-numbers list
        |
        v
data[]  : matching numbers with region_information and features
meta    : total_results, best_effort_results

AI Prompt

Using the Telnyx CLI, search for available phone numbers in California that support both SMS and voice, and show the phone number, state, and features for three results.

Requirements:
- Install the CLI with `go install github.com/team-telnyx/telnyx-cli/cmd/[email protected]` and authenticate with the TELNYX_API_KEY environment variable.
- Pass search criteria with a single `--filter` flag holding a YAML-style map, for example `--filter '{country_code: US, administrative_area: CA, features: [sms, voice], limit: 3}'`. The `features` value must be a list.
- Use `--format json` and a `--transform` GJSON expression to trim the output to the fields you need.
- The search does not change the account. It does not add numbers to the account's phone number list.
- Run the verification step below before finishing.

Prerequisites

• Go installed, to run go install. The CLI binary lands in $GOBIN (or $GOPATH/bin), which must be on your PATH.
• A Telnyx API key exported as an environment variable:

export TELNYX_API_KEY="<your Telnyx API key>"
go install github.com/team-telnyx/telnyx-cli/cmd/[email protected]
telnyx --version

telnyx version 0.32.0

Note: Output below is trimmed with --transform to the fields relevant to each step. Phone numbers come from live inventory, so the numbers you receive will differ.

1. Search with only a country

telnyx available-phone-numbers list \
  --filter '{country_code: US, limit: 1}' \
  --transform 'meta' \
  --format json

Real output:

{
  "total_results": 1,
  "best_effort_results": 0
}

total_results counts the numbers returned for this request, which limit bounds.

2. Narrow by state and features

telnyx available-phone-numbers list \
  --filter '{country_code: US, administrative_area: CA, features: [sms, voice], limit: 3}' \
  --transform 'data.#.{phone_number:phone_number,state:region_information.#(region_type=="state").region_name,features:features.#.name}' \
  --format json

Real output:

[
  {
    "phone_number": "+19098530209",
    "state": "CA",
    "features": ["sms", "voice", "mms", "hd_voice", "emergency", "fax"]
  },
  {
    "phone_number": "+16504597243",
    "state": "CA",
    "features": ["sms", "voice", "mms", "hd_voice", "emergency", "fax"]
  },
  {
    "phone_number": "+18583395476",
    "state": "CA",
    "features": ["sms", "voice", "mms", "hd_voice", "emergency", "fax"]
  }
]

3. Filter by number type or area code

Toll-free numbers:

telnyx available-phone-numbers list \
  --filter '{country_code: US, phone_number_type: toll_free, limit: 2}' \
  --transform 'data.#.phone_number_type' \
  --format json

Real output:

["toll_free", "toll_free"]

A single area code, using national_destination_code:

telnyx available-phone-numbers list \
  --filter '{country_code: US, national_destination_code: "415", limit: 2}' \
  --transform 'data.#.phone_number' \
  --format json

The area code is quoted so it is read as a string. In a run of the second command, the response contained a number beginning with +1415.

4. Confirm that searching does not change the account

curl -s "https://api.telnyx.com/v2/phone_numbers" \
  -H "Authorization: Bearer $TELNYX_API_KEY"

Real output after the searches above:

{"data":[],"meta":{"total_pages":0,"total_results":0,"page_number":1,"page_size":100}}

Verify the result

Re-run the search from step 2 and check that every returned number reports CA as its state and includes both sms and voice:

telnyx available-phone-numbers list \
  --filter '{country_code: US, administrative_area: CA, features: [sms, voice], limit: 3}' \
  --transform 'data.#.{phone_number:phone_number,state:region_information.#(region_type=="state").region_name,features:features.#.name}' \
  --format json

Expected: three entries, each with "state": "CA" and both sms and voice in features. The specific numbers and the order of items inside features vary between runs because they depend on live inventory.

How it works

The CLI sends the --filter map as filter[...] query parameters to GET /v2/available_phone_numbers. limit caps the result count. A request for limit: 1000 returned total_results: 500, and limit: 0 was rejected with a 400. Each result carries region_information entries (rate center, location, country code, state) and a features list, which is why the transform in step 2 can read the state back out of the response.

Common issues

The features filter is rejected as a string

Passing --filter.features sms fails with string was used where sequence is expected. Pass a list instead, as in features: [sms, voice].

An unsupported country code returns a 400 with exit code 1

A search with country_code: ZZ returns HTTP 400, error code 10015, with the detail No coverage found in the specified country based on the provided search parameters. The CLI exits with status 1.

A search with no matches returns a 400, not an empty list

A search for locality: Nowhereville in the US returns HTTP 400, error code 10031, with the detail No numbers found for the given filters. Please try again with best_effort=true. Adding best_effort: true to that same search returned a successful response with an empty data list and total_results: 0, so the suggestion does not always produce results.

An unknown feature name is rejected without listing valid values

features: [teleportation] returns HTTP 400, error code 10015. The detail field is Invalid query parameters: {'features': {0: ["'teleportation' is not a valid Features"]}}. Use feature names that appear in the features field of real results, such as sms, voice, mms, hd_voice, emergency, and fax.

Cost fields can read zero

Each result includes a cost_information object. On the account used for this guide, monthly_cost and upfront_cost were 0.00000. Confirm pricing on the Telnyx pricing page or at order time instead of relying on these fields.

Next steps

• Configure a messaging profile so a number you order can send and receive SMS: 02-configure-a-messaging-profile-with-the-telnyx-cli.md.
• Create a call control application that receives voice webhooks: 03-configure-a-call-control-application-with-typescript.md.

verification:
  status: verified
  tested_at: "2026-10-06"
  product_version: "telnyx CLI 0.32.0"
  command: "telnyx available-phone-numbers list --filter '{country_code: US, administrative_area: CA, features: [sms, voice], limit: 3}' --transform 'data.#.{phone_number:phone_number,state:region_information.#(region_type==\"state\").region_name,features:features.#.name}' --format json"
  expected_result: "Three entries, each with state CA and both sms and voice in features. Specific numbers and the order of items in features vary with live inventory."