---
title: "Update appointment (A034, FHIR STU3)"
method: PUT
path: "/STU3/Appointment/{id}"
tags: ["Change appointment"]
---

# Update appointment (A034, FHIR STU3)

`PUT /STU3/Appointment/{id}`

## Overview
Use this endpoint to cancel an appointment that is booked into a directly-bookable service. Appointments made to directly-bookable services always have a date and time. You can only ever update the current appointment, i.e. an appointment that is related to a service on the current shortlist *and* the most recent appointment made.

Currently, this endpoint only allows cancellation of an appointment as an update. Future developments may permit further updates.

To cancel the referral, use [[HYPERLINK_A036]].

## Supported security patterns
- Healthcare worker, user-restricted access

## Pre-requisites
In order to use this endpoint you must be an authenticated e-RS user and use one of the following e-RS roles:
- `REFERRING_CLINICIAN`
- `REFERRING_CLINICIAN_ADMIN`

You must use [[HYPERLINK_A004]] to retrieve reference data from the set `APPOINTMENT-CANCELLATION-REASON`.

To find out which reference data from this set can be used to cancel an appointment, filter as follows:

  - *usage* must be `CANCEL`,
  - *businessFunction* must be `REFERRING_CLINICIAN` or `REFERRING_CLINICIAN_ADMIN` (depending which authenticated user will be performing the action),
  - *effectiveFrom* must be in the past, and
  - *effectiveTo* must not be in the past

Both the appointment reference, and version, are needed to update an appointment:

You must use [[HYPERLINK_A005]] to obtain the current appointment reference (via *Extension-eRS-Appointment-Reference-1*).

You must use [[HYPERLINK_A038]] to obtain the current appointment and get the current appointment's version. 

## Use case
As an authenticated user

I need to update the current appointment

So that I can manage the patients care appropriately. 

## Related endpoints
You can retrieve the reference data needed to cancel an appointment by using [[HYPERLINK_A004]]. This contains "reasons" for cancellation.

You can check if you currently can cancel the appointment by checking [[HYPERLINK_A029]].

You must use [[HYPERLINK_A005]] to obtain the current appointment reference (via *Extension-eRS-Appointment-Reference-1*) .

You must use [[HYPERLINK_A038]] to obtain the current appointment and get the current appointment's version. 

You can use [[HYPERLINK_A031]] after updating an appointment, to create a new shortlist of services. After changing a shortlist, you may be able to [[HYPERLINK_A016]]. 

## Known Issues

1. The Participant.type attribute is being mapped as a single type for this endpoint. As per the Appointment [FHIR profile](https://hl7.org/fhir/STU3/appointment-definitions.html#Appointment.participant.type), this attribute should be an array. See our [problems and fixes](https://digital.nhs.uk/services/e-referral-service/api/updates-and-releases/problems-and-fixes) section for more information.
2. The participant of an Appointment references a value set. As per the Appointment [FHIR profile](https://hl7.org/fhir/STU3/appointment-definitions.html#Appointment.participant.type), this attribute should be a coding system. See our [problems and fixes](https://digital.nhs.uk/services/e-referral-service/api/updates-and-releases/problems-and-fixes) section for more information.

## Path parameters

- `id` string, required

## Headers

- `If-Match` string, required

## Parameters

- `#/paths/~1STU3~1Task/get/parameters/0` — unresolved $ref
- `#/paths/~1STU3~1Task/get/parameters/1` — unresolved $ref
- `#/paths/~1STU3~1Slot/get/parameters/2` — unresolved $ref
- `#/paths/~1STU3~1Task/get/parameters/4` — unresolved $ref

## Response `200`

An appointment within e-RS.

## Other responses

- `400` — Bad Request
- `401` — unresolved $ref
- `403` — unresolved $ref
- `404` — Not Found
- `406` — unresolved $ref
- `409` — unresolved $ref
- `412` — Precondition Failed - Mandatory data is missing
- `415` — unresolved $ref
- `422` — Where status code 422 (Unprocessable Entity) is returned then an eRS-OperationOutcome-1 will be included in the body, as detailed below. Check diagnostics property for specific information regarding the error. | Error code | Description | | ---------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- | | INVALID_REQUEST_STATE | A note describing that the Request is not in the correct state should be returned to the caller. | | INVALID_VALUE | Reason provided is not a valid Cancellation Reason. | | INAPPROPRIATE_VALUE | Reason provided is not a valid in this case. | | MISSING_VALUE | Part of early validation that checks that the input conforms with the specifications of the FHIR profiles. A field defined as Mandatory on the FHIR profile is not provided. | | UNEXPECTED_FIELD | A field is provided that is not expected as part of the request. E.g. a field is mis-spelt, was defined on a previous version of the endpoint but has subsequently been removed. | | NO_RELATIONSHIP | No legitimate relationship with referral (UBRN). | | PATIENT_ERROR | An error occurred while retrieving the requested patient. Do not attempt again. | | UNABLE_TO_CANCEL_APPOINTMENT | Unable to cancel the appointment. |
- `423` — unresolved $ref
- `429` — unresolved $ref
- `500` — unresolved $ref
- `502` — Where status code 502 (Bad Gateway) is returned then an eRS-OperationOutcome-1 will be included in the body. Check diagnostics property for specific information regarding the error. | Error code | Description | | ---------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- | | PAS_RESPONDED_WITH_ERROR | Error received from PAS. |
- `503` — unresolved $ref
- `504` — Where status code 504 (Gateway Timeout) is returned then an eRS-OperationOutcome-1 will be included in the body. Check diagnostics property for specific information regarding the error. In response to receiving this status code, it is recommended that clients retry at a later time. | Error code | Description | | ---------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- | | PAS_NOT_RESPONDING | No response from PAS. |

---

[API](https://skmtc.dev/nhs/apis/e-referrals-service-api.md) · [All operations](https://skmtc.dev/nhs/apis/e-referrals-service-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/nhs/e-referrals-service-api/revisions/916969ea472f/schema)