Retrieve advice and guidance conversation (A025, FHIR STU3)

Overview

Use this endpoint to retrieve the advice and guidance conversation between the referring organisation and service providing organisation.

A conversation takes the form of messages between a referrer (seeking advice) and a provider or specialist. Messages can include file attachments. These must be retrieved via [[HYPERLINK_A042]]

Read our building healthcare software guide for detailed information.

Supported security patterns

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

Pre-requisites

You need to use the Unique Booking Reference Number (UBRN) of the advice and guidance request. For service provider users, you may have identified the UBRN via [[HYPERLINK_A023]].

You need to use [[HYPERLINK_A024]] to retrieve the summary of an advice and guidance request. This will importantly include the latest version of the request which must be used.

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 and use one of the following e-RS roles:

• REFERRING_CLINICIAN
• REFERRING_CLINICIAN_ADMIN
• SERVICE_PROVIDER_CLINICIAN
• SERVICE_PROVIDER_CLINICIAN_ADMIN

Use case

As an authenticated user or application

I need to retrieve the conversation that is present on an advice and guidance request

So that I can review the conversation and potentially contribute further to it.

Important notes

The conversation returned includes links to any attachments associated with the conversation. This can be done via endpoint [[HYPERLINK_A006]]. Note, dependent on how attachments were added they may be linked to the Advice and Guidance summary instead of the conversation. These may be retrieved from [[HYPERLINK_A024]].

If the converted advice and guidance request is referred to a service outside of your organisation, the subsequent referral information may not be accessible due to existing data-access rules. However, the advice and guidance summary ([[HYPERLINK_A024]]), attachments ([[HYPERLINK_A006]]), advice and guidance conversation ([[HYPERLINK_A025]]) and clinical information ([[HYPERLINK_A043]]) which took place before such a conversion still forms part of the clinical information and can still be retrieved. The conversation also gets included in the form of a PDF file returned by [[HYPERLINK_A007]].

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_A025]]. The eRS-AvailabilityStatus-1 code can return one of four possible values, as detailed below.

Related endpoints

After using this endpoint:

• Use [[HYPERLINK_A006]] to retrieve any attachments associated with the advice and guidance request.
• (For service provider users) Use [[HYPERLINK_A026]] to respond to the referrer supplying advice or requesting further information.
• (For service provider users) Use [[HYPERLINK_A027]] to convert the advice and guidance request into a referral. This is only possible if the referrer has authorised the provider to do so.

Use [[HYPERLINK_A043]] to generate a PDF file overview relating to an advice and guidance request.

Sandbox test scenarios

You can test the following scenarios in our sandbox environment