diff --git a/CHANGELOG.md b/CHANGELOG.md
index f1dfeaff2..41bc49b6e 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -1,4 +1,7 @@
# Changelog
-
-## {{ ansible_date_time.date }}
-* Initial commit
+## 15/09/2026
+* A015 (Retrieve Appointment Slots): documented support for `SERVICE_PROVIDER_CLINICIAN` and `SERVICE_PROVIDER_CLINICIAN_ADMIN` roles.
+* A015 - Enhanced ErrorOutcome.yaml with comprehensive error code documentation for retrieveAppointmentSlots
+ - Documented error conditions for referral state validation (NOT_BOOKED, TRIAGE service checks)
+ - Added response headers: X-Correlation-ID, X-Request-ID, Content-Type
+ - Configured FHIR JSON error response schema with STU3-OperationOutcome reference
diff --git a/sandbox/src/routes/stu3/retrieveAppointmentSlots.js b/sandbox/src/routes/stu3/retrieveAppointmentSlots.js
index 84e98f886..67d48ed9f 100644
--- a/sandbox/src/routes/stu3/retrieveAppointmentSlots.js
+++ b/sandbox/src/routes/stu3/retrieveAppointmentSlots.js
@@ -10,7 +10,7 @@ module.exports = [
path: '/FHIR/STU3/Slot',
handler: (request, h) => {
- const allowedBusinessFunctions = ["REFERRING_CLINICIAN", "REFERRING_CLINICIAN_ADMIN"]
+ const allowedBusinessFunctions = ["REFERRING_CLINICIAN", "REFERRING_CLINICIAN_ADMIN", "SERVICE_PROVIDER_CLINICIAN", "SERVICE_PROVIDER_CLINICIAN_ADMIN"]
const validationResult = validationUtils.validateBusinessFunction(request, h, allowedBusinessFunctions)
if (validationResult) {
diff --git a/specification/components/stu3/schemas/endpoints/a015-retrieve-appointment-slots.yaml b/specification/components/stu3/schemas/endpoints/a015-retrieve-appointment-slots.yaml
index 8703217b2..59b9d9642 100644
--- a/specification/components/stu3/schemas/endpoints/a015-retrieve-appointment-slots.yaml
+++ b/specification/components/stu3/schemas/endpoints/a015-retrieve-appointment-slots.yaml
@@ -4,6 +4,12 @@ description: |
## Overview
Use this endpoint to retrieve available appointment slots for a service.
+ Service provider clinicians can also use this endpoint, but only to retrieve slots for the purpose of redirecting a referral to another directly bookable service. This is only permitted when all of the following conditions are met:
+ - the referral's current holding service is of type `TRIAGE`
+ - the referral is in the `NOT_BOOKED` state
+ - the requested service is of type `APPOINTMENT`
+ - the user has a Legitimate Relationship with the referral
+
## Supported security patterns
- Healthcare worker, user-restricted access
@@ -11,9 +17,15 @@ description: |
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`
+
+ If using the `SERVICE_PROVIDER_CLINICIAN` or `SERVICE_PROVIDER_CLINICIAN_ADMIN` role, this endpoint is only usable under the narrow conditions described in the Overview above (referral redirection from a `TRIAGE` holding service, referral in `NOT_BOOKED` state, requested service of type `APPOINTMENT`, and an existing Legitimate Relationship with the referral). Outside of these conditions, calls from these roles will be rejected.
You need to have identified a directly bookable `service` that is on the current referral shortlist. You can do this by using [[HYPERLINK_A005]].
+ The `NHSD-eRS-Business-Function` header must be set to a role that is permitted to call this endpoint - `REFERRING_CLINICIAN`, `REFERRING_CLINICIAN_ADMIN`, `SERVICE_PROVIDER_CLINICIAN`, or `SERVICE_PROVIDER_CLINICIAN_ADMIN` are all now accepted, subject to the conditions above for the service provider roles.
+
## Use case
As an authenticated user
@@ -22,6 +34,12 @@ description: |
So that I can offer them to the patient for booking.
+ As a service provider clinician (`SERVICE_PROVIDER_CLINICIAN`/`SERVICE_PROVIDER_CLINICIAN_ADMIN`)
+
+ I need to retrieve a list of available appointment slots for a service while a referral is held in `TRIAGE` and not yet booked
+
+ So that I can redirect the referral to a suitable directly bookable service and book an appointment via [[HYPERLINK_A016]].
+
## Important note
You need to provide the 'commissioning rule organisation' when calling [[HYPERLINK_A015]] to ensure only suitable slots are returned. You can obtain the 'commissioning rule organisation' from [[HYPERLINK_A005]].
@@ -38,6 +56,8 @@ description: |
- when trying to book an appointment into a service, the slot advertised is no longer available
- when trying to book an appointment into a service, no response is received within message timeout period (currently 2 minutes)
+ Service provider clinicians (`SERVICE_PROVIDER_CLINICIAN`/`SERVICE_PROVIDER_CLINICIAN_ADMIN`) use [[HYPERLINK_A015]] as part of the referral redirection workflow: retrieving slots for a suitable service before booking the redirected referral using [[HYPERLINK_A016]].
+
## Known Issues
This endpoint is using the :Practitioner search parameter. The "schedule.actor" search parameter is incorrectly using the ":Practitioner" modifier. As per the [FHIR standard](https://hl7.org/fhir/R4/) the ":identifier" modifier should be used when searching to indicate that an Identifer is used rather than a literal, relative, internal or absolute reference. See our [problems and fixes](https://digital.nhs.uk/services/e-referral-service/api/updates-and-releases/problems-and-fixes) section for more information.
@@ -65,6 +85,7 @@ parameters:
- $ref: '../headers/request/BusinessFunction.yaml'
- $ref: '../headers/request/CorrelationID.yaml'
- $ref: '../headers/request/ErsCommRuleOrg.yaml'
+ - $ref: '../headers/request/OnBehalfOfUserID.yaml'
- $ref: '../queryParameters/ServiceId.yaml'
- $ref: '../queryParameters/Priority.yaml'
- $ref: '../queryParameters/Status.yaml'
diff --git a/specification/components/stu3/schemas/responses/retrieveAppointmentSlots/ErrorOutcome.yaml b/specification/components/stu3/schemas/responses/retrieveAppointmentSlots/ErrorOutcome.yaml
index 03b3bbff6..77a8ab800 100644
--- a/specification/components/stu3/schemas/responses/retrieveAppointmentSlots/ErrorOutcome.yaml
+++ b/specification/components/stu3/schemas/responses/retrieveAppointmentSlots/ErrorOutcome.yaml
@@ -9,7 +9,7 @@ description: |
| INVALID_CODE | The input provided for a field is not one of the defined legal values. |
| MISSING_PARAMETER | Indicates missing mandatory FHIR search parameter. |
| MISSING_HEADER | Indicates missing mandatory HTTP header. |
- | INVALID_STATE | Indicates that the referenced item is not in the correct state for the request to be processed. |
+ | INVALID_STATE | Indicates that the referenced item is not in the correct state for the request to be processed. This applies when:
- the referral is not in the `NOT_BOOKED` state;
- (`SERVICE_PROVIDER_CLINICIAN`/`SERVICE_PROVIDER_CLINICIAN_ADMIN` only) the referral's current holding service is not of type `TRIAGE`. |
| SERVICE_UNAVAILABLE | Indicates that a service is no longer available. |
headers:
X-Correlation-ID:
diff --git a/tests/sandbox/stu3/test_a015_get_appointment_slots.py b/tests/sandbox/stu3/test_a015_get_appointment_slots.py
index c2c11a266..a7e1ca690 100644
--- a/tests/sandbox/stu3/test_a015_get_appointment_slots.py
+++ b/tests/sandbox/stu3/test_a015_get_appointment_slots.py
@@ -14,6 +14,8 @@ class TestGetAdviceAndGuidanceConversation(SandboxTest):
allowed_business_function_data = [
"REFERRING_CLINICIAN",
"REFERRING_CLINICIAN_ADMIN",
+ "SERVICE_PROVIDER_CLINICIAN",
+ "SERVICE_PROVIDER_CLINICIAN_ADMIN",
]
authorised_actor_data = Actor.all(