Mixed shortlist

As part of the NHS Choice Framework, the e-Referral Service (e-RS) will be making changes to give patients greater choice and control over how they receive their healthcare. In order to fulfil this agenda, changes will be made to both the professional web application and the e-RS API.

In the professional web application, professional users will be able to create a shortlist made up of bookable and/or triage services, termed a 'mixed' shortlist. Currently, only bookable services can be shortlisted.

The same mixed shortlist functionality will also be supported in the e-RS API.

At this stage, we don't expect there to be any breaking changes in the structure of the existing API. However, there will be a change in terms of the data returned from our API.

The proposed changes may impact your API solution if:

1. It is being used in a GP setting.
2. It is possible to progress unbooked referrals via A016 - Book or defer appointment, A031 - Change shortlist or A032 - Change shortlist and send for triage.
3. Your professional users need to manage referrals that were not initiated via your API solution.

The proposed changes may impact API solutions that are using these endpoints:

The impact to each endpoint grouping is described below.

What we are doing and why

Currently, two shortlist endpoints only support the shortlisting of bookable services. These are:

• A011 - Create referral
• A031 - Change shortlist 

We will be extending the APIs to support creating a shortlist including both bookable and triage services.

What this means for your solution

Existing API implementations will not expect a triage service on the shortlist and therefore won't be able to progress a triage referral. 

To progress with a shortlisted triage service, partners will have to integrate with the new functionality added to A016 - Book or defer appointment.

What we are doing and why

The book/defer endpoint A016 - Book or defer appointment currently only supports booking or deferring to a directly bookable service.

We will be extending the API to support deferring to a triage service.

What this means for your solution

To progress with a shortlisted triage service, partners will need to integrate with the new functionality added to A016 - Book or defer appointment, which will be released with the mixed shortlist functionality.

If your professional users need to manage shortlists that were not initiated via your API solution, we are recommending that you integrate with A033 - Retrieve healthcare service and A035 - Search for healthcare services as soon as possible. This will provide the ability to detect a triage service on a shortlist and present an appropriate message to the user. See the section, Healthcare service endpoints, for more details.

Integrating now will reduce the risk of being unable to progress a referral which could occur once mixed shortlists are supported by the wider e-RS.

What we are doing and why

Two triage endpoints were created to specifically support triage workflows, since they could not exist on a shortlist with bookable services. These are:

• A021 - Create referral and send for triage
• A032 - Change shortlist and send for triage 

With the introduction of mixed shortlists, these APIs should no longer be required and will be deprecated at a future date.

What this means for your solution

Partners will need to support the shortlisting of bookable and/or triage services using A011 - Create referral and A031 - Change shortlist.

The act of shortlisting alone will not result in a referral being sent or booked to any of the shortlisted services. Partners will need to use A016 - Book or defer appointment if there is a need to support this, e.g. sending the referral to a shortlisted triage service.

What we are doing and why

Endpoints already exist to retrieve information about a service:

• A033 - Retrieve healthcare service
• A035 - Search for healthcare services 

Attributes within these endpoints are particularly relevant to the mixed shortlist functionality.

Request flow type - indicates which flows are supported by the service:

• BOOKABLE - for directly-bookable services
• REVIEW - for triage referrals
• ADVICE_AND_GUIDANCE - for advice and guidance requests

Bookable type – indicates what type of booking is supported, for a BOOKABLE service:

• DIRECTLY_BOOKABLE
• INDIRECTLY_BOOKABLE

The bookable type attribute will be available in production on July 21st and will be available in the integration environment a week prior to this.

When progressing a shortlisted referral via A016 - Book or defer appointment these endpoints can be used to retrieve the request flow type and bookable type of the shortlisted services. This will allow your system to present the appropriate options to your users.

What this means for your solution

In preparation for the mixed shortlist release, partners should integrate with these endpoints.

This will allow your system to detect a triage service on the shortlist and display an appropriate message to the user, preventing them from any attempt to book or defer.

When you are ready to integrate with the new mixed shortlist functionality, your system can be updated to integrate with the triage deferral functionality in A016 - Book or defer appointment. See the section 'Book/defer endpoint' for more details.

What we are doing and why

The endpoint 'A029 - Available actions for user list' allows partners to determine which action can be performed on a given referral.

The action 'FHIR Reference Server eRS Available Actions For User' is currently supported.

We will be updating this API to provide support for mixed shortlists.

What this means for your solution

The CREATE_APPOINTMENT and CHANGE_SHORTLIST actions will be updated to reflect a mixed shortlist.

The CHANGE_SHORTLIST_AND_SEND_FOR_TRIAGE action will be removed following the deprecation of A032 - Change shortlist and send for triage.

In readiness for delivery of these changes, partners should:

If you need further information, please contact us at [email protected].