a005-retrieve-referral-request-versioned.yaml

security:
  - bearerAuth: [ ]
description: |
  ## Overview
  
  Use this endpoint to retrieve a specific version of `ReferralRequest`.

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

  ## Pre-requisites

  The pre-requisites for this endpoint are the same as for endpoint [[HYPERLINK_A005]].

  Note: e-RS only supports the retrieval of the most recent version of `ReferralRequest`. You cannot retrieve earlier versions.

  ## Important notes
  ### Attachment availability

  In order to retrieve an attachment using the [[HYPERLINK_A042]] (or deprecated [[HYPERLINK_A006]]) endpoint, the attachment must be available for download. Attachments are only made available once an uploaded file has been validated and successfully malware scanned. A request to retrieve an attachment that is not available for download will result in an error being returned. See [[HYPERLINK_A042]] for more information.

  The availability status of an attachment can be retrieved via any endpoint that returns an eRS-AvailabilityStatus-1 code in the success response, including [[HYPERLINK_A005]]. The eRS-AvailabilityStatus-1 code can return one of four possible values, as detailed below.

  | eRS-AvailabilityStatus-1 code | Description / Guidance                                                                                            |
  |-------------------------------|-------------------------------------------------------------------------------------------------------------------|
  | AVAILABLE                     | The file is available for download.                                                                               |
  | PENDING                       | The file is being scanned and cannot be retrieved. Wait at least 5 minutes before checking its availability again |
  | THREATS FOUND                 | The file has been quarantined after detecting a threat and cannot be retrieved.<br> Contact the organisation that uploaded the file to resolve the issue and get the information you need. Use the extensions returned via this endpoint: Extension-eRS-AttachedBy-1 and Extension-eRS-AttachedByOrganisation-1. |
  | VALIDATION_FAILED             | The file has failed validation and cannot be retrieved.<br> Contact the organisation that uploaded the file to resolve the issue and get the information you need. Use the extensions returned via this endpoint: Extension-eRS-AttachedBy-1 and Extension-eRS-AttachedByOrganisation-1. Validation can fail because the: <ul><li>content type of the file is not supported</li><li>content type of the file does not correlate with the file extension</li><li>file provided is too large and is not supported by e-RS.</li></ul> |

  ### Receiving an e-Referral Pathway Start Date  
   
  The e-Referral Pathway Start Date is a derived value of when the Referral To Treatment (RTT) clock starts. Find out how e-RS derives the pathway start date [[HYPERLINK_PATHWAY_START]].
  
  If a referral was created with an alternate pathway start date, then this will be available in the referral request response.
  
  Service providers must always ensure the correct start date is recorded in line with [[HYPERLINK_RTT_RULES]].

  ## Use case

  See [[HYPERLINK_A005]].

  ## Related endpoints

  See [[HYPERLINK_A005]].

  ## Sandbox test scenarios
  You can test the following scenarios in our sandbox environment
  
  | Scenario                                                                 | Request                               |
  | ------------------------------------------------------------------------ | ------------------------------------- |
  | Unbooked `ReferralRequest`                                               | `ubrn`=`000000070000`, `version`=`5`  |
  | `ReferralRequest` booked to directly-bookable service                    | `ubrn`=`000000070001`, `version`=`5`  |
  | `ReferralRequest` booked to indirectly-bookable service                  | `ubrn`=`000000070002`, `version`=`5`  |
  | `ReferralRequest` deferred to service provider for booking               | `ubrn`=`000000070003`, `version`=`5`  |
  | `ReferralRequest` that was converted from an Advice and Guidance Request | `ubrn`=`000000070004`, `version`=`5`  |
  | `ReferralRequest` with related `ReferralRequest`                         | `ubrn`=`000000070005`, `version`=`5`  |
  | `ReferralRequest` with additional requirements listed                    | `ubrn`=`000000070011`, `version`=`5`  |
  | `ReferralRequest` with attachments unavailable to download               | `ubrn`=`000000070012`, `version`=`5`  |  

summary: Retrieve referral request (versioned) (A005, FHIR STU3)
operationId: a005-retrieve-referral-request-versioned
tags:
  - Retrieve clinical information
parameters:
  - $ref: '../pathParameters/Ubrn.yaml'
  - $ref: '../pathParameters/Version.yaml'
  - $ref: '../headers/request/BearerAuthorization.yaml'
  - $ref: '../headers/request/OdsCodeOnlyUserRestricted.yaml'
  - $ref: '../headers/request/BusinessFunctionOnlyUserRestricted.yaml'
  - $ref: '../headers/request/OnBehalfOfUserIDOnlyUserRestricted.yaml'
  - $ref: '../headers/request/CorrelationID.yaml'
responses:
  '200':
    $ref: '../responses/retrieveReferralRequest/200Response.yaml'
  '400':
    $ref: '../responses/BadRequest.yaml'
  '401':
    $ref: '../responses/Unauthorized.yaml'
  '403':
    $ref: '../responses/Forbidden.yaml'
  '404':
    $ref: '../responses/NotFoundVersioned.yaml'
  '406':
    $ref: '../responses/NotAcceptable.yaml'
  '422':
    $ref: '../responses/retrieveReferralRequest/422Response.yaml'
  '429':
    $ref: '../responses/TooManyRequests.yaml'
  '500':
    $ref: '../responses/InternalServerError.yaml'
  '503':
    $ref: '../responses/ServiceUnavailable.yaml'