> ## Documentation Index
> Fetch the complete documentation index at: https://developers.telnyx.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Number Reservations tutorial

> Reserve phone numbers temporarily before purchasing on Telnyx. Step-by-step tutorial showing how to use the Number Reservations API.

# Quickstart - Number Reservations

\| [cURL](#curl) | [Python](#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](/docs/development) 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.

<Callout type="info">
  *Don't forget to update `YOUR_API_KEY` here.*
</Callout>

```bash theme={null}
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
```

<Callout type="info">
  *The above is a test number. You will have to replace the number field with a number from one of your search results.*
</Callout>

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

### Retrieve All Reservations

```bash theme={null}
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

```json theme={null}
{
  "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

```bash theme={null}
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

```json theme={null}
{
  "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](/docs/development/sdk/python) 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.

```python theme={null}
import telnyx
telnyx.api_key = "YOUR_API_KEY"

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

<Callout type="info">
  *The above is a test number. You will have to replace the number field with a number from one of your search results.*
</Callout>

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

### Retrieve All Reservations

```python theme={null}
import telnyx
telnyx.api_key = "YOUR_API_KEY"

telnyx.NumberReservation.list()
```

#### Sample Response

```json theme={null}
{
  "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

```python theme={null}
import telnyx
telnyx.api_key = "YOUR_API_KEY"

telnyx.NumberReservation.retrieve("uuid")
```

#### Sample Response

```json theme={null}
{
  "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",
}
```