Status:

This endpoint has been deprecated, meaning you should not use it for new integrations.

Instead, please use our newer e-RS FHIR API solution which is documented here: https://digital.nhs.uk/developer/api-catalogue/e-referral-service-fhir

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

• {Base URL} (Dev1) = https://api.dev1.ers.ncrs.nhs.uk/ers-api

Structure Definition

• eRS-Appointment-1

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

Request Operation: Parameters

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

• 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: