Number Reservations

The Phone Number Reservations API lets you "reserve" phone numbers for 30 minutes. During this period, you have exclusive rights to search for and order the reserved phone number. After 30 minutes, the number is returned to the available pool, making it accessible for other users to search for and order.

Search for reservable phone numbers

Not all phone numbers are reservable.

To ensure only reservable phone numbers are included in your search results, add the filters filter[reservable]=true and filter[exclude_held_numbers]=true to your search request.

A sample request is shown below:

Request Sample

Note
Don't forget to update YOUR_API_KEY here.

Request:

curl --location --globoff --request GET 'https://api.telnyx.com/v2/available_phone_numbers?filter[country_code]=US&filter[phone_number_type]=local&filter[limit]=1&filter[reservable]=true&filter[exclude_held_numbers]=true' \
--header 'Authorization: Bearer YOUR_API_KEY'

Response:
{
    "data": [
        {
            "quickship": false,
            "features": [
                {
                    "name": "emergency"
                },
                {
                    "name": "fax"
                },
                {
                    "name": "sms"
                },
                {
                    "name": "mms"
                },
                {
                    "name": "hd_voice"
                },
                {
                    "name": "voice"
                }
            ],
            "vanity_format": null,
            "phone_number": "{{e.164.telephone_number_1}}",
            "reservable": true,
            "record_type": "available_phone_number",
            "best_effort": false,
            "region_information": [
                {
                    "region_name": "WI",
                    "region_type": "state"
                },
                {
                    "region_name": "SHEBOYGAN",
                    "region_type": "rate_center"
                },
                {
                    "region_name": "SHEBOYGAN (SHEBOYGAN)",
                    "region_type": "location"
                },
                {
                    "region_name": "US",
                    "region_type": "country_code"
                }
            ],
            "cost_information": {
                "monthly_cost": "1.00000",
                "currency": "USD",
                "upfront_cost": "1.00000"
            },
            "phone_number_type": "local"
        }
    ],
    "meta": {
        "total_results": 1,
        "best_effort_results": 0
    },
    "metadata": {
        "total_results": 1,
        "best_effort_results": 0
    }
}

Create a Reservation

To create a number reservation, send a POST https://api.telnyx.com/v2/number_reservations API request. You can optionally include a customer_reference in the request to help organize your reservations.

A sample request is shown below:

Request:

curl --location --request POST 'https://api.telnyx.com/v2/number_reservations' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer [redacted]' \
--data '{
    "phone_numbers": [
        {
            "phone_number": "{{e.164.telephone_number_1}}"
        }
    ],
    "customer_reference": "test_123"
}'

Response:

{
    "data": {
        "id": "1eb7526a-f009-44b8-861a-f1f6c2ffb9f9",
        "phone_numbers": [
            {
                "id": "8024b57c-2baa-4678-86f0-4c03b23d77d8",
                "phone_number": "{{e.164.telephone_number_1}}",
                "status": "success",
                "created_at": "2024-05-15T18:11:37.387302Z",
                "updated_at": "2024-05-15T18:11:37.387302Z",
                "expired_at": "2024-05-15T18:41:37.387302Z",
                "expired": false,
                "record_type": "reserved_phone_number"
            }
        ],
        "record_type": "number_reservation",
        "customer_reference": "test_123",
        "status": "success",
        "created_at": "2024-05-15T18:11:37.387302Z",
        "updated_at": "2024-05-15T18:11:37.387302Z"
    }
}

A couple of important attributes in the API response to consider:

id: Unique ID associated with the overall number reservation request.
status: Status of the overall reservation request.
phone_numbers[].status: status of the individual phone number reservation.
phone_numbers[].expired_at: Expiration timestamp for the individual phone number reservation. Once this timestamp is exceeded, the phone number will be returned to the available pool for other users to search and order.

Reserve multiple phone numbers

You can reserve multiple phone numbers with a single API request.

When the request is submitted, each phone number will be individually attempted for reservation. Some phone numbers may fail to be reserved (i.e., already purchased or reserved). In such cases, the phone_numbers[].status will be failed, and the overall request status will be partial_success.

A sample request is shown below:

Request:

curl --location --request POST 'https://api.telnyx.com/v2/number_reservations' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer [redacted]' \
--data '{
    "phone_numbers": [
        {
            "phone_number": "{{e.164.telephone_number_1}}"
        },
                {
            "phone_number": "{{e.164.telephone_number_2}}"
        },
                {
            "phone_number": "{{e.164.telephone_number_3}}"
        }
    ],
    "customer_reference": "test_123"
}'

Response:
{
    "data": {
        "id": "94d04678-359c-4e8e-8de4-bf8bfe56b1b9",
        "phone_numbers": [
            {
                "id": "c7927711-f0b8-4d31-91d5-9c126cb68b68",
                "phone_number": "{{e.164.telephone_number_1}}",
                "status": "failed",
                "created_at": "2024-05-15T17:46:16.031329Z",
                "updated_at": "2024-05-15T17:46:16.031329Z",
                "expired_at": "2024-05-15T18:16:16.031329Z",
                "expired": false,
                "record_type": "reserved_phone_number"
            },
            {
                "id": "7f5c1170-0955-403d-bbc8-704ff6de5f5f",
                "phone_number": "{{e.164.telephone_number_2}}",
                "status": "success",
                "created_at": "2024-05-15T17:46:16.031329Z",
                "updated_at": "2024-05-15T17:46:16.031329Z",
                "expired_at": "2024-05-15T18:16:16.031329Z",
                "expired": false,
                "record_type": "reserved_phone_number"
            },
            {
                "id": "7be0fdf9-ff90-42c5-a388-254eee39b05f",
                "phone_number": "{{e.164.telephone_number_3}}",
                "status": "success",
                "created_at": "2024-05-15T17:46:16.031329Z",
                "updated_at": "2024-05-15T17:46:16.031329Z",
                "expired_at": "2024-05-15T18:16:16.031329Z",
                "expired": false,
                "record_type": "reserved_phone_number"
            }
        ],
        "record_type": "number_reservation",
        "customer_reference": "test_123",
        "status": "partial_success",
        "created_at": "2024-05-15T17:46:16.031329Z",
        "updated_at": "2024-05-15T17:46:16.031329Z"
    }
}

