Skip to main content

Migrating to the FHIR R4 upload attachment endpoint

Learn how to update your software to use the new API endpoint for uploading file attachments.

Page contents

Overview

This page explains how to migrate your software from the FHIR STU3 Upload file to document store (A020) endpoint to the new FHIR R4 Upload file to document store (A039) endpoint.

Migration will be required to support the upload of files greater than 5MB.

Who will be affected

All partners integrated with the Upload file to document store (A020, FHIR STU3) endpoint.

What we are doing

The Upload file to document store (A020, FHIR STU3) API endpoint will be deprecated and no longer available for new integrations. Inline with our sunsetting policy, we will remove support for this endpoint from September 2026.

Integration partners should migrate to the Upload file to document store (A039, FHIR R4) API endpoint before September 2027, when the endpoint will be retired.

Why we are making the change

The e-RS is increasing the maximum supported file size to enable care settings to share larger attachments and high-resolution media.

The existing Upload file to document store (A020, FHIR STU3) endpoint uploads attachments through the e-RS API platform and supports files up to 5 MB (5242880 bytes).

The new Upload file to document store (A039, FHIR R4) endpoint uses a modern direct-upload approach, allowing clients to upload files directly to the e-RS document store using a pre-authorised upload URL.

This approach:

  • supports larger file sizes, up to 100MB

  • improves upload performance and scalability

  • enables asynchronous malware scanning and file validation

What this means for you

The Upload file to document store (A020, FHIR STU3) endpoint will continue to support uploads of up to 5MB only.

To upload attachments larger than 5MB, integration partners must use the Upload file to document store (A039, FHIR R4) endpoint.

Next steps

What you need to do
  • Support asynchronous processing
  • Understand the new upload pattern
  • Implement endpoint changes

1. Support asynchronous processing

With the introduction of direct file uploads, attachments are processed asynchronously.

Processing includes:

  • file validation
  • file type and size checks
  • malware scanning

As a result, the direct upload operation does not mean the file is immediately available for users. Attachments can exist in one of four availability states:

File availability status Meaning
AVAILABLE File can be downloaded
PENDING Processing or malware scanning in progress
VALIDATION_FAILED Validation checks failed
THREATS_FOUND Malware or security threats were detected and the file has been quarantined

Your software should:

  • inform users when files are still being processed
  • check availability status to confirm successful upload, prior to any subsequent referral/A&G association
  • handle uploads that subsequently fail validation or threats found

2. Understand the new upload pattern

Existing A020, FHIR STU3 upload endpoint

The Upload file to document store (A020, FHIR STU3) endpoint uses a single-step upload model.

The file binary is sent directly to the e-RS API in a single HTTP request. The response returns a file reference that can later be linked to a referral or an advice and guidance request.

New A039, FHIR R4 upload endpoint

The Upload file to document store (A039, FHIR R4) endpoint adopts a two-step pre-signed URL upload pattern.

This modern approach does not send the file through the API. Instead, the API provides a temporary upload URL, and the file is then uploaded directly to the underlying object storage.

Partners must ensure they:

  • use the URL to upload the file
  • do not cache the temporary location
  • generate a new URL each time a file is required for upload

The temporary location will only be valid for 30 seconds.

3. Implement endpoint changes

Partners should replace calls to Upload file to document store (A020, FHIR STU3) with Upload file to document store (A039, FHIR R4)​.

The worked example shows how you can upload an attachment using both old and new endpoints.

This guide aims to highlight the types of changes required, it does not represent an exhaustive list of differences.

Please ensure you review the documentation for each endpoint in detail.

Worked example

Using A020

The metadata is passed in HTTP headers and the request body contains the binary file.

POST /STU3/Binary

Request

Request
Headers:
content-type: text/plain
nhsd-end-user-organisation-ods: R69
nhsd-ers-business-function: SERVICE_PROVIDER_CLINICIAN_ADMIN
nhsd-ers-file-name: test.txt
nhsd-ers-on-behalf-of-user-id: 021600556514
nhsd-ers-referral-id: 000000070000
x-correlation-id: 11C46F5F-CDEF-4865-94B2-0EE0EDCC26DA

