NHSDigital · TomKinghorn · Sep 9, 2026 · Sep 10, 2026 · Sep 10, 2026 · Sep 10, 2026
@@ -5,6 +5,7 @@
 Reads an openapi spec on stdin and substitutes placeholders with values stored in dictionary,
 then prints it on stdout.
 """
+
 import sys
 
 
@@ -41,6 +42,7 @@ def main():
         "[[HYPERLINK_A036]]": "[Cancel referral (A036)](#post-/STU3/ReferralRequest/-ubrn-/$ers.cancelReferral)",
         "[[HYPERLINK_A037]]": "[Retrieve healthcare service version (A037)](#head-/R4/HealthcareService/-id-)",
         "[[HYPERLINK_A038]]": "[Retrieve appointment (A038)](#get-/STU3/Appointment/-id-)",
+        "[[HYPERLINK_A039]]": "[Upload file to document store (A039)](#post-/R4/Binary)",
         "[[HYPERLINK_A040]]": "[Retrieve “on-behalf-of” practitioner user information (A040)](#get-/R4/Practitioner)",
         "[[HYPERLINK_A041]]": "[Search for service requests (A041)](#get-/R4/ServiceRequest)",
         "[[HYPERLINK_A042]]": "[Retrieve attachment (A042)](#get-/R4/Binary/-id-)",

@@ -7,8 +7,6 @@ description: |
 
   Use this endpoint to initiate the upload of 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.
 
-   This end point supersedes A020 and should be used for any new work. 
-
   ## Supported security patterns
   - Healthcare worker, user-restricted access
 
@@ -37,7 +35,7 @@ description: |
   | MSWORD             | `.doc`, `.docx`             | `application/msword`, `application/vnd.openxmlformats-officedocument.wordprocessingml.document` |
   | DICOM              | `.dcm`                      | `application/dicom`                                                          |
 
-  Currently, the maximum file size supported by e-RS is 5MB. This will be increasing to 100MB inline with the roadmap.
+  Currently, the maximum file size supported by e-RS is 5MB. This will be increasing to 100MB in the October 2026 (16.9) release.
 
   ## Use case
 
@@ -65,12 +63,12 @@ description: |
     - perform a PUT to this location to upload the file
     - do not cache the temporary location
     - do not attempt to re-use the temporary location
-    - supply a file size header (when calling A039) that EXACTLY matches the size of the file uploaded
+    - supply a file size header that exactly matches the size of the file uploaded
 
   When performing the PUT operation the following headers are required:
-   - `Content-Type` - this should be the same value that was provided in the `NHSD-eRS-File-MIME-Type` header when calling A039
-   - `Content-Disposition` - this should contain the value returned in the `Content-Disposition` header of the A039 response
-   - `Content-Length` - this should be the exact length of the file in bytes and must be the same as the value provided in the `NHSD-eRS-File-Size header` when calling A039.
+   - `Content-Type` - this should be the same value that was provided in the `NHSD-eRS-File-MIME-Type` header
+   - `Content-Disposition` - this should contain the value returned in the `Content-Disposition` header of the response
+   - `Content-Length` - this should be the exact length of the file in bytes and must be the same as the value provided in the `NHSD-eRS-File-Size header`
 
   See the Response HTTP 200 section for further information.
 

@@ -51,8 +51,8 @@ description: |
   A referral pathway in e-RS can be made up of more than one UBRN. For example: a referral is booked and seen in a general knee clinical assessment service (UBRN #1), and the service decides to onward refer to a more specialist knee meniscus service (UBRN #2). This would result in two UBRNs for the referral pathway. There may be additional related UBRNs if there are multiple onward referrals.
 
   As such, it is important that all clinical information is obtained from across all the related UBRNs referenced in [[HYPERLINK_A005]]. You can do this using the following endpoints:
-    - [[HYPERLINK_A006]]
     - [[HYPERLINK_A007]]
+    - [[HYPERLINK_A042]]
 
   Note: It is possible that the initial UBRN may be the only one in the referral pathway to have clinical information and/or attachments associated.
 

@@ -33,9 +33,11 @@ description: |
 
   ### Maximum file size
 
-   The [[HYPERLINK_A006]] endpoint allows you to retrieve attachments up to a maximum file size of 5MB (5242880 bytes). Attempting to retrieve a file over this limit will lead to a 422 error being returned. See the Response section for further information. Due to this, prior to calling this endpoint, the size of the attachment being retrieved should first be validated so that this error can be avoided.
+  The [[HYPERLINK_A006]] endpoint allows you to retrieve attachments up to a maximum file size of 5MB (5242880 bytes).
 
-  Files that are larger than 5MB can be downloaded via the [[HYPERLINK_A042]] endpoint or the e-RS web-based professional application.
+  Use the DocumentReference.content.attachment.size resource to check the file is not larger than 5MB. The resource is returned in the success response for any endpoint that provides details of an attachment. For example: [[HYPERLINK_A005]] for referrals and [[HYPERLINK_A024]] for advice and guidance requests. Attempting to retrieve a file over this limit will lead to a 422 error being returned. See the Response section for further information. Due to this, prior to calling this endpoint, the size of the attachment being retrieved should first be validated so that this error can be avoided.
+
+  When a file larger than 5MB is encountered, your solution must provide a means for users to access it. This can be achieved either by implementing the [[HYPERLINK_A042]] endpoint, or by directing users to manually download the file through the e-RS web-based professional application.
 
   ## Important notes
 

@@ -1,7 +1,9 @@
+deprecated: true
 security:
   - bearerAuth: []
 description: |
   ## Overview
+   **This endpoint has now been deprecated please use [[HYPERLINK_A039]] instead.**
 
   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.
 

@@ -290,9 +290,6 @@ tags:
   - name: Review advice and guidance requests
 
 paths:
-  /R4/Binary:
-    post:
-      $ref: 'components/r4/schemas/endpoints/a039-upload-file-to-document-store.yaml'
   /STU3/CodeSystem/{codeSystemType}:
     get:
       $ref: 'components/stu3/schemas/endpoints/a004-retrieve-reference-data.yaml'
@@ -335,6 +332,9 @@ paths:
   /STU3/Binary:
     post:
       $ref: 'components/stu3/schemas/endpoints/a020-upload-file-to-document-store.yaml'
+  /R4/Binary:
+    post:
+      $ref: 'components/r4/schemas/endpoints/a039-upload-file-to-document-store.yaml'
   /STU3/ReferralRequest/{ubrn}/$ers.maintainReferralLetter:
     post:
       $ref: 'components/stu3/schemas/endpoints/a012-maintain-referral-letter.yaml'