Retrieve appointment slots (A015, FHIR STU3)
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 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 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
A single service ID is required to indicate the service for which appointment slots are required.
The priority of the appointment slots.
The status of the appointment slots required must be supplied. This must indicate that 'free' slots are required.
The pageSize is the maximum number of results (i.e. slots) that should be returned by this call. This value must be in the range of 1-100. 100 is the maximum slots available per API call. Note: Page contents cannot be guaranteed to be contiguous with no gaps or duplicates since the availability of slots may change between calls to the API.
The number of the page required to be returned, starting at 1.
Slots in e-RS may be allocated to a clinician and is set in the service provider's PAS. If a named clinician is supplied (by the UUID), the appointment slots returned are constrained to slots for which this clinician is allocated to the appointment slot. The clinician must be a named clinician for the selected service.
An optional URL parameter to cause service/clinician information to be returned ('_include=Slot:schedule') is recognised (i.e. causes no error and is understood by e-RS) but e-RS will return a Schedule for each Slot whether this parameter is present or not.
Headers
The e-RS Business Function of the caller
To retrieve accurate slot information for a specific ReferralRequest the code from the ReferralRequest's 'Extension-eRS-Commissioning-Rule-Org-1' field should be passed to the slot search in this field otherwise slots which are, in fact, unbookable for that ReferralRequest may be returned
Parameters
Response
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.
Changes
No recorded changes to this endpoint across all 1 revision of this API.