/telnyx-numbers-curl

name: telnyx-numbers-curl
description: >-
  Search, order, and manage phone numbers by location, features, and coverage.
metadata:
  author: telnyx
  product: numbers
  language: curl
  generated_by: telnyx-openapi-pipeline
  contract: v2

<!-- 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 `$TELNYX_API_KEY` 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 /available_phone_numbers`

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `filter` | object | No | Consolidated filter parameter (deepObject style). |

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`

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `phone_numbers` | array[object] | Yes | | | `connection_id` | string (UUID) | No | Identifies the connection associated with this phone number. | | `messaging_profile_id` | string (UUID) | No | Identifies the messaging profile associated with the phone n... | | `billing_group_id` | string (UUID) | No | Identifies the billing group associated with the phone numbe... | | ... | | | +1 optional params in [references/api-details.md](references/api-details.md) |

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.phone_numbers_count`
• `.data.requirements_met`
• `.data.messaging_profile_id`
• `.data.connection_id`

Check number order status

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

`GET /number_orders/{number_order_id}`

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `number_order_id` | string (UUID) | Yes | The number order 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.phone_numbers_count`
• `.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`

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `phone_numbers` | array[object] | Yes | | | `status` | enum (pending, success, failure) | No | The status of the entire reservation. | | `id` | string (UUID) | No | | | `record_type` | string | No | | | ... | | | +3 optional params in [references/api-details.md](references/api-details.md) |

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 /number_reservations/{number_reservation_id}`

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `number_reservation_id` | string (UUID) | Yes | The number reservation ID. |

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

Primary response fields:

• `.d