--- title: "Available actions for user (A029, FHIR STU3)" method: GET path: "/STU3/Task" tags: ["Change appointment", "Manage referral", "Review referral requests"] --- # Available actions for user (A029, FHIR STU3) `GET /STU3/Task` ## Overview This endpoint allows an authenticated e-RS user to check ahead of performing an action, whether or not the action is permitted. This endpoint performs a search for available and supported actions that can be *currently* performed, by the *current* e-RS user on a *specific* referral. When a permitted action is returned, the e-RS user could immediately attempt to perform a permitted action. You SHOULD NOT cache the list of available user actions returned because this endpoint gives the *current* actions for the *current* e-RS user, for the referral in context and is therefore, transient; a future call for a different e-RS user, referral, or at a different point in time, might result in a different set of actions, leading to potential failure flows. ## Supported security patterns - Healthcare worker, user-restricted access - Application-restricted, unattended access ## Pre-requisites ### Application-restricted, unattended 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 action: - Record Review Outcome - Cancel Referral ### Healthcare worker, 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: - `REFERRING_CLINICIAN` - `REFERRING_CLINICIAN_ADMIN` - `SERVICE_PROVIDER_CLINICIAN` - `SERVICE_PROVIDER_CLINICIAN_ADMIN` You should obtain a `Unique Booking Reference Number` (UBRN) before using this endpoint, as the current UBRN version is required. ## Use case As an authenticated user I want to know what actions I might currently perform on a referral prior to attempting to do so So that I can review my options, and do not try to persist a prohibited action ## Important information about using this endpoint This endpoint can be used to check permitted actions on a referral. Only a select number of results will be returned for which a corresponding action can be performed via the API. Not all actions are currently supported. As a referrer, the actions returned can include: - Cancel Directly Booked Appointment - Cancel Referral - Create Appointment - Change Shortlist - Change Shortlist and Send for Triage As a service provider, the actions returned can include: - Record Review Outcome - Cancel Referral ## Related endpoints To retrieve pertinent details relating to a referral: - Use [[HYPERLINK_A005]] to retrieve the details of the referral, UBRN and UBRN version. Below is a list of actions that could be returned by calling [[HYPERLINK_A029]] - Use [[HYPERLINK_A028]] to record a review outcome based on the available clinical information and attachments. - Use [[HYPERLINK_A016]] to Book, or if unable, Defer, an appointment to a specific service on the current shortlist, or to make a triage deferral by sending an appointment to a triage service. - Use [[HYPERLINK_A031]] to change the shortlist of bookable services on an existing referral. ## Sandbox test scenarios You can test the following scenarios in our sandbox environment | Scenario | Request | | --------------------------------------------------- | ---------------------------------------------------------------------------------------- | | No "action" is available | `focus`=`ReferralRequest/000000070000/_history/6`, `intent`=`proposal`, `status`=`ready` | | "Record Review Outcome" is available | `focus`=`ReferralRequest/000000070001/_history/6`, `intent`=`proposal`, `status`=`ready` | | "Create Appointment" is available | `focus`=`ReferralRequest/000000070002/_history/6`, `intent`=`proposal`, `status`=`ready` | | "Change Shortlist" is available | `focus`=`ReferralRequest/000000070003/_history/6`, `intent`=`proposal`, `status`=`ready` | | "Change Shortlist and Send for Triage" is available | `focus`=`ReferralRequest/000000070004/_history/6`, `intent`=`proposal`, `status`=`ready` | | "Cancel Referral" is available | `focus`=`ReferralRequest/000000070005/_history/6`, `intent`=`proposal`, `status`=`ready` | | "Cancel Directly Booked Appointment" is available | `focus`=`ReferralRequest/000000070006/_history/6`, `intent`=`proposal`, `status`=`ready` | ## Query parameters - `focus` string, required - `intent` 'proposal', required - `status` 'ready', required ## Headers - `Authorization` string, ^Bearer\ [[:ascii:]]+$, required - `NHSD-End-User-Organisation-ODS` string, required - `NHSD-eRS-Business-Function` 'REFERRING_CLINICIAN' | 'REFERRING_CLINICIAN_ADMIN' | 'REFERRING_ADMIN' | 'COMMISSIONER' | 'SERVICE_PROVIDER_CLINICIAN_ADMIN' | 'SERVICE_PROVIDER_CLINICIAN' | 'SERVICE_PROVIDER_ADMIN' | 'INFORMATION_ANALYST' | 'BOOKING_MANAGER' | 'ADDITIONAL_REQUIREMENTS_MANAGER', required - `NHSD-eRS-On-Behalf-Of-User-ID` string - `X-Correlation-ID` string ## Response `200` Bundle containing list of available tasks ## Other responses - `400` — Where status code 400 (Bad Request) 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 | | ---------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- | | INVALID_VALUE | The input provided does not conform to the expected data types and format. | | MISSING_PARAMETER | Indicates missing mandatory FHIR search parameter. | | HISTORY_NOT_SUPPORTED | Only the current version of the UBRN is permissible. | | REFERENCE_NOT_FOUND | A supplied reference could not be resolved to valid resource (e.g. a patient, clinician or an organisation). | - `401` — Where status code 401 (Unauthorised) 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. | issue.details.coding.code | issue.code | Coding System | Description | | ------------------------- | ---------- | ------------------------------------------------------------------ | ---------------------------------------------------------------------------------- | | NO_ACCESS | | [eRS Error Code](https://fhir.nhs.uk/CodeSystem/ers-error-codes) | The request could not be authenticated due to either no credentials being provided or the provided credentials no longer being valid. Callers receiving this code should reauthenticate. | - `403` — Where status code 403 (Forbidden) 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. | issue.details.coding.code | issue.code | Coding System | Description | | ------------------------- | ---------- | ------------------------------------------------------------------ | ---------------------------------------------------------------------------------- | | FORBIDDEN | forbidden | [eRS Error Code](https://fhir.nhs.uk/CodeSystem/ers-error-codes) | A call attempts to access or operate upon a resource without proper authorisation. | | NO_ACCESS | forbidden | [eRS Error Code](https://fhir.nhs.uk/CodeSystem/ers-error-codes) | The request could not be authenticated due to insufficient credentials being provided. | - `406` — Not Acceptable - `429` — The e-Referral service APIs limit the number of transactions you can make per unit of time. This protects our service against excessive use and denial-of-service (DoS) attacks, and is also to encourage you to use our APIs efficiently. Our standard rate limit for the production environment is 10 requests per second per application. If you go over the rate limit you'll receive a response with an HTTP status of 429 (Too Many Requests). Our path-to-live environments have very low rate limits. They are for functional testing only - you should not use them for [[HYPERLINK_PERFORMANCE_TESTING]]. If you have problems with rate limits, [[HYPERLINK_CONTACT_US]] to discuss your application design and volumetrics, and to see whether it's appropriate to raise your rate limit. If a 429 response is received, indicating a request has been rate limited, then you must back off and retry with exponentially increasing periods between requests. Once a request is successful again, then you may continue to send requests inline with the documented rate limits. Example: - Receive a 429 response - Wait 1s and resend, but still receive a 429 - Wait 2s and resend, but still receive a 429 - Wait 4s, request is successful - Return to normal request cadence - `500` — Internal Server Error - `503` — Where status code 503 (Service Unavailable) is returned then an eRS-OperationOutcome-1 will be included in the body, as detailed below. In response to receiving this status code, it is recommended that clients retry at a later time based on a returned `Retry-After` header when provided. | Error code | Description | | ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ | | SYSTEM_UNAVAILABLE | A request to an internal component timed out whilst attempting to serve a response or the system is currently otherwise unavailable. | --- [API](https://skmtc.net/nhs/apis/e-referrals-service-api.md) · [All operations](https://skmtc.net/nhs/apis/e-referrals-service-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/nhs/e-referrals-service-api/versions/916969ea472f/schema)