Skip to main content

Quickstart - Number Reservations

| cURL | Python |


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.

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

Note: 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

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.

import telnyx
telnyx.api_key = "YOUR_API_KEY"

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

Note: 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",
}

On this page