---
title: "Upload file to document store (A020, FHIR STU3)"
method: POST
path: "/STU3/Binary"
tags: ["Refer patient", "Request advice", "Arrange appointment", "Arrange triage"]
---

# Upload file to document store (A020, FHIR STU3)

`POST /STU3/Binary`

## Overview

Use this endpoint to upload a file containing clinical information to e-RS ready to be associated with a referral, an advice and guidance request or an advice and guidance response.

## 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`
  - `SERVICE_PROVIDER_CLINICIAN`
  - `SERVICE_PROVIDER_CLINICIAN_ADMIN`

You can only upload file formats that are supported by e-RS. Currently, the supported file formats are:

| File type          | File extension(s)           |
| ------------------ | --------------------------- |
| Plain Text         | `.txt`                      |
| PDF                | `.pdf`                      |
| XML Text           | `.xml`                      |
| RTF Text           | `.rtf`, `.rtx`              |
| Basic Audio        | `.au`                       |
| MPEG audio layer 3 | `.mp3`                      |
| PNG Image          | `.png`                      | 
| GIF Image          | `.gif`                      |
| JPEG Image         | `.jpg,` `.jpe`, `.jpeg`     |
| TIFF Image         | `.tif`, `.tiff`             |
| MPEG Video         | `.mpg`, `.mpeg`, `.mpe`     |
| MSWORD             | `.doc`, `.docx`             |
| DICOM              | `.dcm`                      |

Currently, the maximum file size supported by e-RS is 5MB.

## Use case

As an authenticated user

I need to upload a referral letter or other clinical information file to e-RS

So that I can associate the file with an existing referral or advice and guidance request.

## Important notes

This endpoint **only** performs the file upload and **does not** associate it with a referral. The uploaded file must be explicitly associated with a referral by, for example, using [[HYPERLINK_A012]].

The resulting URL within e-RS for the uploaded file is returned in the 'Location' header of the response.

Request header `NHSD-eRS-Referral-ID` - the ID (typically the UBRN) of the referral which the documents are intended for - is non-mandatory, but must be provided if this file is to be attached to an existing request.

## Related endpoints

You can associate the uploaded file with a specific referral using:
  - [[HYPERLINK_A012]]
  - [[HYPERLINK_A022]]
  - [[HYPERLINK_A028]]

You can associate the uploaded file with a specific advice and guidance request using:
  - [[HYPERLINK_A044]]
  - [[HYPERLINK_A026]]
  - [[HYPERLINK_A027]]

## Headers

- `NHSD-eRS-File-Name` string, required
- `NHSD-eRS-Referral-ID` string

## Parameters

- `#/paths/~1STU3~1Task/get/parameters/0` — unresolved $ref
- `#/paths/~1STU3~1Task/get/parameters/1` — unresolved $ref
- `#/paths/~1STU3~1Task/get/parameters/2` — unresolved $ref
- `#/paths/~1STU3~1Task/get/parameters/3` — unresolved $ref
- `#/paths/~1STU3~1Task/get/parameters/4` — unresolved $ref

## Response `201`

201 (Created) - success response with no body

## Other responses

- `401` — unresolved $ref
- `403` — unresolved $ref
- `406` — unresolved $ref
- `415` — Unsupported Media Type
- `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 | | ---------------------------------- | --------------------------------------------------------------------------------------------------------------------------- | | CONFLICTING_VALUES | Two or more supplied values are contradictory. | | FILE_SIZE_ERROR | The file is either empty or too large. | | INAPPROPRIATE_VALUE | A value, which is acceptable under different conditions, is inappropriate in the context of the other information provided. | | INVALID_VALUE | The input provided does not conform to the expected data types and format. | | MISSING_VALUE | A field defined as mandatory for an endpoint has not been provided. |
- `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-service-production.skmtc.workers.dev/v1/apis/nhs/e-referrals-service-api/revisions/916969ea472f/schema)