Convert advice and guidance request to referral (A027, FHIR STU3)

Overview

Use this endpoint, as a service provider, to:

• convert the advice and guidance request you have received into a referral, AND
• create a task for the service provider admin team to select/shortlist appropriate services for the patient, AND
• provide final guidance response details back to the referrer

Note: This endpoint is only allowed to be used if the referrer has authorised the provider to convert the advice and guidance request into a referral.

Whilst a document can be uploaded via [[HYPERLINK_A020]] without a NHSD-eRS-Referral-ID, only documents that have a NHSD-eRS-Referral-ID can be associated using this end point. An attempt to associate a document without a NHSD-eRS-Referral-ID will return an error response of 422 - INAPPROPRIATE_VALUE.

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:

• SERVICE_PROVIDER_CLINICIAN
• SERVICE_PROVIDER_CLINICIAN_ADMIN

You need to use [[HYPERLINK_A024]] to retrieve the summary of an advice and guidance request. This will include whether or not the referrer has authorised the provider to be able to convert an advice and guidance request into a referral, and thus dictate whether this endpoint can be used.

You need to use [[HYPERLINK_A025]] to retrieve the conversation within an advice and guidance request.

If you want to include attachments with the admin task and/or the response to the referrer, you need to use [[HYPERLINK_A020]] so they are ready to be associated when this endpoint is called.

Use case

As an authenticated user

I need to convert an inbound advice and guidance request into a referral and task my admin team to shortlist appropriate services for the patient

So that I can progress the patient's care along the most appropriate referral pathway.

Important notes

When this endpoint is successfully used, an entry will be added to the service providers Appointments For Booking worklist for the admin team to action the task. The provider admin team will currently only be able to progress the referral via the e-RS Professional Application user interface (e.g. shortlisting appropriate services for the patient).

In order to retrieve an attachment using the [[HYPERLINK_A042]] (or deprecated [[HYPERLINK_A006]]) endpoint, the attachment must be available for download. The availability status of attachments associated with a referral are returned via this endpoint as a eRS-AvailabilityStatus-1 code.

Further details on attachment availability status and eRS-AvailabilityStatus-1 codes can be found in the [[HYPERLINK_A005]] and [[HYPERLINK_A042]] specifications.

Related endpoints

You can use [[HYPERLINK_A005]] to retrieve the details of the referral.

You can use [[HYPERLINK_A024]] to retrieve the latest summary of the advice and guidance request.

You can use [[HYPERLINK_A025]] to retrieve the latest conversation within the advice and guidance request.

You can use [[HYPERLINK_A006]] to retrieve the clinical attachments for a referral/advice request.

You can use [[HYPERLINK_A007]] to retrieve the clinical information summary PDF for a referral.

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.