---
title: "Change shortlist (A031, FHIR STU3)"
method: POST
path: "/STU3/ReferralRequest/{ubrn}/$ers.changeShortlist"
tags: ["Manage referral"]
---

# Change shortlist (A031, FHIR STU3)

`POST /STU3/ReferralRequest/{ubrn}/$ers.changeShortlist`

## Request

- Base URL: `https://sandbox.api.service.nhs.uk/referrals/FHIR`
- URL: `https://sandbox.api.service.nhs.uk/referrals/FHIR/STU3/ReferralRequest/{ubrn}/$ers.changeShortlist`
- Auth: HTTP bearer

## Overview
Use this endpoint to change the shortlist of bookable and/or triage services on an existing referral.

## Supported security patterns
- Healthcare worker, user-restricted access

## Important notes

The maximum amount of services allowed on a given shortlist is 20.

The act of changing a shortlist alone will not result in a referral being sent/booked to any of the shortlisted services (even if only one service is shortlisted). 
A shortlist of a single triage service should be avoided as this relies on the patient to progress the referral, potentially leading to a delay to care. Especially if the referral priority is 2WW or Urgent.

Use [[HYPERLINK_A016]] if there is a need to support the sending/booking of the referral into a shortlisted service.

A patient can request assistance at a service (e.g. a translator, transport or advocacy) when a shortlist is created within the e-RS web application, meaning that all services shortlisted would support the patient's additional requirements to attend.

The e-RS APIs do not currently support patients' additional requirements so you can neither specify services that support patients' additional requirements, arrange additional requirements for a patient, or view comments associated with the request for additional requirements.

You must consider if you are fully meeting the patient's additional requirement needs if there are additional requirements associated with the referral.

If you do not know whether the patient has an existing additional requirement need and the referral may have been shortlisted within the e-RS web application, be mindful that if you chose to amend the shortlist via changing the services, you could remove this patient need.

If you are changing services to send the patient to a triage service, the triaging service will not support additional requirements but will need to consider if the patient has any additional requirements as part of their decision for future care.

You can view additional requirements on a referral via the e-RS web application or by fetching [[HYPERLINK_A005]].

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.

## 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:
- `REFERRING_CLINICIAN`
- `REFERRING_CLINICIAN_ADMIN`

You need to use the `Unique Booking Reference Number` (UBRN) of a referral request in order to use this endpoint.

You need to have found services that meet the referral needs of a patient using [[HYPERLINK_A010]].

## Use case
As an authenticated user

I need to change the shortlist of bookable services and/or triage services on an existing referral

So that I can adequately manage my patients referral pathway, allowing the patient to book into an appropriate service.

## Related endpoints
To allow the patient to book their appointment in their own time, you can generate a letter for the patient by using [[HYPERLINK_A019]]. The letter summarises the current state of the referral and any steps the patient may need to follow (e.g. appointment booking instructions).

You can book an appointment for the patient into a shortlisted directly bookable service using [[HYPERLINK_A015]] and [[HYPERLINK_A016]].

You can send the referral into a shortlisted triage service using [[HYPERLINK_A016]].

For the referral to be processed by the service provider, you must ensure appropriate referral letter information has been added to the referral. You can add/manage referrer letter information by using [[HYPERLINK_A012]].

You can check to see what referral letter information has already been added to a referral by using [[HYPERLINK_A005]], [[HYPERLINK_A007]], and [[HYPERLINK_A006]] endpoints where necessary.

## Known Issues

