---
title: "Retrieve advice and guidance requests worklist (A023, FHIR STU3)"
method: POST
path: "/STU3/CommunicationRequest/$ers.fetchworklist"
tags: ["Review advice and guidance requests"]
---

# Retrieve advice and guidance requests worklist (A023, FHIR STU3)

`POST /STU3/CommunicationRequest/$ers.fetchworklist`

## Overview
Use this endpoint to retrieve available worklists of advice and guidance requests. Use [[HYPERLINK_A008]] to retrieve available worklists of referral requests.

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.

Service provider organisations can retrieve the contents of their 'Advice and guidance requests' worklist using 
this endpoint. This worklist contains advice and guidance requests the provider has received and which need actioning. The version of each advice 
request 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.

There are currently no advice and guidance related worklists available for referring organisations.

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

## Pre-requisites
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`

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 worklist of advice and guidance requests

So I can determine which ones I need to take further action on.

## Related endpoints

Having used this endpoint to retrieve the 'Advice and Guidance Requests' worklist, entries from it can be used as follows:
  - Use [[HYPERLINK_A024]] to retrieve contextual summary details of the advice and guidance request
  - Use [[HYPERLINK_A025]] to retrieve the conversation within the advice and guidance request, including references to attachments
  - Use [[HYPERLINK_A006]] to retrieve clinical attachments for an advice and guidance request
  - Use [[HYPERLINK_A026]] to respond to the referrer supplying advice or requesting further information
  - Use [[HYPERLINK_A027]] to convert the advice and guidance request into a referral. This is only possible if the referrer has authorised the provider to do so
  - Use [[HYPERLINK_A043]] to generate a PDF file overview relating to an advice and guidance request

## Parameters

- `#/paths/~1STU3~1Task/get/parameters/0` — unresolved $ref
- `#/paths/~1STU3~1Task/get/parameters/1` — unresolved $ref
- `#/paths/~1STU3~1Task/get/parameters/2` — unresolved $ref
- `#/paths/~1STU3~1Task/get/parameters/3` — unresolved $ref
- `#/paths/~1STU3~1Task/get/parameters/4` — unresolved $ref

## Response `200`

The response body contains the list of advice and guidance requests (if any) that match the search criteria provided

## Other responses

- `400` — unresolved $ref
- `401` — unresolved $ref
- `403` — unresolved $ref
- `406` — unresolved $ref
- `415` — unresolved $ref
- `422` — Where status code 422 (Unprocessable Entity) is returned then an eRS-OperationOutcome-1 will be included in the body, as detailed below. Check diagnostics property for specific information regarding the error. | Error code | Description | | ---------------------------------- | ----------------------------------------------------------------------------------------------------------------------- | | REFERENCE_NOT_FOUND | A supplied reference could not be resolved to valid resource (e.g. a patient, clinician or an organisation). | | MISSING_VALUE | A field defined as mandatory for an endpoint has not been provided. | | NO_RELATIONSHIP | The user does not have a legitimate relationship with the request or service. | | INVALID_VALUE | The input provided does not conform to the expected data types and format. | | INVALID_CODE | The input provided for a field is not one of the defined legal values. | | UNEXPECTED_FIELD | A field is provided that is not expected as part of the request. E.g. a field is mis-spelt, was defined on a previous version of the endpoint but has subsequently been removed. | | INVALID_FHIR_STRUCTURE | The FHIR data structure in the message body does not match the expected structure (e.g. an array is present for a value when no array is expected). |
- `429` — unresolved $ref
- `500` — unresolved $ref
- `503` — unresolved $ref

---

[API](https://skmtc.dev/nhs/apis/e-referrals-service-api.md) · [All operations](https://skmtc.dev/nhs/apis/e-referrals-service-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/nhs/e-referrals-service-api/revisions/916969ea472f/schema)