--- title: "Retrieve appointment slots (A015, FHIR STU3)" method: GET path: "/STU3/Slot" tags: ["Arrange appointment"] --- # Retrieve appointment slots (A015, FHIR STU3) `GET /STU3/Slot` ## Overview Use this endpoint to retrieve available appointment slots for a service. ## 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: - `REFERRING_CLINICIAN` - `REFERRING_CLINICIAN_ADMIN` You need to have identified a directly bookable `service` that is on the current referral shortlist. You can do this by using [[HYPERLINK_A005]]. ## Use case As an authenticated user I need to retrieve a list of available appointment slots for a service So that I can offer them to the patient for booking. ## 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]]. When slots are retrieved using this endpoint, they can include slots with or without a named clinician associated with them. Your integrated application must support both scenarios. Slots with a named clinician will have an additional "actor" which defines the SDS User ID of the clinician, this will be on the Schedule associated to the Slot. ## Related endpoints You can book an appointment to an available slot using [[HYPERLINK_A016]]. You can defer booking to a directly bookable service using [[HYPERLINK_A016]] but only in the following circumstances: - when the service has no available slots - 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) ## 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. ## Sandbox test scenarios You can test the following scenarios in our sandbox environment: | Scenario | Request Query Parameters | Response | | -------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------- | | Minimum slot search | `schedule.actor:HealthcareService`=`12000`, `appointmentType`=`ROUTINE`, `_count`=`20`, `status`=`free`, `page`=`1` | Illustrates minimum usage/parameters with concise, minimal response. | | Empty slot search response | `schedule.actor:HealthcareService`=`10000`, `appointmentType`=`ROUTINE`, `_count`=`20`, `status`=`free`, `page`=`1` | Illustrates how a 'no slots' response appears. | | Multipage slot search (page 1) | `schedule.actor:HealthcareService`=`11000`, `appointmentType`=`ROUTINE`, `_count`=`5`, `status`=`free`, `page`=`1` | Illustrates first page of multi-page response. | | Multipage slot search (page 2) | `schedule.actor:HealthcareService`=`11000`, `appointmentType`=`ROUTINE`, `_count`=`5`, `status`=`free`, `page`=`2` | Illustrates second page of multi-page response. | | Multipage slot search (invalid page 5) | `schedule.actor:HealthcareService`=`11000`, `appointmentType`=`ROUTINE`, `_count`=`5`, `status`=`free`, `page`=`5` | Illustrates error when page is outside of valid range. | | Multi schedule response | `schedule.actor:HealthcareService`=`13000`, `appointmentType`=`ROUTINE`, `_count`=`5`, `status`=`free`, `page`=`1` | Illustrates response when there is >1 Schedule: one Schedule is for slots with no associated clinician and the other does have an associated clinician. | | Slot clinician search | `schedule.actor:HealthcareService`=`14000`, `schedule.actor:Practitioner`=`921600556514`, `appointmentType`=`ROUTINE`, `_count`=`5`, `status`=`free`, `page`=`1` | Illustrates search for clinician-specific slots | ## Query parameters - `schedule.actor:HealthcareService` string, required - `appointmentType` 'ROUTINE' | 'URGENT' | 'TWO_WEEK_WAIT', required - `status` 'free', required - `_count` integer, required - `page` integer, required - `schedule.actor:Practitioner` string - `_include` string ## Headers - `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-Comm-Rule-Org` string, required ## Parameters - `#/paths/~1STU3~1Task/get/parameters/0` — unresolved $ref - `#/paths/~1STU3~1Task/get/parameters/1` — unresolved $ref - `#/paths/~1STU3~1Task/get/parameters/4` — unresolved $ref ## Response `200` The Response contains a FHIR 'Bundle' that, in turn, contains 'Slot' resources where each 'Slot' resource includes the 'Reference' to the slot and the slot's 'start' and 'end' times. The Response Bundle also contains one or more 'Schedule' resources each of which is used to indicate which allocated clinician a Slot is associated with (if any). The 'Schedule' also indicates the Service Id that will be the same Service for which the Slot search was performed. ## 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 | | ---------------------------------- | ----------------------------------------------------------------------------------------------------------------------- | | REFERENCE_NOT_FOUND | A supplied reference could not be resolved to valid resource (e.g. a patient, clinician or an organisation). | | 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. | | 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. | | SERVICE_UNAVAILABLE | Indicates that a service is no longer available. | - `401` — unresolved $ref - `403` — unresolved $ref - `406` — unresolved $ref - `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)