Retrieve appointment (A038, FHIR STU3)

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, this attribute should be an array. See our problems and fixes section for more information.
2. The participant of an Appointment references a value set. As per the Appointment FHIR profile, this attribute should be a coding system. See our problems and fixes section for more information.

Sandbox test scenarios

You can test the following scenarios in our sandbox environment