<!-- Auto-generated from Telnyx OpenAPI specs. Do not edit. -->

Telnyx Numbers - curl

Installation

# curl is pre-installed on macOS, Linux, and Windows 10+

Setup

export TELNYX_API_KEY="YOUR_API_KEY_HERE"

All examples below use $TELNYXAPIKEY for authentication.

Error Handling

All API calls can fail with network errors, rate limits (429), validation errors (422), or authentication errors (401). Always handle errors in production code:

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

Common error codes: 401 invalid API key, 403 insufficient permissions, 404 resource not found, 422 validation error (check field formats), 429 rate limited (retry with exponential backoff).

Important Notes

• Phone numbers must be in E.164 format (e.g., +13125550001). Include the + prefix and country code. No spaces, dashes, or parentheses.
• Pagination: List endpoints return paginated results. Use page[number] and page[size] query parameters to navigate pages. Check meta.total_pages in the response.

Reference Use Rules

Do not invent Telnyx parameters, enums, response fields, or webhook fields.

• If the parameter, enum, or response field you need is not shown inline in this skill, read [references/api-details.md](references/api-details.md) before writing code.
• Before using any operation in ## Additional Operations, read [the optional-parameters section](references/api-details.md#optional-parameters) and [the response-schemas section](references/api-details.md#response-schemas).

Core Tasks

Search available phone numbers

Number search is the entrypoint for provisioning. Agents need the search method, key query filters, and the fields returned for candidate numbers.

GET /availablephonenumbers

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

Response wrapper:

• items: .data
• pagination: .meta

Primary item fields:

• phone_number
• record_type
• quickship
• reservable
• best_effort
• cost_information

Create a number order

Number ordering is the production provisioning step after number selection.

POST /number_orders

curl \
  -X POST \
  -H "Authorization: Bearer $TELNYX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
      "phone_numbers": [
          {
              "phone_number": "+18005550101"
          }
      ]
  }' \
  "https://api.telnyx.com/v2/number_orders"

Primary response fields:

• .data.id
• .data.status
• .data.phonenumberscount
• .data.requirements_met
• .data.messagingprofileid
• .data.connection_id

Check number order status

Order status determines whether provisioning completed or additional requirements are still blocking fulfillment.

GET /numberorders/{numberorder_id}

curl -H "Authorization: Bearer $TELNYX_API_KEY" "https://api.telnyx.com/v2/number_orders/550e8400-e29b-41d4-a716-446655440000"

Primary response fields:

• .data.id
• .data.status
• .data.requirements_met
• .data.phonenumberscount
• .data.phone_numbers
• .data.connection_id

Important Supporting Operations

Use these when the core tasks above are close to your flow, but you need a common variation or follow-up step.

Create a number reservation

Create or provision an additional resource when the core tasks do not cover this flow.

POST /number_reservations

curl \
  -X POST \
  -H "Authorization: Bearer $TELNYX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
      "phone_numbers": [
          {
              "phone_number": "+18005550101"
          }
      ]
  }' \
  "https://api.telnyx.com/v2/number_reservations"

Primary response fields:

• .data.id
• .data.status
• .data.created_at
• .data.updated_at
• .data.customer_reference
• .data.errors

Retrieve a number reservation

Fetch the current state before updating, deleting, or making control-flow decisions.

GET /numberreservations/{numberreservation_id}

curl -H "Authorization: Bearer $TELNYX_API_KEY" "https://api.telnyx.com/v2/number_reservations/550e8400-e29b-41d4-a716-446655440000"

Primary response fields:

• .data.id
• .data.status
• .data.created_at
• .data.updated_at
• .data.customer_reference
• .data.errors

List Advanced Orders

Inspect available resources or choose an existing resource before mutating it.

GET /advanced_orders

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

Response wrapper:

• items: .data

Primary item fields:

• id
• status
• area_code
• comments
• country_code
• customer_reference

Create Advanced Order

Create or provision an additional resource when the core tasks do not cover this flow.

POST /advanced_orders

curl \
  -X POST \
  -H "Authorization: Bearer $TELNYX_API_KEY" \
  -H "Content-Type: application/json" \
  "https://api.telnyx.com/v2/advanced_orders"

Primary response fields:

• .data.id
• .data.status
• .data.area_code
• .data.comments
• .data.country_code
• .data.customer_reference

Update Advanced Order

Modify an existing resource without recreating it.

PATCH /advancedorders/{advanced-order-id}/requirementgroup

curl \
  -X PATCH \
  -H "Authorization: Bearer $TELNYX_API_KEY" \
  -H "Content-Type: application/json" \
  "https://api.telnyx.com/v2/advanced_orders/{advanced-order-id}/requirement_group"

Primary response fields:

• .data.id
• .data.status
• .data.area_code
• .data.comments
• .data.country_code
• .data.customer_reference

Get Advanced Order

Fetch the current state before updating, deleting, or making control-flow decisions.

GET /advancedorders/{orderid}

curl -H "Authorization: Bearer $TELNYX_API_KEY" "https://api.telnyx.com/v2/advanced_orders/{order_id}"

Primary response fields:

• .data.id
• .data.status
• .data.area_code
• .data.comments
• .data.country_code
• .data.customer_reference

List available phone number blocks

Inspect available resources or choose an existing resource before mutating it.

GET /availablephonenumber_blocks

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

Response wrapper:

• items: .data
• pagination: .meta

Primary item fields:

• phone_number
• cost_information
• features
• range
• record_type
• region_information

Retrieve all comments

Inspect available resources or choose an existing resource before mutating it.

GET /comments

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

Response wrapper:

• items: .data
• pagination: .meta

Primary item fields:

• id
• body
• created_at
• updated_at
• commentrecordid
• commentrecordtype

Additional Operations

Use the core tasks above first. The operations below are indexed here with exact SDK methods and required params; use [references/api-details.md](references/api-details.md) for full optional params, response schemas, and lower-frequency webhook payloads. Before using any operation below, read [the optional-parameters section](references/api-details.md#optional-parameters) and [the response-schemas section](references/api-details.md#response-schemas) so you do not guess missing fields.

Other Webhook Events

For exhaustive optional parameters, full response schemas, and complete webhook payloads, see [references/api-details.md](references/api-details.md).