Retrieve referral request (A005, FHIR STU3)

Overview

Use this endpoint to retrieve details of a referral. This includes references to clinical attachments, related referrals and other important data.

During the lifecycle of a referral, the state of the referral may change multiple times. To help with understanding the state of a referral, we provide an "at a glance" summary of the referral as detailed below:

Some referral states may also have a reason and some reasons may also have a comment. These are described below:

Reason

• The reason is always connected to the current state. This means the reason is likely to change each time the state changes. You cannot currently retrieve previous versions of a referral.
• This reason may have been selected by a clinician or automatically applied by the e-RS system at the time the state was persisted.
• A reason can be dynamic reference data, from any of the following sets of reference data: APPOINTMENT-CANCELLATION-REASON, REFERRAL-CANCELLATION-REASON, APPOINTMENT-NON-ATTENDANCE-REASON. These are retrievable from [[HYPERLINK_A004]].
• A reason may be static reference data.

Comments

• The comment is always connected to the current reason, and state. This means the comment is likely to change as the state changes.

Supported security patterns

• Application-restricted access
• Healthcare worker, user-restricted access

Pre-requisites

Application-restricted access

In order to use this endpoint you must be an authenticated e-RS calling application, working in the context of a Service Provider Organisation.

Healthcare worker, user-restricted access

In order to use this endpoint you must be an authenticated e-RS user or application 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 request in order to retrieve details of a referral.

Important notes

Attachment availability

In order to retrieve an attachment using the [[HYPERLINK_A042]] (or deprecated [[HYPERLINK_A006]]) endpoint, the attachment must be available for download. Attachments are only made available once an uploaded file has been validated and successfully malware scanned. A request to retrieve an attachment that is not available for download will result in an error being returned. See [[HYPERLINK_A042]] for more information.

The availability status of an attachment can be retrieved via any endpoint that returns an eRS-AvailabilityStatus-1 code in the success response, including [[HYPERLINK_A005]]. The eRS-AvailabilityStatus-1 code can return one of four possible values, as detailed below.

Receiving an e-Referral Pathway Start Date

The e-Referral Pathway Start Date is a derived value of when the Referral To Treatment (RTT) clock starts. Find out how e-RS derives the pathway start date [[HYPERLINK_PATHWAY_START]].

If a referral was created with an alternate pathway start date, then this will be available in the referral request response.

Service providers must always ensure the correct start date is recorded in line with [[HYPERLINK_RTT_RULES]].

Use case

As an authenticated user or application

I want to read details of a referral

So that I can decide what further action may be needed.

Related endpoints

You can retrieve attachments that are associated with the referral using [[HYPERLINK_A042]] (or deprecated [[HYPERLINK_A006]]. Attachments can only be retrieved where the eRS-AvailabilityStatus-1 code returned is 'AVAILABLE'

You can retrieve a clinical information summary for the referral using [[HYPERLINK_A007]]

You can search for services appropriate to a referral to form a shortlist using [[HYPERLINK_A010]]

If bookable services are on the shortlist of the referral, you can retrieve appointment slots for a service on the shortlist for a referral using [[HYPERLINK_A015]]

You can retrieve the patient letter appropriate to the referral using [[HYPERLINK_A019]]

You can retrieve reference data used in viewing a referral using [[HYPERLINK_A004]]

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