a006-retrieve-attachment.yaml

deprecated: true
security:
  - bearerAuth: []
description: |
  ## Overview
   **This endpoint has now been deprecated please use [[HYPERLINK_A042]] instead.**

  Use this endpoint to retrieve a file that is attached to a referral or advice request.

  ## Supported security patterns
  - Application-restricted access
  - Healthcare worker, user-restricted access


  ## Pre-requisites
  ### Authentication
  #### Application-restricted access
  In order to use this endpoint you must be an authenticated e-RS calling application.

  #### Healthcare worker, user-restricted access
  In order to use this endpoint you must be an authenticated e-RS user or application and use one of the following e-RS roles:
    - `REFERRING_CLINICIAN`
    - `REFERRING_CLINICIAN_ADMIN`
    - `SERVICE_PROVIDER_CLINICIAN`
    - `SERVICE_PROVIDER_CLINICIAN_ADMIN`

  ### Attachment availability
  In order to use this endpoint, the attachment to be retrieved must be available for download. Attachments are only made available once an uploaded file has been validated and successfully scanned for malware. A request to retrieve an attachment that is not available for download will result in a 422 error being returned. See the Response section for further information.

  The availability status of an attachment can be retrieved via any endpoint that provides details of an attachment in the success response. Details of the availability statuses that may be returned via these endpoints can be found in the specification for [[HYPERLINK_A005]].

  Prior to retrieving an attachment, you will need to have retrieved the referral or advice request the attachment is associated with (via the [[HYPERLINK_A005]] or [[HYPERLINK_A024]] endpoints, for example). Referrals and advice requests include resolvable URLs to the files currently attached to them, which can be used with this endpoint to retrieve the attachments themselves.

  ### 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.

  Files that are larger than 5MB can be downloaded via the [[HYPERLINK_A042]] endpoint or the e-RS web-based professional application.

  ## Important notes

  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 miniscus service (UBRN #2). 
  This would result in two UBRNs for the referral pathway in this example (but there could be more related UBRNs if onward referred multiple times).

  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_A007]]
    - [[HYPERLINK_A006]]

  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.
  
  The [[HYPERLINK_A006]] endpoint allows you to retrieve attachments up to a maximum file size of 5MB (5242880 bytes), subject to the attachment being available for download. Attempts to retrieve an attachment that is not available, or exceeds the maximum file size, will lead to a 422 error being returned. See the Response section for further information.

  ## Use case

  As an authenticated user

  I need to retrieve a clinical attachment associated with a referral

  So that I can assess its content and decide what further action may be needed.

  ## Related endpoints
  
  You can retrieve a clinical information summary for a referral using [[HYPERLINK_A007]].
  
  ## Sandbox test scenarios
  
  The sandbox for this endpoint is a simple implementation that only supports success cases.
  
  A successful response will always be returned, provided the Binary ID is in a valid format. The Availability Status of a file is not considered in the sandbox and a file will always be available for retrieval.
  
  Successful responses will always return the same example PDF file.

summary: Retrieve attachment (A006, FHIR STU3) [deprecated]
operationId: a006-retrieve-attachment
tags:
  - Retrieve clinical information
parameters:
  - $ref: '../headers/request/BearerAuthorization.yaml'
  - $ref: '../headers/request/OdsCodeOnlyUserRestricted.yaml'
  - $ref: '../headers/request/BusinessFunctionOnlyUserRestricted.yaml'
  - $ref: '../headers/request/CorrelationID.yaml'
  - $ref: '../headers/request/OnBehalfOfUserIDOnlyUserRestricted.yaml'
  - $ref: '../pathParameters/AttachmentLogicalID.yaml'
responses:
  '200':
    $ref: '../responses/retrieveAttachment/200Response.yaml'
  '401':
    $ref: '../responses/Unauthorized.yaml'
  '403':
    $ref: '../responses/Forbidden.yaml'
  '404':
    $ref: '../responses/NotFound.yaml'
  '406':
    $ref: '../responses/NotAcceptable.yaml'
  '422':
    $ref: '../responses/retrieveAttachment/422Response.yaml'
  '429':
    $ref: '../responses/TooManyRequests.yaml'
  '500':
    $ref: '../responses/InternalServerError.yaml'
  '503':
    $ref: '../responses/ServiceUnavailable.yaml'