a041-search-service-request.yaml

security:
  - bearerAuth: []
description: |
  ## Overview

  <p style="color:red;font-weight:bold">
  Warning: This endpoint is part of a new suite of APIs currently in development. We currently advise against integrating with this endpoint as its definition may be subject to change. If you would still like to use this endpoint please contact us before you start integration.
  </p>

  The e-RS FHIR API represents an advice and guidance request and a referral in FHIR R4 as a ServiceRequest. This endpoint allows you to search for attributes about a ServiceRequest.

  At present the following is the only permitted use case for using this endpoint, but it is expected that additional use cases will be added as future needs are identified and prioritised.
  - For FHIR R4 endpoints, the e-RS FHIR API requires a unique identifier for the ServiceRequest, instead of the UBRN, to identify an advice and guidance request or referral request. To support partners to transition from previous FHIR versions, and utilise the newer FHIR endpoints, this endpoint can be used as a bridging mechanism so that you can search for the required unique identifiers using a UBRN. 

  ## Supported security patterns

  - Healthcare worker, user-restricted access

  ## Pre-requisites
  To use this endpoint, you must be an authenticated e-RS user and use one of the following e-RS roles:

  - `REFERRING_CLINICIAN`
  - `REFERRING_CLINICIAN_ADMIN`
  - `SERVICE_PROVIDER_CLINICIAN`
  - `SERVICE_PROVIDER_CLINICIAN_ADMIN`

  You need to use the Unique Booking Reference Number (UBRN) of an advice and guidance request or referral request.


  ## Important notes

  When searching for a unique identifier for a ServiceRequest, it's important to note that one UBRN can relate to both an advice and guidance request and a referral. In this case, the response could contain two unique identifiers: one relating to the advice and guidance request and one relating to the referral.

  ## Use case

  As an authenticated user

  I need the unique identifier for a given advice and guidance request or referral request

  So that I can view or action an advice and guidance request or referral

  ## Related endpoints

  Once the ServiceRequest's unique identifier has been retrieved it can then be used to call the following endpoints to manage its clinical attachments:
  - [[HYPERLINK_A012]]

  ## Sandbox test scenarios
  You can test the following scenarios in our sandbox environment

  | Scenario                                                                                | UBRN           |
  | --------------------------------------------------------------------------------------- | -------------- |
  | A response containing a single Request ID for a `ServiceRequest` of category `referral` | `000000070000` |
  | A response containing a single Request ID for a `ServiceRequest` of category `request`  | `000000070001` |
  | A response containing two Request IDs                                                   | `000000070002` |
  | A response containing an empty bundle                                                   | `000000070003` |
summary: Search for service requests (A041, FHIR R4)
operationId: a041-search-service-request
tags:
  - Retrieve clinical information
parameters:
  - $ref: '../headers/request/BearerAuthorization.yaml'
  - $ref: '../headers/request/BusinessFunctionOBO.yaml'
  - $ref: '../headers/request/CorrelationID.yaml'
  - $ref: '../headers/request/OdsCode.yaml'
  - $ref: '../headers/request/OnBehalfOfUserID.yaml'
  - $ref: '../queryParameters/Identifier.yaml'
responses:
  '200':
    $ref: '../responses/searchServiceRequest/200Response.yaml'
  '400':
    $ref: '../responses/searchServiceRequest/400Response.yaml'
  '401':
    $ref: '../responses/Unauthorized.yaml'
  '403':
    $ref: '../responses/searchServiceRequest/403Response.yaml'
  '406':
    $ref: '../responses/NotAcceptable.yaml'
  '429':
    $ref: '../responses/TooManyRequests.yaml'
  '500':
    $ref: '../responses/InternalServerError.yaml'
  '503':
    $ref: '../responses/ServiceUnavailable.yaml'