1. The Participant.type attribute is being mapped as a single type for this endpoint. As per the Appointment [FHIR profile](https://hl7.org/fhir/STU3/appointment-definitions.html#Appointment.participant.type), this attribute should be an array. See our [problems and fixes](https://digital.nhs.uk/services/e-referral-service/api/updates-and-releases/problems-and-fixes) section for more information.
2. The participant of an Appointment references a value set. As per the Appointment [FHIR profile](https://hl7.org/fhir/STU3/appointment-definitions.html#Appointment.participant.type), this attribute should be a coding system. See our [problems and fixes](https://digital.nhs.uk/services/e-referral-service/api/updates-and-releases/problems-and-fixes) section for more information.

## Parameters

- `#/paths/~1STU3~1Task/get/parameters/0` (unresolved $ref)
- `#/paths/~1STU3~1Task/get/parameters/1` (unresolved $ref)
- `#/paths/~1STU3~1Slot/get/parameters/2` (unresolved $ref)
- `#/paths/~1STU3~1Task/get/parameters/4` (unresolved $ref)
- `#/paths/~1STU3~1Appointment~1%7Bid%7D/put/parameters/5` (unresolved $ref)
- `#/paths/~1STU3~1ReferralRequest~1%7Bubrn%7D/get/parameters/0` (unresolved $ref)

## Request body

- object: Parameters provided when looking to change the services a referral has currently shortlisted
  - `resourceType` 'Parameters', required
  - `meta` object, required
    - `profile` string[], required
  - `parameter` union[], required: | Field | Cardinality | Notes | | --------------------------------- | ----------- | ---------------------------------------------------------------------------------------- | | `Shortlist` | `1..1` | Shortlist indicating the new services a referral should have shortlisted | | `IntentionToAddReferralLetter` | `1..1` | Flag indicating whether a referral letter is going to be added later or is already added | | `FirstReminderLetterFollowUpDays` | `1..1` | Time at which a reminder should be sent to remind the patient about the referral |
    - union
      - 2 (unresolved $ref)
      - 3 (unresolved $ref)
      - 4 (unresolved $ref)

## Response `200`

Referral updated with new service list

- Schema (unresolved $ref)

## Other responses

- `400` (unresolved $ref)
- `401` (unresolved $ref)
- `403` (unresolved $ref)
- `404` (unresolved $ref)
- `406` (unresolved $ref)
- `409` (unresolved $ref)
- `415` (unresolved $ref)
- `422`: Where status code 422 (Unprocessable Entity) is returned then an eRS-OperationOutcome-1 will be included in the body, as detailed below. Check diagnostic property for specific information regarding the error. | Error code | Description | | ---------------------------------- | ----------------------------------------------------------------------------------------------------------------------- | | INAPPROPRIATE_VALUE | A value, which is acceptable under different conditions, is inappropriate in the context of the other information provided. | | TOO_MANY_ITEMS | In a list where a maximum number of items is specified (e.g. a Shortlist), too many entries are supplied. | | MISSING_VALUE | A field defined as mandatory for an endpoint has not been provided. | | PATIENT_ERROR | An error occurred while retrieving the requested patient. Do not attempt again. | | INVALID_VALUE | The input provided does not conform to the expected data types and format. | | INVALID_CODE | The input provided for a field is not one of the defined legal values. | | UNEXPECTED_FIELD | A field is provided that is not expected as part of the request. E.g. a field is mis-spelt, was defined on a previous version of the endpoint but has subsequently been removed. | | INVALID_FHIR_STRUCTURE | The FHIR data structure in the message body does not match the expected structure (e.g. an array is present for a value when no array is expected). | | ORGANISATION_IS_CLOSED | The organisation supplied corresponds to an organisation that is closed. | | ORGANISATION_NOT_APPROPRIATE | The organisation supplied corresponds to an organisation that is not valid for the given request. | | DUPLICATE_SERVICE | Unique service value expected. | | SHORTLISTED_SERVICE_NOT_IN_RESULTS | The service selected for the shortlist submitted does not satisfy the search criteria provided. | | SNOMED_NOT_FOUND | A SNOMED code, while potentially valid in the latest version of the international dictionary, is not found in the e-RS dictionary. | | NO_RELATIONSHIP | The user does not have a legitimate relationship with the request. | | INVALID_REQUEST_TYPE | The `UBRN` provided exists in e-RS but does not correspond to an active request. | | INVALID_REQUEST_STATE | The Request, while otherwise valid, is not in the correct state for the specific action being performed. |
- `423` (unresolved $ref)
- `429` (unresolved $ref)
- `500` (unresolved $ref)
- `503` (unresolved $ref)

---

[API](https://skmtc.dev/nhs/apis/e-referrals-service-api.md) - [All operations](https://skmtc.dev/nhs/apis/e-referrals-service-api/llms.txt) - [OpenAPI document](https://skmtc.dev/nhs/apis/e-referrals-service-api/revisions/916969ea472f?raw)
