Search loading...


Explore and Make use of Nationally Defined Messaging APIs


A020: Upload file to the e-RS document store

Status: Live


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

Resource URL

Method URL Authentication
POST {Base URL}/STU3/v1/Binary Session Token (Details)
  • {Base URL} (Dev1) =

Important Information:

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 successfully linked to a referral are periodically deleted from the e-RS document store.

If attachments subsequently need to be added or amended then the e-RS Professional Application should be used.

Supported file types

ID mime type file extension
768 text/plain txt
769 text/html html, htm
770 application/pdf pdf
771 text/xml xml
772 text/rtf rtf, rtx
773 audio/basic au
774 audio/mpeg mp3
775 image/png png
776 image/gif gif
777 image/jpeg jpg, jpe, jpeg
778 image/tiff tif, tiff
779 video/mpeg mpg, mpeg, mpe
780 application/msword doc
781 application/vnd.openxmlformats-officedocument.wordprocessingml.document docx
1406 application/xml xml


Request Operation: 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 Operation: Body

The binary stream of the file being uploaded

Example Request Header

"XAPI_ASID" : "999000000045",
"HTTP_X_SESSION_KEY" : "pro-api-session:e96357b1-298d-4159-ac58-a8953c3262c6",
"Content-Type" : "text/plain",
"Accept" : "application/fhir+json",
"X-ERS-XAPI-META-FILE_NAME" : "test.txt",


Response: Success

If successful, the Status code 201 (Created) is returned and the response header will also contain the e-RS file location of the just uploaded file, as a URL, which must be used to link the file to a UBRN using A012: Maintain Referral Letter.

Example Response Header

"X_ERS_TRANSACTION_ID" : "b3bf226d-16f4-4a7a-867c-a21e1466a2f6-1",
"Location" : "Binary/att-97366-95217"

Response: Failure

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