a020-upload-file-to-document-store.yaml

security:
  - bearerAuth: []
description: |
  ## 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]]

summary: Upload file to document store (A020, FHIR STU3)
operationId: a020-upload-file-to-document-store
tags:
  - Refer patient
  - Request advice
  - Arrange appointment
  - Arrange triage
parameters:
  - $ref: '../headers/request/BearerAuthorization.yaml'
  - $ref: '../headers/request/OdsCode.yaml'
  - $ref: '../headers/request/BusinessFunctionOBO.yaml'
  - $ref: '../headers/request/OnBehalfOfUserID.yaml'
  - $ref: '../headers/request/CorrelationID.yaml'
  - $ref: '../headers/request/ErsFileName.yaml'
  - $ref: '../headers/request/ErsReferralId.yaml'
requestBody:
  required: true
  content:
    text/plain:
      schema:
        $ref: '../file/StringBinarySchema.yaml'
      example: 'This is some example text.'
    application/pdf:
      schema:
        $ref: '../file/StringBinarySchema.yaml'
    text/xml:
      schema:
        $ref: '../file/StringBinarySchema.yaml'
    text/rtf:
      schema:
        $ref: '../file/StringBinarySchema.yaml'
    audio/basic:
      schema:
        $ref: '../file/StringBinarySchema.yaml'
    audio/mpeg:
      schema:
        $ref: '../file/StringBinarySchema.yaml'
    image/png:
      schema:
        $ref: '../file/StringBinarySchema.yaml'
    image/gif:
      schema:
        $ref: '../file/StringBinarySchema.yaml'
    image/jpeg:
      schema:
        $ref: '../file/StringBinarySchema.yaml'
    image/tiff:
      schema:
        $ref: '../file/StringBinarySchema.yaml'
    video/mpeg:
      schema:
        $ref: '../file/StringBinarySchema.yaml'
    application/msword:
      schema:
        $ref: '../file/StringBinarySchema.yaml'
    application/vnd.openxmlformats-officedocument.wordprocessingml.document:
      schema:
        $ref: '../file/StringBinarySchema.yaml'
    application/dicom:
      schema:
        $ref: '../file/StringBinarySchema.yaml'
responses:
  '201':
    $ref: '../responses/uploadFileToDocumentStore/201Response.yaml'
  '401':
    $ref: '../responses/Unauthorized.yaml'
  '403':
    $ref: '../responses/Forbidden.yaml'
  '406':
    $ref: '../responses/NotAcceptable.yaml'
  '415':
    $ref: '../responses/UnsupportedMediaType.yaml'
  '422':
    $ref: '../responses/uploadFileToDocumentStore/422Response.yaml'
  '429':
    $ref: '../responses/TooManyRequests.yaml'
  '500':
    $ref: '../responses/InternalServerError.yaml'
  '503':
    $ref: '../responses/ServiceUnavailable.yaml'