DID Reservations

Use the DID Reservations resource to create, retrieve, and cancel reservations for Available DID phone numbers.

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 /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 /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.

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 /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	Specific DID phone numbers available for selection and reservation.
DID Groups	DID inventory groups used to find coverage, features, pricing options, and number selection support.
Orders	Orders created after selecting or reserving an Available DID number.
Countries	Countries used to filter DID inventory and coverage.
Regions	Regions used to filter DID inventory where region-level coverage applies.
Cities	Cities used to filter DID inventory where city-level coverage applies.
NANPA Prefixes	NANPA prefixes used for North American DID inventory.
Common Definitions	Shared embedded objects such as the Stock Keeping Unit Object.