# DID Reservations

Use the DID Reservations resource to create, retrieve, and cancel reservations for
[Available DID phone numbers](../available-did/index.html).

A DID Reservation temporarily holds an Available DID before ordering. This allows a
selected phone number to be reserved while the customer continues the DID ordering flow.

DID Reservations are commonly used after selecting a specific Available DID and before
creating an order. By default, a DID Reservation reserves up to 10 DID numbers for 10
minutes.

## Endpoints

| Action | Method | Endpoint |
| --- | --- | --- |
| Retrieve all DID Reservations | `GET` | `/v3/did_reservations` |
| Retrieve DID Reservation | `GET` | `/v3/did_reservations/{id}` |
| Create DID Reservation | `POST` | `/v3/did_reservations` |
| Delete DID Reservation | `DELETE` | `/v3/did_reservations/{id}` |

## Retrieve all DID Reservations

Retrieves all DID Reservations for the account.

Use this endpoint to list active DID Reservations and check reserved Available DIDs before
continuing the ordering flow.

The response can include related Available DID data, DID Group data, and Stock Keeping
Unit data.

See [Retrieve All DID Reservations](get-did-reservations.html).

```
GET /v3/did_reservations
```

## Retrieve DID Reservation

Retrieves a specific DID Reservation by its unique ID.

Use this endpoint when you already know the DID Reservation ID and need to retrieve its
expiration time, creation time, description, and related Available DID before creating an
order.

The response can include the reserved Available DID, the related DID Group, and related
Stock Keeping Units.

See [Retrieve DID Reservation](get-did-reservation.html).

```
GET /v3/did_reservations/{id}
```

## Create DID Reservation

Creates a DID Reservation for a selected Available DID.

Use this endpoint after selecting an Available DID and before creating an order. The
request links the DID Reservation to an Available DID resource.

If the Available DID is not already reserved, the API creates a new DID Reservation. If
the Available DID is already reserved and an active reservation exists, the API may update
the current reservation.

See [Create DID Reservation](create-did-reservation.html).

```
POST /v3/did_reservations
```

## Delete DID Reservation

Deletes a DID Reservation by its unique ID.

Use this endpoint to cancel a reservation when the selected Available DID should no longer
be held before ordering.

See [Delete DID Reservation](delete-did-reservation.html).

```
DELETE /v3/did_reservations/{id}
```

## Common DID Reservation use cases

| Use case | Description |
| --- | --- |
| Reserve a selected DID number | Create a DID Reservation after selecting a specific Available DID phone number. |
| Hold a number before ordering | Temporarily hold an Available DID while preparing the order. |
| Check reservation expiration | Retrieve the reservation to check when the reserved number expires. |
| Continue the ordering flow | Use the reserved Available DID and related DID Group or Stock Keeping Unit data before creating an order. |
| Cancel a reservation | Delete a DID Reservation when the selected number should no longer be held. |
| Retrieve reserved number details | Include the related Available DID, DID Group, and Stock Keeping Units to review the selected number before ordering. |

## Related resources

Use DID Reservations together with Available DIDs and ordering resources to complete the
selected-number ordering flow.

| Resource | Description |
| --- | --- |
| [Available DIDs](../available-did/index.html) | Specific DID phone numbers available for selection and reservation. |
| [DID Groups](../did-group/index.html) | DID inventory groups used to find coverage, features, pricing options, and number selection support. |
| [Orders](../../inventory-resources/order/index.html) | Orders created after selecting or reserving an Available DID number. |
| [Countries](../countries/index.html) | Countries used to filter DID inventory and coverage. |
| [Regions](../regions/index.html) | Regions used to filter DID inventory where region-level coverage applies. |
| [Cities](../city/index.html) | Cities used to filter DID inventory where city-level coverage applies. |
| [NANPA Prefixes](../nanpa/index.html) | NANPA prefixes used for North American DID inventory. |
| [Common Definitions](../../common-definitions/index.html) | Shared embedded objects such as the Stock Keeping Unit Object. |

On this page