Search loading...


Explore and Make use of Nationally Defined Messaging APIs


A020: Upload file to the e-RS document store

Status: Beta


Base URL (Dev3):

Method URL Authentication
POST STU3/v1/Binary Session Token (Details)


As a Referring Clinician (/Administrator)
I want to upload a file to the e-RS document store
so that I can then link it to a referral as part of its referral letter

Important note:

Each file needs to be individually uploaded via this endpoint then an additional call made to endpoint A012: Maintain Referral Letter to link the file(s) to the referral once all files have been uploaded. Any files not linked to a referral are periodically deleted from the e-RS document store.

Prerequisite Operations

This endpoint has no pre-requisites

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)
X-ERS-XAPI-META-FILE_NAME The name of file being uploaded, including the extension
X-ERS-XAPI-META-INTENDED_UBRN The UBRN for the referral which the documents are intended for
Accept application/fhir+json
Content-Type The mime type of the file being uploaded

Request Body

The binary stream of the file being uploaded


Request Header



HTTP Status code 201 (Created) is returned. The header will also contain the e-RS file ID of the just uploaded file. No response body is returned.


Response Header


If an error occurs, the relating HTTP status code will be returned. 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 The file extension is not compatible with the file mime type
FILE_SIZE_ERROR The file is too large; the max size is 5MB
INAPPROPRIATE_VALUE The mime type is not supported
INVALID_VALUE If the total length of the File Name including extension is greater than 255 characters
MISSING_VALUE File name, file mime type or the file data are not supplied

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