List all reservations

To view a list of all your number reservations, send a GET https://api.telnyx.com/v2/number_reservations API request. You can refine your search results using various filtering options. For more details on these filters, refer to the API reference.

A sample request is shown below:

Request:

curl --location --request GET 'https://api.telnyx.com/v2/number_reservations' \
--header 'Authorization: Bearer [redacted]'

Response:

            },
            {
               "id":"342bb7dd-66db-479e-af3b-9b21ae65c897",
               "phone_number":"{{e.164.telephone_number_1}}",
               "status":"success",
               "created_at":"2024-05-14T20:56:18.793926Z",
               "updated_at":"2024-05-14T21:27:31.450879Z",
               "expired_at":"2024-05-14T21:26:18.793926Z",
               "expired":true,
               "record_type":"reserved_phone_number"
            }
         ],
         "record_type":"number_reservation",
         "customer_reference":"",
         "status":"success",
         "created_at":"2024-05-14T20:56:18.793926Z",
         "updated_at":"2024-05-14T20:56:18.793926Z"
      },
      {
         "id":"1eb7526a-f009-44b8-861a-f1f6c2ffb9f9",
         "phone_numbers":[
            {
               "id":"8024b57c-2baa-4678-86f0-4c03b23d77d8",
               "phone_number":"{{e.164.telephone_number_2}}",
               "status":"success",
               "created_at":"2024-05-15T18:11:37.387302Z",
               "updated_at":"2024-05-15T18:11:37.387302Z",
               "expired_at":"2024-05-15T18:41:37.387302Z",
               "expired":false,
               "record_type":"reserved_phone_number"
            }
         ],
         "record_type":"number_reservation",
         "customer_reference":"test_123",
         "status":"success",
         "created_at":"2024-05-15T18:11:37.387302Z",
         "updated_at":"2024-05-15T18:11:37.387302Z"
      }
   ],
   "meta":{
      "count":2,
      "page_size":25,
      "page":1,
      "total_pages":1
   }
}

Retrieve a specific reservation

Sure, here's an improved version of your text:

To retrieve a specific reservation, send a GET https://api.telnyx.com/v2/number_reservations/{{id}} API request.

A sample request is shown below:

Request:

curl --location --request GET 'https://api.telnyx.com/v2/number_reservations/{{id}}' \
--header 'Authorization: Bearer [redacted]'

Response:

{
    "data": {
        "id": "1eb7526a-f009-44b8-861a-f1f6c2ffb9f9",
        "phone_numbers": [
            {
                "id": "8024b57c-2baa-4678-86f0-4c03b23d77d8",
                "phone_number": "{{e.164.telephone_number_1}}",
                "status": "success",
                "created_at": "2024-05-15T18:11:37.387302Z",
                "updated_at": "2024-05-15T18:11:37.387302Z",
                "expired_at": "2024-05-15T18:41:37.387302Z",
                "expired": false,
                "record_type": "reserved_phone_number"
            }
        ],
        "record_type": "number_reservation",
        "customer_reference": "test_123",
        "status": "success",
        "created_at": "2024-05-15T18:11:37.387302Z",
        "updated_at": "2024-05-15T18:11:37.387302Z"
    }
}

Extend a reservation

Number reservations expire 30 minutes after creation, specifically when the phone_numbers[].expired_at timestamp is exceeded.

To extend your reservation by another 30 minutes, send a POST https://api.telnyx.com/v2/number_reservations/{{id}}/actions/extend API request. This request will update the phone_numbers[].expired_at timestamp to reflect the additional 30 minutes.

A sample request is shown below:

Request:
curl --location --request POST 'https://api.telnyx.com/v2/number_reservations/{{id}}/actions/extend' \
--header 'Authorization: Bearer [redacted]'

Response:

{
    "data": {
        "id": "1eb7526a-f009-44b8-861a-f1f6c2ffb9f9",
        "phone_numbers": [
            {
                "id": "8024b57c-2baa-4678-86f0-4c03b23d77d8",
                "phone_number": "{{e.164.telephone_number_1}}",
                "status": "success",
                "created_at": "2024-05-15T18:11:37.387302Z",
                "updated_at": "2024-05-15T18:31:16.212421Z",
                "expired_at": "2024-05-15T19:11:37.387302Z",
                "expired": false,
                "record_type": "reserved_phone_number"
            }
        ],
        "record_type": "number_reservation",
        "customer_reference": "test_123",
        "status": "success",
        "created_at": "2024-05-15T18:11:37.387302Z",
        "updated_at": "2024-05-15T18:31:16.212421Z"
    }
}

Search for reservable phone numbers ​

Request Sample ​

Create a Reservation ​

Reserve multiple phone numbers ​

List all reservations ​

Retrieve a specific reservation ​

Extend a reservation ​

Search for reservable phone numbers

Request Sample

Create a Reservation

Reserve multiple phone numbers

List all reservations

Retrieve a specific reservation

Extend a reservation