Status:
This endpoint has been deprecated, meaning you should not use it for new integrations.
Instead, please use our newer e-RS FHIR API solution which is documented here: https://digital.nhs.uk/developer/api-catalogue/e-referral-service-fhir
Description
As a Referring Clinician, Referring Clinician Administrator, Service Provider Clinician or Service Provider Clinician Admin
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) = https://api.dev1.ers.ncrs.nhs.uk/ers-api
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 | |
| 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 |
INPUT
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",
"X-ERS-XAPI-META-INTENDED_UBRN": "000000097366"
OUTPUT
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 |
