a008-retrieve-worklist.yaml

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

  Use this endpoint to retrieve available worklists of referral requests. 
  Service Providers can use [[HYPERLINK_A023]] to retrieve available worklists of advice and guidance requests. 
  There are currently no worklists of advice and guidance requests for Referrers.

  Worklists provide lists of referral/advice requests that meet certain criteria, 
  typically where a user needs to be aware of something important, or to undertake an action, in order to avoid delays to patient care.

  ## Referring Organisations
  Referring organisations can currently access the following referral related worklists:
    - The 'Letters Outstanding' worklist contains referrals which require a referral letter to be added.
    - The 'Rejected / Triage Response' worklist contains referrals which have had an appointment rejected or have been returned to the referrer with a response as part of a triage outcome.
    - The 'Assessment Returned / Cancelled / DNA' worklist contains referrals which have a clinical assessment outcome of 'advise referrer' recorded, or referrals which have been cancelled by someone outside the initial referring organisation, or referrals where the patient did not attend the appointment booking and the provider has returned the referral back to the referrer for action.
    - The 'Awaiting Booking' worklist contains referrals for which an appointment booking could be made but they do not currently have an appointment booking. This includes referrals that are currently awaiting triage, deferred to provider, or have had their appointment booking cancelled.
  
  Filters can be used in requests for service provider organisation worklists, however, filters cannot be used in requests for referring organisation worklists.

  ## Supported security patterns
  - Healthcare worker, user-restricted access
  
  ## Pre-requisites
  In order to use this endpoint and retrieve the referring organisation worklists, you must be an authenticated e-RS user and use one of the following e-RS roles:
    - `REFERRING_CLINICIAN`
    - `REFERRING_CLINICIAN_ADMIN`
    - `REFERRING_ADMIN`
  
  ### Use case
  As an authenticated user
  
  I need to retrieve a referral worklist for my referring organisation
  
  So that I can determine which referrals I need to take further action on

  ### Related endpoints
  To retrieve pertinent details relating to a referral:
    - Use [[HYPERLINK_A005]] to retrieve the details of the referral
    - Use [[HYPERLINK_A006]] to retrieve the clinical attachments for a referral
    - Use [[HYPERLINK_A007]] to retrieve the clinical information summary PDF for a referral

  You can use [[HYPERLINK_A029]] to determine what endpoints an authenticated user is permitted to use for a referral in it's current state.

  ## Service Providing Organisations
  Service provider organisations can currently access the following referral related worklists:
    - The 'Referrals for Review' worklist contains booked and RAS (triage) referrals that require review by the service provider organisation. The version of each referral in the worklist will also be returned. Note that the version can change due to admin/clinical changes as well as internal e-RS processes.
    - The 'Appointment Slot Issues' worklist contains referrals which have been 'deferred to provider' because of a lack of appointment availability (e.g. no appointment slots). 
    The referrals need to be reviewed and if appropriate booked into a service at the service provider organisation.

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

  ## Pre-requisites
  
  ### Application-restricted access
  In order to use this endpoint you must be an authenticated e-RS calling application, working in the context of a Service Provider Organisation.

  Supported Worklists:
  - Referrals for Review
  - Appointment Slot Issues
  
  The Service filter is mandatory when using this security pattern.
  
  This endpoint must only be used to retrieve the worklist for a given service up to two times per day. If this does not meet your requirements, please [[HYPERLINK_CONTACT_US]] to discuss your use case.
  
  If a worklist response exceeds 10MB, a successful response will not be returned. This is due to the size limitation on the APIM platform.
  
  ### User-restricted access
  In order to use this endpoint you must be an authenticated e-RS user and use one of the following e-RS roles:
    - `SERVICE_PROVIDER_CLINICIAN`
    - `SERVICE_PROVIDER_ADMIN`
    - `SERVICE_PROVIDER_CLINICIAN_ADMIN`

  Supported Worklists:
    - Referrals for Review
    - Appointment Slot Issues

  If a worklist response exceeds 10MB, a successful response will not be returned. This is due to the size limitation on the APIM platform.
  
  ### Use case
  As an authenticated user

  I need to retrieve a referral worklist for my service providing organisation

  So that I can determine which referrals I need to take further action on

  ### Related endpoints

  To retrieve pertinent details relating to a referral:
    - Use [[HYPERLINK_A005]] to retrieve the details of the referral
    - Use [[HYPERLINK_A006]] to retrieve the clinical attachments for a referral
    - Use [[HYPERLINK_A007]] to retrieve the clinical information summary PDF for a referral

  For service providing organisations reviewing booked referrals on the 'Referrals for review' worklist:
    - Use [[HYPERLINK_A013]] to accept a referral into a bookable service
    - Use [[HYPERLINK_A014]] to reject a referral from a bookable service
    - Use [[HYPERLINK_A022]] to request an admin team to rebook or redirect a referral

  For service providing organisations reviewing triage (RAS) referrals on the 'Referrals for review' worklist:
    - Use [[HYPERLINK_A028]] to record the triage outcome based on the available clinical information and attachments

  For service providing organisations reviewing referrals that have been deferred to provider on the 'Appointment slot issues' worklist:
    - Use [[HYPERLINK_A028]] to record the triage outcome based on the available clinical information and attachments

