---
title: "Maintain referral letter (A012, FHIR STU3)"
method: POST
path: "/STU3/ReferralRequest/{ubrn}/$ers.maintainReferralLetter"
tags: ["Refer patient", "Arrange appointment", "Arrange triage"]
---

# Maintain referral letter (A012, FHIR STU3)

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

## Request

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

## Overview
Use this endpoint to manage the set of 'referral letter' attachments associated with an existing referral, including adding or removing attachments from 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:
  - `REFERRING_CLINICIAN`
  - `REFERRING_CLINICIAN_ADMIN`

All new files to be associated with a referral must be uploaded first using [[HYPERLINK_A020]] and then linked to the referral using this endpoint.

## Important notes

This endpoint can be used to associate attachments to a referral that has no existing referral letter attachments. 
In this case you must upload the file first using [[HYPERLINK_A020]] and then associate it to the referral using this endpoint.

You can also use this endpoint to modify the *set* of referral letter attachments already associated with a referral. 
In this case, you must post all referral letter attachments you wish to be (finally) associated to the referral, 
including any that were already associated. In other words, this endpoint replaces the set of referral letter 
attachments previously associated - with those specified in your latest request. 
As such, it is imperative that this call references all the attachments the user wishes to keep, every time it is called.

Below are three example scenarios which clarify the behaviour of the endpoint when referral attachments are already present on the referral:

1. Let us consider a referral that has two referral letter attachments associated (say "A.pdf" and "B.pdf"). If 
you wish to add an additional attachment (say "C.pdf"), you must upload the additional attachment 
"C.pdf" using [[HYPERLINK_A020]], and then associate attachments "A.pdf", "B.pdf" and "C.pdf" 
via this endpoint in a single request. That is, all three attachments "A.pdf", "B.pdf" and "C.pdf" 
must be included in the request to [[HYPERLINK_A012]].
2. Let us consider a different referral that has two referral letter attachments (say "D.jpg" and "E.jpg") 
already associated, and you wish to remove one of them. Let us consider that you wish to remove "D.jpg". 
To do this, you would call [[HYPERLINK_A012]] specifying only "E.jpg" in your request. By omitting 
"D.jpg" from your request, e-RS will disassociate attachment "D.jpg" from the referral and only attachment "E.jpg" 
will remain associated.
3. Let us now consider a referral that has four referral letter attachments associated (say "L.doc", "M.doc", "N.doc" 
and "O.doc"), and you wish to add some more files (say "P.doc" and "Q.doc") and remove some files (say "N.doc" 
and "O.doc"). To do this you must upload the additional attachment(s) ("N.doc" and "O.doc") 
using [[HYPERLINK_A020]]. Following that successful upload, you must then associate only all 
referral letter attachments the user wishes to keep (namely "L.doc", "M.doc", "P.doc" and "Q.doc") 
in a single request to [[HYPERLINK_A012]]. Attachments not included in the request 
(namely "N.doc" and "O.doc") will be disassociated from the referral as a result.

As a developer or software supplier, please ensure your users are made aware or protected from this behaviour. 
For example, when a referring user wants to update the attachments on a referral, the user should be presented 
with the currently associated attachments so they can add and/or remove attachments as required.

Note: It is not permissible to remove *all* referral letter attachments leaving zero attachments associated. 
There must be at least one referral letter attachment associated.

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.

## Use case
As an authenticated user

I need to be able to manage referral letter attachments associated with a referral

So I can ensure the service provider has enough information to review/process the referral.


## Related endpoints
Documents must be uploaded into the e-RS document store using [[HYPERLINK_A020]] before they can be associated 
with a referral.

You can check to see what referral letter information has 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.

## Sandbox test scenarios

You can test the following scenarios in our sandbox environment:

| Scenario                                               | Request                                                 |
| ------------------------------------------------------ | ------------------------------------------------------- |
| Add clinical information for first time (single file)  | `ubrn`=`000000070000`, `body` as defined in example 1   |
| Add clinical information for first time (two files)    | `ubrn`=`000000070001`, `body` as defined in example 2   |
| Update clinical information                            | `ubrn`=`000000070001`, `body` as defined in example 3   |

## 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: The parameters object used in maintain referral letter endpoint
  - `meta` object, required
    - `profile` string[], required
  - `resourceType` 'Parameters', required
  - `parameter` object[], required: | Field | Cardinality | Notes | | ---------------------- | ----------- | ------------------------------------------ | | `referralLetterFile` | `1..*` | |
    - `name` 'referralLetterFile', required
    - `resource` object, required: A reference to a document
      - `meta` object, required
        - `profile` string[], required
      - `resourceType` 'DocumentReference', required
      - `type` object, required
        - `coding` object[]
          - `system` 'https://fhir.nhs.uk/STU3/CodeSystem/eRS-AttachmentType-1', required
          - `code` 'REFERRER', required
      - `status` 'current', required
      - `indexed` string, date-time, required
      - `description` string, nullable
      - `content` object[], required
        - `attachment` object, required
          - `url` string, required

## Response `200`

e-RS Referral Request

- Schema (unresolved $ref)

## Other responses

- `400` (unresolved $ref)
- `401` (unresolved $ref)
- `403` (unresolved $ref)
- `404` (unresolved $ref)
- `406` (unresolved $ref)
- `409` (unresolved $ref)
- `412` (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 diagnostics property for specific information regarding the error. | Error code | Description | | ---------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- | | REFERENCE_NOT_FOUND | A supplied reference could not be resolved to valid resource (e.g. a patient, clinician or an organisation). | | INAPPROPRIATE_VALUE | A value, which is acceptable under different conditions, is inappropriate in the context of the other information provided. | | MISSING_VALUE | A field defined as mandatory for an endpoint has not been provided. | | INVALID_STATE | Indicates that the referenced item is not in the correct state for the request to be processed. | | 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. | | NO_RELATIONSHIP | The user does not have a legitimate relationship with the request. | | 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. | | 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). | | CONFLICTING_VALUES | Two or more supplied values are contradictory. | | DUPLICATE_FILENAME | A file being attached, matches another file being attached, or matches a file that is already linked. | | NO_CHANGES_DETECTED | No changes detected when processing supplied request. |
- `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)
