Search loading...


Explore and Make use of Nationally Defined Messaging APIs


A012: Maintain Referral Letter

Status: Beta


Base URL (Dev3):

Method URL Authentication
POST STU3/v1/ReferralRequest/{UBRN}/$ers.maintainReferralLetter Session Token (Details)


As a Referring Clinician (/Administrator)
I want to associate files I have uploaded to a referral
So that I can create the referral letter

Prerequisite Operations

Each file to be attached to a referral needs to have been individually uploaded first by calling A020: Upload file to document store. A020 will have returned to the caller the e-RS attachment ID of each uploaded file; these are the IDs that need to be passed to the Maintain Referral Letter API so that they can be associated to the referral and thus form the referral letter (which is to be considered as a “collection of files”)

Request Operation

Request Header

Field Name Value
XAPI_ASID The “Accredited System ID” issued to the third party
HTTP_X_SESSION_KEY The session key generated by the Create Session endpoint (A001)
Accept application/fhir+json
Content-Type application/fhir+json

Request Body

The Operation Definition for this endpoint is available on the FHIR server: eRS-maintainReferralLetter-Operation-1

Parameter Name Cardinality Type Notes
referralLetterFile 1..* Resource The structure definition of this resource is: eRS-DocumentReference-1


Request Header
Request Body



HTTP Status code 200 (OK) is returned. The response body contains the just updated eRS-ReferralRequest-1


Response Body


If an error occurs, the relating HTTP status code will be returned in the header. Where status code 422 (Unprocessable Entity) is returned then an eRS-OperationOutcome-1 will be included in the body, as detailed below.

issue.details.code Description
CONFLICTING_VALUES Two or more of the attachment IDs provided are the same
DUPLICATE_FILENAME The names of the files that (having been previously uploaded) are being associated to the referral match the names of existing files associated with the referral, for example files uploaded during an advice and guidance conversation; or: two or more of the files uploaded via A020: Upload file to document store have the same name
INAPPROPRIATE_VALUE In the document reference, the type has value other than ‘REFERRER’, or the status is other than ‘current’
INVALID_REQUEST_STATE The UBRN relates to an onward referral; or: the referral state is either incomplete or cancelled or the referral has been superseded by an onward referral; or: the referral has an appointment booking with a date prior to today; or: the referral has an appointment booking that has been ‘DNAd’ (‘Did Not Attend’); or: the referral already has referral letter files associated
INVALID_REQUEST_TYPE The UBRN provided exists in e-RS but does not correspond to a referral
INVALID_STATE One of the attachment IDs provided relates to a file that is already linked to a referral.
INVALID_VALUE The input provided does not conform with the expected data types and format specifically documented on the FHIR OperationDefinition eRS-maintainReferralLetter-Operation-1 or on the related FHIR profile eRS-DocumentReference-1
NO_ACCESS One of the attachment IDs provided relates to a file that was not uploaded by the current user
NO_RELATIONSHIP The user does not have a suitable legitimate relationship with the referral
PATIENT_ERROR There was an error retrieving the patient’s record from SDS - this patient cannot be referred via e-RS
REFERENCE_NOT_FOUND The file identified by the attachment ID does not exist in the e-RS document store

All content is available under the Open Government Licence v3.0, except where otherwise stated