Quickstart - Number Reservations

cURL

Using the Telnyx Number Reservations endpoint you can reserve numbers for 1 day. You can also extend your reservations for a further day, all without purchasing a single number. Now you can maintain a Telnyx number inventory for free!

Check out the Development Environment Setup guide to set up the Telnyx Python SDK and your development environment for this guide.

Reserve a Number

First, you’ll need to search for the number to make sure it’s available. Once you’ve done this, you’re ready to reserve.

Don’t forget to update YOUR_API_KEY here.

curl -X POST \
  --header "Content-Type: application/json" \
  --header "Accept: application/json" \
  --header "Authorization: Bearer YOUR_API_KEY" \
  --data '{
    "phone_numbers": [{"phone_number": "+18665552368"}]
  }' \
  https://api.telnyx.com/v2/number_reservations

The above is a test number. You will have to replace the number field with a number from one of your search results.

Congrats, you’ve just reserved your first phone number using the Telnyx API.

Retrieve All Reservations

curl -X GET \
  --header "Content-Type: application/json" \
  --header "Accept: application/json" \
  --header "Authorization: Bearer YOUR_API_KEY" \
  "https://api.telnyx.com/v2/number_reservations"

Sample Response

{
  "data": [
    {
      "created_at": "2019-07-16T18:47:29.861226Z",
      "customer_reference": null,
      "id": "12367-5678-4024-8c92-56709e67fb61",
      "phone_numbers": [
        {
          "created_at": "2019-07-16T18:47:29.861226Z",
          "expired": false,
          "expired_at": "2019-07-21T18:47:29.783665Z",
          "id": "567412-db32-4b27-678-50de401cab19",
          "phone_number": "+18665552368",
          "record_type": "reserved_phone_number",
          "status": "success",
          "updated_at": "2019-07-16T18:47:37.151673Z"
        }
      ],
      "record_type": "number_reservation",
      "status": "success",
      "updated_at": "2019-07-16T18:47:37.040751Z",
    }
  ],
  "meta": {
    "page_number": 1,
    "page_size": 25,
    "total_pages": 1,
    "total_results": 1
  },
  "url": "/v2/number_reservations"
}

Retrieve a Reservation

curl -X GET \
  --header "Content-Type: application/json" \
  --header "Accept: application/json" \
  --header "Authorization: Bearer YOUR_API_KEY" \
  "https://api.telnyx.com/v2/number_reservations/{number_reservation_id}"

Sample Response

{
  "created_at": "2019-07-16T18:47:29.861226Z",
  "customer_reference": null,
  "id": "12367-5678-4024-8c92-56709e67fb61",
  "phone_numbers": [
    {
      "created_at": "2019-07-16T18:47:29.861226Z",
      "expired": false,
      "expired_at": "2019-07-21T18:47:29.783665Z",
      "id": "567412-db32-4b27-678-50de401cab19",
      "phone_number": "+18665552368",
      "record_type": "reserved_phone_number",
      "status": "success",
      "updated_at": "2019-07-16T18:47:37.151673Z"
    }
  ],
  "record_type": "number_reservation",
  "status": "success",
  "updated_at": "2019-07-16T18:47:37.040751Z",
}

Python

Check out the Development Environment Setup guide to set up the Telnyx Python SDK and your development environment for this guide.

Reserve a Number

First, you’ll need to search for the number to make sure it’s available. Once you’ve done this, you’re ready to reserve.

import telnyx
telnyx.api_key = "YOUR_API_KEY"

telnyx.NumberReservation.create(
  phone_numbers=[{"phone_number": "+18665552368"}]
)

The above is a test number. You will have to replace the number field with a number from one of your search results.

Congrats, you’ve just reserved your first phone number using the Telnyx API.

Retrieve All Reservations

import telnyx
telnyx.api_key = "YOUR_API_KEY"

telnyx.NumberReservation.list()

Sample Response

{
  "data": [
    {
      "created_at": "2019-07-16T18:47:29.861226Z",
      "customer_reference": null,
      "id": "12367-5678-4024-8c92-56709e67fb61",
      "phone_numbers": [
        {
          "created_at": "2019-07-16T18:47:29.861226Z",
          "expired": false,
          "expired_at": "2019-07-21T18:47:29.783665Z",
          "id": "567412-db32-4b27-678-50de401cab19",
          "phone_number": "+18665552368",
          "record_type": "reserved_phone_number",
          "status": "success",
          "updated_at": "2019-07-16T18:47:37.151673Z"
        }
      ],
      "record_type": "number_reservation",
      "status": "success",
      "updated_at": "2019-07-16T18:47:37.040751Z",
    }
  ],
  "meta": {
    "page_number": 1,
    "page_size": 25,
    "total_pages": 1,
    "total_results": 1
  },
  "url": "/v2/number_reservations"
}

Retrieve a Reservation

import telnyx
telnyx.api_key = "YOUR_API_KEY"

telnyx.NumberReservation.retrieve("uuid")

Sample Response

{
  "created_at": "2019-07-16T18:47:29.861226Z",
  "customer_reference": null,
  "id": "12367-5678-4024-8c92-56709e67fb61",
  "phone_numbers": [
    {
      "created_at": "2019-07-16T18:47:29.861226Z",
      "expired": false,
      "expired_at": "2019-07-21T18:47:29.783665Z",
      "id": "567412-db32-4b27-678-50de401cab19",
      "phone_number": "+18665552368",
      "record_type": "reserved_phone_number",
      "status": "success",
      "updated_at": "2019-07-16T18:47:37.151673Z"
    }
  ],
  "record_type": "number_reservation",
  "status": "success",
  "updated_at": "2019-07-16T18:47:37.040751Z",
}

Regulatory

Documents

All Others

For AI Agents

Number Reservations tutorial

Quickstart - Number Reservations

cURL

Reserve a Number

Retrieve All Reservations

Sample Response

Retrieve a Reservation

Sample Response

Python

Reserve a Number

Retrieve All Reservations

Sample Response

Retrieve a Reservation

Sample Response

​Quickstart - Number Reservations

​cURL

​Reserve a Number

​Retrieve All Reservations

​Sample Response

​Retrieve a Reservation

​Sample Response

​Python

​Reserve a Number

​Retrieve All Reservations

​Sample Response

​Retrieve a Reservation

​Sample Response

Quickstart - Number Reservations

cURL

Reserve a Number

Retrieve All Reservations

Sample Response

Retrieve a Reservation

Sample Response

Python

Reserve a Number

Retrieve All Reservations

Sample Response

Retrieve a Reservation

Sample Response