Body:
<binary file content>

Response

Response
status: 201

Headers:
location: Binary/att-97366-95217
x-correlation-id: 11C46F5F-CDEF-4865-94B2-0EE0EDCC26DA

The returned binary reference can be subsequently linked to the referral, or A&G request, using the Maintain referral letter (A012, FHIR STU3) endpoint.

Using A039

1. Request upload URL

Request

Request
Headers:
nhsd-end-user-organisation-ods: R69
nhsd-ers-business-function: SERVICE_PROVIDER_CLINICIAN_ADMIN
nhsd-ers-file-mime-type: text/plain
nhsd-ers-file-name: test.txt
nhsd-ers-file-size: 1024
nhsd-ers-on-behalf-of-user-id: 021600556514
nhsd-ers-referral-id: 000000070000
x-correlation-id: 11C46F5F-CDEF-4865-94B2-0EE0EDCC26DA

Response

Response
Headers:
x-correlation-id: 11C46F5F-CDEF-4865-94B2-0EE0EDCC26DA
nhsd-ers-referral-id: 000000070000
Location: https://s3.amazonaws.com/nhs-example-bucket/test.txt?X-Amz-Algorithm=AWS4-HMAC...
Content-Disposition: attachment; filename="test.txt"; filename*=UTF-8''test.txt

Body:
{
  "id": "d497bbe3-f88b-45f1-b3d4-9c563e4c0f5f",
  "resourceType": "Binary",
  "meta":
  {
    "lastUpdated": "2026-09-04T09:40:04.656Z"
  },
  "identifier":
  [
    {
      "system": "https://fhir.nhs.uk/Id/ers-binary-id",
      "value": "d497bbe3-f88b-45f1-b3d4-9c563e4c0f5f"
    }
  ],
  "contentType": "text/plain"
}

2. Upload the file

Request

Request
PUT https://s3.amazonaws.com/nhs-example-bucket/test.txt?X-Amz-Algorithm=AWS4-HMAC...

Content-Type: text/plain
Content-Disposition: attachment; filename="test.txt"; filename*=UTF-8''test.txt
Content-Length: 10

<binary file content>

The Content-Type header must contain the correct MIME type to go with the file extension supplied. See the list of options in the A039 endpoint documentation.

The Content-Disposition header must contain the value that was provided in the response message. See the Request upload URL section above.

The Content-Length header must exactly match the file size in bytes. If the value is:

  • greater than the actual file size, the service will wait for the remaining data and the upload will fail
  • less than the actual file size, the file will be truncated and may not open correctly for users

Ensure your implementation calculates and supplies the correct Content-Length value for every upload, and verify this during testing.

The Content-Length value must be identical to the Content-Length value supplied in the POST request. See the Request upload URL section above.

Response

Response

status: 200

3. Monitor availability status

Uploaded files are validated and scanned for malware before they become available. As a result, a file may not be immediately available for retrieval or association.

To confirm that a file is available, call the Retrieve Attachment (A042, FHIR R4) endpoint using the binaryID. A file is considered available when the endpoint returns HTTP 307. It is not necessary to follow the redirect and download the file.

If the file is not yet available, the endpoint will return HTTP 422 with one of the following states: PENDING, THREATS_FOUND and VALIDATION_FAILED.

PENDING

For files in the PENDING state, retry the request after a 3-second delay.

THREATS_FOUND / VALIDATION_FAILED

Files in the THREATS_FOUND or VALIDATION_FAILED states will never become available for download. Your application should detect and handle these states, whilst providing appropriate feedback to your users.

To minimise validation failures, ensure that the:

  • content type matches the file extension
  • file name does not exceed 255 characters
  • file size does not exceed 5MB
  • file type is supported

Last edited: 10 September 2026 3:10 pm