---
title: "Creates or updates a reservation by its ID."
method: PATCH
path: "/availablePhoneNumbers/reservations/{reservationId}"
tags: ["Browse, reserve and purchase available phone numbers"]
---

# Creates or updates a reservation by its ID.

`PATCH /availablePhoneNumbers/reservations/{reservationId}`

Adds and removes phone numbers from the reservation with the given ID. The response will be the updated state of the reservation. Phone numbers can be reserved by including them in the payload. If a number is already in the reservation, it will be ignored. To remove a phone number, set it explicitly to null in the request payload. This operation is idempotent. If a reservation with the same ID already exists, it will be updated, otherwise a new one is created. Only reservations with 'active' status can be updated. Updating a reservation will extend the expiration time of the reservation to 15 minutes after the last change, up to a maximum of 2 hours from creation time. Partial success is possible, in which case the response will have a 207 status code.

## Path parameters

- `reservationId` string, uuid, required

## Query parameters

- `api-version` string, required

## Response `200`

Reservation successfully updated.

- PhoneNumbersReservation — Represents a reservation for phone numbers. A reservation is a temporary hold on phone numbers that can later be purchased. The reservation has a limited lifetime after which the phone numbers are released if not purchased. Reservations older than 1 month are automatically deleted.
  - `id` string, uuid — The id of the reservation.
  - `expiresAt` string, date-time — The time at which the reservation will expire. If a reservation is not purchased before this time, all of the reserved phone numbers will be released and made available for others to purchase.
  - `phoneNumbers` object — A dictionary containing the reservation phone numbers. The key is the ID of the phone number (digits only) and values are AvailablePhoneNumber objects. Not populated when retrieving PhoneNumbersReservation collections.
  - `status` 'active' | 'submitted' | 'completed' | 'expired' — Represents the status of the reservation. Possible values include: 'active', 'submitted', 'completed', 'expired'.

## Other responses

- `201` — Reservation successfully created.
- `207` — Reservation operation partially succeeded. This can happen when the operation (create or update) is processed successfully, but it failed for at least one of the phone numbers in the request.
- `default` — Failure

## Changes

- **2021-05-19** (2021-03-07) `5c6abf2b2252` — 1 breaking
  - api path removed without deprecation

[Change history](https://skmtc.dev/azure/apis/communication-phonenumbers/changes/availablePhoneNumbers/reservations/:reservationId/patch.md)

---

[API](https://skmtc.dev/azure/apis/communication-phonenumbers.md) · [All operations](https://skmtc.dev/azure/apis/communication-phonenumbers/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/azure/communication-phonenumbers/revisions/6e81b3741aa7/schema)