summary: Retrieve referral worklist (A008, FHIR STU3)
operationId: a008-retrieve-worklist
tags:
  - Retrieve clinical information
  - Review referral requests
parameters:
  - $ref: '../headers/request/BearerAuthorization.yaml'
  - $ref: '../headers/request/OdsCodeOnlyUserRestricted.yaml'
  - $ref: '../headers/request/BusinessFunctionOnlyUserRestricted.yaml'
  - $ref: '../headers/request/OnBehalfOfUserID.yaml'
  - $ref: '../headers/request/CorrelationID.yaml'
requestBody:
  required: true
  content:
    application/fhir+json:
      schema:
        $ref: '../eRS-FetchWorklist-Parameters.yaml'
      examples:
        referrals-for-review:
          summary: Referrals for review
          value:
            $ref: '../../examples/retrieveWorklist/requests/MinimalReferralsForReview.json'
        appointment-slot-issues:
          summary: Appointment slot issues
          value:
            $ref: '../../examples/retrieveWorklist/requests/MinimalAppointmentSlotIssues.json'
        filtered-by-specialty:
          summary: Filter by specialty
          value:
            $ref: '../../examples/retrieveWorklist/requests/FilteringBySpecialty.json'
        filtered-by-clinician:
          summary: Filter by clinician
          value:
            $ref: '../../examples/retrieveWorklist/requests/FilteringByClinician.json'
        filtered-by-service:
          summary: Filter by service
          value:
            $ref: '../../examples/retrieveWorklist/requests/FilteringByService.json'
        rejected-triage-responses:
          summary: Rejected Triage Responses
          value:
            $ref: '../../examples/retrieveWorklist/requests/MinimalRejectedTriageResponse.json'
        assessment-returned-cancelled-dna:
          summary: Assessment Returned Cancelled DNA
          value:
            $ref: '../../examples/retrieveWorklist/requests/MinimalAssessmentReturnedCancelledDna.json'
        awaiting-booking:
          summary: Awaiting Booking
          value:
            $ref: '../../examples/retrieveWorklist/requests/MinimalAwaitingBooking.json'
        letters-outstanding:
          summary: Letters Outstanding
          value:
            $ref: '../../examples/retrieveWorklist/requests/MinimalLettersOutstanding.json'
responses:
  '200':
    $ref: '../responses/retrieveWorklist/200Response.yaml'
  '400':
    $ref: '../responses/BadRequest.yaml'
  '401':
    $ref: '../responses/Unauthorized.yaml'
  '403':
    $ref: '../responses/Forbidden.yaml'
  '406':
    $ref: '../responses/NotAcceptable.yaml'
  '415':
    $ref: '../responses/UnsupportedMediaType.yaml'
  '422':
    $ref: '../responses/retrieveWorklist/422Response.yaml'
  '429':
    $ref: '../responses/TooManyRequests.yaml'
  '500':
    $ref: '../responses/InternalServerError.yaml'
  '503':
    $ref: '../responses/ServiceUnavailable.yaml'