--- title: "Retrieve appointment (A038, FHIR STU3)" method: GET path: "/STU3/Appointment/{id}" tags: ["Change appointment"] --- # Retrieve appointment (A038, FHIR STU3) `GET /STU3/Appointment/{id}` ## Overview Use this endpoint to retrieve the current version of an appointment. An appointment is made to a service so a patient can be seen or for the referral to be reviewed, prior to care. A referral may, or may not, have an appointment and an appointment will always relate to a specific referral. It is possible to have more than one appointment during the life of the referral, but never concurrent appointments. This endpoint only returns the current appointment and does not support historic views. The outcome of a referral review can be recorded on an appointment. Cancellation or maintenance of an appointment (such as the intent to cancel the current appointment and book another one later) are recorded against the current appointment. e-RS currently supports a number of appointment scenarios: - Where a booking has been made to a directly-bookable service (DBS) - Where a deferred booking is made when a slot could not be found at a directly-bookable service. In this case, the service "books" the appointment - Where a booking has been made to a indirectly-bookable service (IBS) - Where a review is required by a triage service - Where a review has been conducted by a triage service - Where a service has rejected, or accepted an appointment - Where an appointment has been cancelled, and no further action is possible - Where an appointment is currently cancelled, but a future appointment may be made by a service later ## 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` - `SERVICE_PROVIDER_CLINICIAN` - `SERVICE_PROVIDER_CLINICIAN_ADMIN` You need to use the `Unique Booking Reference Number` (UBRN) of a referral in order to retrieve details of an appointment that it relates to. Note: e-RS only supports the retrieval of the most recent version of Appointment. You cannot retrieve earlier versions. ## Use case As an authenticated user I want to read details of an appointment So that I can decide what further action may be needed. ## Related endpoints Note that in some cases below, an appointment forms part of the referral returned. You can always retrieve the current version of an existing appointment via [[HYPERLINK_A005]]. When successfully accepting an appointment, the accepted appointment is returned via [[HYPERLINK_A013]]. When successfully rejecting an appointment, the rejected appointment is returned via [[HYPERLINK_A014]]. When booking an appointment to a directly bookable service, deferring the booking responsibility to a directly bookable service, or referring a patient into a triage service, an "appointment" is returned via [[HYPERLINK_A016]]. When successfully cancelling an appointment, to action it later, the cancelled appointment is returned via [[HYPERLINK_A022]]. When converting an advice and guidance to a referral, if the referral has an appointment, it will be returned via [[HYPERLINK_A027]]. Having successfully reviewed a referral, details of that review are shown on the appointment returned via [[HYPERLINK_A028]]. You will need the appointment version when using [[HYPERLINK_A034]], which can be obtained from [[HYPERLINK_A038]]. If an appointment is cancelled as part of [[HYPERLINK_A036]], an appointment will be returned as part of a successful response. ## 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. ## Sandbox test scenarios You can test the following scenarios in our sandbox environment | Scenario | Request | | --------------------------------------------------------------------------------------------------------- | ----------------------- | | `Appointment` booked to directly-bookable service | `appointmentId`=`70000` | | `Appointment` booked to indirectly-bookable service | `appointmentId`=`70001` | | `Appointment` deferred to service provider for booking | `appointmentId`=`70002` | | `Appointment` sent for triage | `appointmentId`=`70003` | | `Appointment` triage response (Record Triage Outcome) | `appointmentId`=`70004` | | `Appointment` Cancel Appointment, Action Later | `appointmentId`=`70005` | | `Appointment` cancelled | `appointmentId`=`70006` | | `Appointment` converted from an Advice and Guidance Request and booked to a directly-bookable service | `appointmentId`=`70007` | ## Parameters - `#/paths/~1STU3~1Task/get/parameters/0` — unresolved $ref - `#/paths/~1STU3~1Task/get/parameters/1` — unresolved $ref - `#/paths/~1STU3~1Task/get/parameters/2` — unresolved $ref - `#/paths/~1STU3~1Task/get/parameters/3` — unresolved $ref - `#/paths/~1STU3~1Task/get/parameters/4` — unresolved $ref - `#/paths/~1STU3~1Appointment~1%7Bid%7D/put/parameters/4` — unresolved $ref ## Response `200` e-RS Referral Request ## Other responses - `400` — unresolved $ref - `401` — unresolved $ref - `403` — unresolved $ref - `404` — unresolved $ref - `406` — 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 | | ---------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- | | PATIENT_ERROR | An error occurred while retrieving the requested patient. Do not attempt again. | | NO_RELATIONSHIP | The user does not have a legitimate relationship with the request. | - `429` — unresolved $ref - `500` — unresolved $ref - `503` — unresolved $ref --- [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)