Create advice and guidance requests as a referrer

This page describes functionality available via the NHS e-Referral Service (e-RS) API to create an advice and guidance (A&G) request.

A&G allows a referrer to enter into dialogue with a provider (consultant) around a patient’s care. Read more in the A&G toolkit.

This use case guide covers:

1. Create advice request.

2. Manage advice request.

The process diagram shows how the various endpoints can be used to create an integrated solution. Endpoints in red denote those which can be accessed via the application-restricted, unattended access route. Tasks in green denote user actions in the e-RS professional web application.

This process flow covers the creation of an A&G request with a shortlist.

An A&G shortlist can only contain a single service which must support A&G requests.

Find out about the different channels available in e-RS via which a patient may be referred.

1.1 Carry out a patient service search

Endpoint: Patient service search (A010)

The first step in making an A&G request is for the referrer to identify an appropriate secondary care provider. This is done by querying the e-RS directory of services (DOS).

Referrers can use the most suitable search mechanism to locate services, such as:

• SNOMED clinical term
• speciality and clinic type
• named clinician

Find out more about what the DOS holds and how it enables referring clinicians to search for appropriate services.

Service search has to be carried out in context of a patient. Integrated software must have identified a patient prior to creating an A&G request. This is to ensure a PDS trace has taken place which verifies the patient and their demographic details, which could be used in later stages of the referral workflow. For example, the correct address has been used if a patient letter is subsequently sent out in the post.

1.2 Obtain reference data

Endpoint: Retrieve reference data (A004)

If users are required to perform a service search using specialty and clinic terms, the reference data endpoint will be required to obtain the latest set of codes.

NHS e-Referral video - specialty and clinic types

Click the play button to watch a short video which explains the terms used within e-RS and demonstrates how specialty and clinic types are used to locate a suitable service for A&G requests.

This short video lasts around 5 minutes.

1.3 Upload file

Endpoints: Upload file to document store (A020)

This endpoint allows for the upload of attachments. Attachments part of an A&G request are optional.

Files must be uploaded to the e-RS document store first, if they are to be associated as part of the A&G request.

Files uploaded to e-RS will be assigned a binary file ID in the form of a UUID.

Note: Our endpoints do not currently allow structured data to be uploaded. Structured clinical information should be collated into an attachment and added to the request.

1.4 Create advice request

Endpoint: Create advice and guidance request (A044)

This endpoint will create the advice and guidance request (start the A&G conversation) and send it to an A&G service for a response.

The referrer can also preauthorise the provider to convert the A&G request to a referral, if appropriate. This allows A&G to be used as a referral channel, to reduce the burden on referrers and streamline patient care.

This process covers the management of an existing A&G request. This must be carried out in the professional web application.

It uses existing functionality called seamless transition or seamless login.

2.1 Seamless transition parameters

The seamless transition functionality enables a user to access e-RS in the context of a UBRN.

The URL takes the following format:

https://<e-RS URL>?UBRN=<UBRN>&roleProfileCode=<Role Profile Code>

It uses two URL parameters:

1. Unique Booking Reference Number (UBRN).
2. Role profile code.

UBRN

This is the reference number received from a previous interaction with the e-RS. In this case, the UBRN refers to an A&G request.

Role profile code

This is the role profile for the users current referring system session.

The business function in the role profile must be Referring Clinician or Referring Clinician Admin.

Example

This is an example of a seamless transition URL in production:

https://ers.nhs.uk/app-ebs/login.do?UBRN=000000099565&roleProfileCode=098765432123

where the UBRN is 000000099565 and the role profile code is 098765432123

2.2 Seamless transition

Upon navigating to the URL, the user will be redirected to CIS2 for authentication. If the user is already authenticated, they may not have to complete this step. Authentication behaviour varies, see CIS2 session management for detailed guidance.

Once authenticated by CIS2, the browser will be redirected back to the e-RS.

The user will then be navigated to an e-RS landing page depending on the UBRNs state. For A&G requests this will usually be the advice request details page.