File attachments

Over the course of financial year (FY) 2025/2026, the e-Referral Service (e-RS) will be making file attachment changes in our API.

This page aims to provide a high-level summary of the release plan. It will also contain detailed changes for each release, their impact on your integrated software, and what actions you need to take.

All partners integrated with the Retrieve attachment (A006, FHIR STU3) or Upload file to document store (A020, FHIR STU3) endpoints will be impacted. Partners will be required to make changes to mitigate the impact of future releases. This is irrespective of whether you choose to integrate with the new endpoints or not.

The file attachments work includes:

• an increase of the file size limit
• a switch to direct file upload and download
• the introduction of malware scanning

File size limit

For a long time, e-RS has maintained a file size limit of 5MB.

To support new care settings and share high-resolution media, the e-RS will be increasing the maximum supported file size. The maximum file size will increase to 100MB, and may increase beyond this in the future.

Direct file upload/download

To enable fast, efficient transfer of large files, new endpoints will be introduced. These endpoints will allow direct file transfer to and from the e-RS object store.

The 5MB limit for the existing upload and download endpoints will remain in place. As will attachments uploaded via the HL7 V3 API.

Malware scanning

Alongside the file size increase, the e-RS will scan all file uploads for malware. This will impact how you process file downloads.

Download high resolution diagram (SVG, 944kB)

Release 1 includes a new download endpoint, alongside a deprecation notice.

There are also updates to the:

• existing API responses to include the file availability status
• API documentation
• API sandbox

New download endpoint

To allow faster and more efficient transfer of large files, a new endpoint is required to facilitate download directly from the e-RS object store.

The download endpoint Retrieve attachment (A042, FHIR R4):

• is being released early to give partners the opportunity to integrate before the file size limit increases
• must be used to retrieve file attachments larger than 5MB

Deprecation notice

The Retrieve attachment (A006, FHIR STU3) endpoint will only support a maximum file size of 5MB (5242880 bytes) and will be deprecated.

The deprecation notice includes a migration guide to assist partners in moving to the new FHIR R4 endpoint.

File availability status

With the introduction of direct uploads, files will be processed asynchronously and may not always be available for download immediately. This processing includes validation checks, for example, file type, file size, and malware scanning.

To allow your integrated software to take the appropriate action, an availability status will be added to the attachment metadata.

In this release, the file availability status will always be set to AVAILABLE. Ensuring that files are immediately ready for download.

API documentation

The API technical specification will be updated to include guidance on each availability state and where the file availability status can be found.

API sandbox

The API sandbox will be upgraded to support the technical specification and enable early integration.

Release 2 will start to send all file availability states in the API responses:

1. AVAILABLE - the file is available for download.

2. PENDING - the file is being scanned and cannot be retrieved.

3. VALIDATION_FAILED - the file has failed validation and cannot be retrieved.

4. THREATS_DETECTED - the file has been quarantined after detecting a threat and cannot be retrieved.

Partner software must be able to deal with scenarios where an attachment is not available.

Guidance on how to implement changes to your software is documented as part of the Release 1 page.

Release 3 includes:

• a new upload endpoint
• a deprecation notice for the existing upload endpoint
• updates to the API documentation

New upload endpoint

To allow faster and more efficient transfer of large files, a new endpoint is required to facilitate upload directly to the e-RS object store.

The new Upload file to document store (A039, FHIR R4) endpoint will allow the upload of file attachments larger than 5MB.

Partners will need to integrate with this endpoint if you wish to leverage your integration.

Deprecation notice

The Upload file to document store (A020, FHIR STU3) endpoint will only support a maximum file size of 5MB (5242880 bytes) and will be deprecated.

The deprecation notice includes a migration guide to assist partners in moving to the new FHIR R4 endpoint.

API documentation

The API technical specification and API sandbox will be updated to introduce the new upload endpoint.

Release 4 introduces the capability, in both the e-RS professional web application and the API, to support file sizes up to 100MB. Prior to this release, the file size limit will remain at 5MB.

The existing upload/download endpoints will continue to be limited to 5MB:

• Retrieve attachment (A006, FHIR STU3) 
• Upload file to document store (A020, FHIR STU3)

If you have a query or need further information about file attachments, please contact us at [email protected].