Search loading...

API Hub

Explore and Make use of Nationally Defined Messaging APIs

 

A015: Retrieve Appointment Slots

Status: Live

Description

This API aims to make available e-RS functionality which will allow the retrieval of appointment slots for a single service. By retrieving appointment slots, subsequent APIs are supported in terms of appointment booking or deferring to a provider.

The implementation to expose slots uses the “NHS Scheduling” FHIR model and is standard across all NHS systems. Further information on the scheduling resource can be found here:

https://developer.nhs.uk/apis/nhsscheduling-1.0.6-alpha/resources_overview.html

Resource URL

Method URL Authentication
GET {Base URL}/STU3/v1/Slot Session Token (Details)
  • {Base URL} (Dev1) = https://api.dev1.ers.ncrs.nhs.uk/ers-api

Structure Definition

Prerequisite Conditions

  • The user is authenticated with an effective business function of Referring Clinician or Referring Clinician Admin
  • The user has created a referral and shortlisted one or more bookable services via A011: Create Referral
  • The Service Search Criteria and shortlisted services used to retrieve appointments should be the same as that saved against the referral. This is to ensure only appropriate appointments are offered to the user, and any booking and defer to provider rejections later are minimised
    • Note: A Supplier should be able to obtain the current service search criteria and shortlisted services via A005 Retrieve Referral

INPUT

Request Operation: Header

Field Name Value
XAPI_ASID The “Accredited System ID” issued to the third party
HTTP_X_SESSION_KEY The session key generated by the Authentication and Authorisation APIs
X-ERS-XAPI-COMM-RULE-ORG The ODS code of the NHS organisation which has commissioned the service.

This value must be supplied if searching for appointment slots for a service so that commissioned rules can be considered as part of the search parameters. This ensures that slots are returned within the commissioning contract period, available to be booked.

If no code is supplied and commissioning rules apply, appointment slots may still be returned but subsequent steps to book will fail.

The rule context organisation is included in the returned FHIR ReferralRequest via A005: Retrieve Referral Request

Request Operation: Parameters

Name FHIR Parameter Cardinality Type Description
serviceID schedule.actor:HealthcareService 0..1 Number A single service ID is required to indicate the service for which appointment slots are required
namedClinician schedule.actor:Practitioner 0..0 Number 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.
priority appointmentType 0..1 Coding Optional priority change - eRS-Priority-1
status status 0..1 String The status of the appointment slots required must be supplied. This must indicate that “free” slots are required
pageSize _count 0..1 Number 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.
pageNumber page 0..1 Number The pageNumber is the number of pages required to be returned, starting at 1.

Example Request

http://[FHIR base URL]/Slot
?schedule.actor:HealthcareService=700369
&schedule.actor:Practitioner=031710555510
&appointmentType=ROUTINE
&_count=100
&page=3
&status=free
&_include=Slot:schedule

OUTPUT

Response: Success

On success (when at least one slot has been found), a FHIR Bundle resource is returned. The API will supply slots from the earliest available appointment date/time up to a configurable value. In the (valid) scenario where no slots are found, an empty bundle will be returned, at which point a user can select to defer to the provider via A017: Defer Booking to Provider.

If slots are found, the Reference to a Slot can be passed to A016: Book Appointment to book an appointment.

Further details of the FHIR representation can be found with the example response below.

The Slot 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.

Paging

Link fields at the start of the Response support paging of results by providing the URL that should be used in further calls to obtain the ‘previous’ or ‘next’ pages of Slots.

Additional Notes

  • The ‘id’ of the Bundle is auto-generated randomly on each Bundle. Bundles cannot be retrieved independently (i.e. e-RS does not support a ‘GET’ for a Bundle independently of a search)
  • The ‘meta.lastUpdated’ field contains the date/time when the Bundle is generated
  • The ‘type’ field is always value “searchset”
  • The ‘link’ array will always contain the ‘self’ field and may contain ‘previous’ and ‘next’ fields
  • The ‘previous’ field is present if the page being retrieved is not page 1.
  • The ‘next’ field is present if there are further slots available in the next page after the last slot in the page being retrieved
  • The ‘self’ field contains the search parameters from the URL that were used for the search in its ‘url’ field. If parameters were present in the URL but not recognised, they are omitted from the ‘url’ field. Parameter ‘&_include=Slot:schedule’ is always included in the ‘url’ field value whether it was present in the search parameters or not
  • The ‘url’ fields for ‘previous’ and ‘next’ (if present) should have the same parameters except for the ‘page’ value which should have a value one less or one more respectively as a current page
  • The ‘entry’ array is the standard FHIR way of conveying the search results, each entry is either a ‘Slot’ resourceType or a ‘Schedule’ resourceType.
  • For a Slot:
    • has a ‘fullUrl’ field which is standard FHIR and is mandatory for a searchset. The value identifies a Slot resource where the Id of the Slot is the internal Id of the Slot within e-RS
    • has an ‘id’ field containing the same id as in the ‘fullUrl’
    • has a ‘meta.profile’ field with the CareConnect profile as shown
    • has an ‘identifier’ field as shown that contains the USRN value received from the PAS
    • has a reference to the ‘schedule’ for the Slot. The Schedule resource is in the same Bundle and its id is composed of the Service Id followed by, if the Slot has an Allocated Clinician, a hyphen and the Allocated Clinician’s UUID
    • has a ‘status’ field which will always have a value of ‘free’
    • has a ‘start’ field containing the start date and time of the Slot. This includes a timezone offset of 00:00 indicating UTC
    • has a ‘end’ field containing the end date and time of the Slot. This includes a timezone offset of 00:00 indicating UTC
    • has a ‘search.mode’ field which is standard FHIR with a value of ‘match’
  • For a Schedule:
    - has a ‘fullUrl’ field which is standard FHIR and is mandatory for a searchset. The value identifies a Schedule resource where the Id of the Schedule is composed of the Service Id followed by, if the Schedule relates to an Allocated Clinician, a hyphen and the Allocated Clinician’s UUID - has an ‘id’ field containing the same id as in the ‘fullUrl’ - has a ‘meta.profile’ field with the CareConnect profile as shown - has an ‘identifier’ field as shown that contains the same value as the ‘id’ field - has one or two ‘actor’ fields thus: - always has an ‘actor’ field that contains the identifier of the e-RS Service to which the Schedule relates. This will be the same as the Service for whose slots are being searched - may have an ‘actor’ for an Allocated Clinician if the Schedule relates to slots for that Allocated Clinician. The Clinician is identified by SDS User Id (i.e. the UUID) - has a ‘search.mode’ field which is standard FHIR with a value of ‘include’

Example Response

Response: Failure

If an error occurs, the relating HTTP status code will be returned in the header.

Where status code 422 (Unprocessable Entity) is returned then an eRS-OperationOutcome-1 will be included in the body, as detailed below:

OutcomeKey Description Suggested Diagnostic
NO_SUCH_SERVICE No service exists or has ever existed for this service ID Check the service ID via A010: Patient Service Search
SERVICE_UNAVAILABLE The service is no longer available in the directory of services (DoS) within e-RS, “Service no longer available” message is returned The service must be active, published and within its effective date range. Check the service ID via A010: Patient Service Search
INVALID_STATE The selected service does not support an appointment request, “Unbookable service” message is returned The service must support an appointment request, i.e. not be a triage service
INVALID_STATE The selected service does not support an appointment request, “Service is not directly bookable” message is returned The service must be bookable, i.e. a Directly Bookable Service (DBS)
INVALID_CODE The slot status parameter value is not valid, “Invalid status code” message is returned Select a valid code from those listed in valueset-slotstatus
INVALID_VALUE The slot status parameter is not ‘free’, “Requested status is not supported” message is returned The slot status parameter must be ‘free’
INVALID_VALUE The pageSize (FHIR ‘_count’) parameter is not valid, “Invalid page size” message is returned The pageSize parameter cannot be less than 1 or higher than 100
INVALID_VALUE The pageNumber (FHIR ‘page’) parameter is not valid, “Invalid page number” message is returned The pageNumber parameter must be an integer, and have a value more than 1, or higher than the last page available. If no slots match and the requested page number is 1, no error is returned. Instead, an empty bundle is returned
INVALID_VALUE The named clinician (FHIR ‘schedule.actor:Practitioner’) parameter is not valid, “Invalid practitioner for service” message is returned The professional user must exist, be active, and be a named clinician at the selected service
MISSING_PARAMETER The Commissioning Rule Organisation parameter (via the HTTP header field) is not present, “No commissioning rule org parameter” message is returned. The Rule Context Organisation (as the “Commissioning Rule Org”) applies if the service is on the primary care menu and must be present for all cases
INVALID_VALUE The Commissioning Rule Organisation parameter (via the HTTP header field) is not valid, “Commissioning Rule Organisation is not a referring organisation” message is returned The Commissioning Rule Organisation ODS code must be recognised as an active referring organisation. e-RS organisation types such as referring organisation are mapped from SDS organisation types

All content is available under the Open Government Licence v3.0, except where otherwise stated