Search for free slots within a date range at an organisation

Use case

This specification describes a single use case enabling the consumer to request from the targeted provider system slots matching the selected date range, booking organisation ODS Code and Type, and other parameters including UC Disposition Code and Service ID.

Refer to Consumer sessions illustrated for how this API use case could be used in the context of a typical consumer appointment management session.

Security

  • GP Connect utilises TLS Mutual Authentication for system level authorization
  • GP Connect utilises a JSON Web Tokens (JWT) to transmit clinical audit and provenance details

Search parameters

Provider systems SHALL support the following search parameters:

Name Type Description Paths
status token The free/busy status of the appointment Slot.status
start date or dateTime Slot start date, or date and time Slot.start
end date or dateTime Slot end date, or date and time Slot.end
searchFilter token A generic token to allow consumers to pass additional search criteria to the provider. (n/a)

_include parameters

Provider systems SHALL support the following include parameters:

Name Description Paths
_include=Slot:schedule Include Schedule resources referenced within the returned Slot Resources Slot.schedule
_include:recurse= Schedule:actor:Practitioner Include Practitioner resources referenced within the returned Schedule resources Schedule.actor:Practitioner
_include:recurse= Schedule:actor:Location Include Location resources referenced within the returned Schedule resources Schedule.actor:Location
_include:recurse= Location:managingOrganization Include Organization resources references from matching Location resources Location.managingOrganization

Consumer systems SHALL send the following parameters in the request:

  • The start parameter SHALL only be included once in the request.
  • The start parameter SHALL be supplied with the ge search prefix. For example, start=ge2017-09-22, which indicates that the consumer would like slots where the slot start date is on or after “2017-09-22”.
  • The end parameter SHALL only be included once in the request.
  • The end parameter SHALL be supplied with the le search prefix. For example, end=le2017-09-26, which indicates that the consumer would like slots where the slot end date is on or before “2017-09-26”.

    Diagram - Date range parameters

  • The start and end parameters SHALL contain a search prefix as specified above, and:
    • either, a date in the format yyyy-mm-dd. Partial dates are not allowed.
    • or, a dateTime in the format yyyy-mm-ddThh:mm:ss+hh:mm in (UK) local time, with the timezone offset +00:00 for UTC and +01:00 for BST.
  • status=free specifies that only free slots will be returned. Note: the slot status value of free SHALL be specified, other slot status values are not permitted.

  • _include=Slot:schedule specifies that associated Schedule resources are returned.

Consumer systems SHOULD send the following parameters in the request:

Consumer systems MAY send the following _include parameters in the request, to minimise the number of API calls required to prepare an appointment booking:

  • _include:recurse=Schedule:actor:Practitioner
  • _include:recurse=Schedule:actor:Location
  • _include:recurse=Location:managingOrganization

Enhanced slot filtering

In order for providers to return the appropriate slots for the consumer, the consumer SHOULD send in the following parameters using the searchFilter parameter using the token parameter format of system|code:

Parameter name Parameter value - system element Parameter value - code element
searchFilter https://fhir.nhs.uk/Id/ods-organization-code Consumer ODS organisation code, e.g. A11111
searchFilter https://fhir.nhs.uk/STU3/CodeSystem/GPConnect-OrganisationType-1 Consumer organisation type code from GPConnect-OrganisationType-1 valueset, e.g. urgent-care

Where search filters are sent by consumers which are not explicitly supported in this specification (for example, urgent care use a disposition code value set), providers who do not understand the additional parameters SHALL ignore them and SHALL NOT return an error.

Search for free slots on the wire

On the wire, a search for free slots request sending all parameters, and searching on date, would look something like the following:

GET /Slot?status=free&start=ge2017-10-20&end=le2017-10-31&_include=Slot:schedule&_include:recurse=Schedule:actor:Practitioner&_include:recurse=Schedule:actor:Location&_include:recurse=Location:managingOrganization&searchFilter=https://fhir.nhs.uk/STU3/CodeSystem/GPConnect-OrganisationType-1|gp-practice&searchFilter=https://fhir.nhs.uk/Id/ods-organization-code|A1001

A search for free slots request sending only mandatory and required parameters, and searching on date and time, would look something like the following:

GET /Slot?status=free&start=ge2019-03-29T12:00:00+00:00&end=le2019-04-01T17:00:00+01:00&_include=Slot:schedule&searchFilter=https://fhir.nhs.uk/STU3/CodeSystem/GPConnect-OrganisationType-1|gp-practice&searchFilter=https://fhir.nhs.uk/Id/ods-organization-code|A1001

Booking multiple adjacent slots

Please see the conditions in which a consumer may book multiple adjacent slots on the Book an appointment page.

Consumer display requirements

The fields below allow a patient to choose and attend an appointment appropriate to their needs.

In order to prevent incorrect or unsuitable bookings, and to allow a patient to attend the appointment at the correct time, place or via the correct delivery channel, consumer systems SHALL support the following fields:

  • Start date and time
  • End date and time, or duration
  • Delivery channel (in-person, telephone, video)
  • Slot type and schedule type (see Slot.serviceType and Schedule.serviceCategory)
  • Location name and address
  • Practitioner role (e.g. General Medical Practitioner, Nurse)
  • Practitioner name and gender

Prerequisites

Consumer

The consumer system:

  • SHALL have previously resolved the organisation’s FHIR endpoint base URL through the Spine Directory Service
  • SHALL request a maximum date range covering a two-week period

API usage

Request operation

FHIR relative request

GET /Slot?[start={search_prefix}start_date]
          [&end=[{search_prefix}end_date]
          [&status=free]
          [&_include=Slot:schedule]
          {&_include:recurse=Schedule:actor:Practitioner}
          {&_include:recurse=Schedule:actor:Location}
          {&_include:recurse=Location:managingOrganization}
          {&searchFilter={OrgTypeCodeSystem}|{OrgTypeCode}}
          {&searchFilter={OrgODSCodeSystem}|{OrgODSCode}}

FHIR absolute request

GET https://[proxy_server]/https://[provider_server]/[fhir_base]
          /Slot?[start={search_prefix}start_date]
          [&end=[{search_prefix}end_date]
          [&status=free]
          [&_include=Slot:schedule]
          {&_include:recurse=Schedule:actor:Practitioner}
          {&_include:recurse=Schedule:actor:Location}
          {&_include:recurse=Location:managingOrganization}
          {&searchFilter={OrgTypeCodeSystem}|{OrgTypeCode}}
          {&searchFilter={OrgODSCodeSystem}|{OrgODSCode}}

Request headers

Consumers SHALL include the following additional HTTP request headers:

Header Value
Ssp-TraceID Consumer’s TraceID (that is, GUID/UUID)
Ssp-From Consumer’s ASID
Ssp-To Provider’s ASID
Ssp-InteractionID urn:nhs:names:services:gpconnect:fhir:rest:search:slot-1

Payload request body

N/A

Error handling

The provider system SHALL return an error if:

  • the time period defined by start and end parameters is greater than a two week period
  • the status parameter is absent or is present with a value other than free
  • the _include=Slot:schedule is absent

SHALL return a GPConnect-OperationOutcome-1 resource that provides additional detail when one or more parameters are corrupt or a specific business rule/constraint is breached.

Refer to Error handling guidance for details of error codes.

Request response

Response headers

Provider systems are not expected to add any specific headers beyond that described in the HTTP and FHIR® standards.

Payload response body

Provider systems:

  • SHALL return a 200 OK HTTP status code on successful retrieval of free slot details

  • SHALL return resources conforming to the GP Connect profiled versions of the base FHIR resources listed on the Appointment Management resources page

  • SHALL return a Bundle of type searchset containing:

    • Slot resources for the organisation which:
      • have a status of free
      • and fall fully within the requested date range. That is, free slots which start before the start parameter and free slots which end after end search parameter SHALL NOT be returned.
      • and are bookable according to related defined embargo/booking window rules
      • and which match the search filter parameters of Booking Organisation (ODS Code) and/or organisation type, or are not restricted for booking by ODS code and/or organisation type
    • Schedule resources associated with the returned Slot resources

    • Practitioner resources associated to the returned Schedule resources, where available, and where requested by the consumer using the _include:recurse=Schedule:actor:Practitioner parameter

      • SHALL populate the Practitioner resource according to population requirements for Read a practitioner
    • Location resources associated with the returned Schedule resources, where requested by the consumer using the _include:recurse=Schedule:actor:Location parameter

      • The Location referenced from the Schedule resource SHALL represent the location of the surgery where the appointment will take place. Location.managingOrganization SHALL be populated. See Branch surgeries for more details.

      • SHALL populate the Location resource according to population requirements for Read a location

    • an Organization resource associated with the Location resources (via Location.managingOrganization) associated with the Schedule

      • This resource SHALL always be present, regardless of parameters, except where no slots are returned. Please see Known issues for more details.

      • Provider systems SHALL accept the _include:recurse=Location:managingOrganization parameter in the Search for free slots request without returning an error, however SHALL continue to return the Organization resource regardless of whether this is present

      • SHALL populate the Organization resource according to population requirements for Read an organization

  • If no free slots are returned for the requested time period then an empty response Bundle SHALL be returned

  • Only Schedule, Practitioner, Location and Organization resources SHALL be returned where they are associated with the Slot resources matching the query

  • SHALL populate Slot.start, Slot.end, Schedule.planningHorizon.start and Schedule.planningHorizon.end elements in (UK) local time in the format yyyy-mm-ddThh:mm:ss+hh:mm, with the timezone offset +00:00 for UTC and +01:00 for BST

  • SHALL populate Slot.serviceType.text with a practice defined slot type description, and where available Schedule.serviceCategory.text with a practice defined schedule type description (may be called session name or rota type). The slot and schedule description fields SHOULD be the same as those visible in the NHS App.

  • SHALL meet General FHIR resource population requirements populating all fields for Schedule and Slot where data is available, excluding those listed below

  • SHALL NOT populate the specialty field on Schedule or Slot

{
  "resourceType": "Bundle",
  "type": "searchset",
  "entry": [
    {
      "resource": {
        "resourceType": "Slot",
        "id": "1584",
        "meta": {
          "versionId": "1471219260000",
          "profile": [
            "https://fhir.nhs.uk/STU3/StructureDefinition/GPConnect-Slot-1"
          ]
        },
        "extension": [
          {
            "url": "https://fhir.nhs.uk/STU3/StructureDefinition/Extension-GPConnect-DeliveryChannel-2",
            "valueCode": "In-person"
          }
        ],
        "serviceType": [
          {
            "text": "General GP Appointment"
          }
        ],
        "schedule": {
          "reference": "Schedule/14"
        },
        "status": "free",
        "start": "2016-08-15T11:30:00+01:00",
        "end": "2016-08-15T11:40:00+01:00"
      }
    },
    {
      "resource": {
        "resourceType": "Slot",
        "id": "1644",
        "meta": {
          "versionId": "1471219260112",
          "profile": [
            "https://fhir.nhs.uk/STU3/StructureDefinition/GPConnect-Slot-1"
          ]
        },
        "extension": [
          {
            "url": "https://fhir.nhs.uk/STU3/StructureDefinition/Extension-GPConnect-DeliveryChannel-2",
            "valueCode": "In-person"
          }
        ],
        "serviceType": [
          {
            "text": "NHS Health Check"
          }
        ],
        "schedule": {
          "reference": "Schedule/14"
        },
        "status": "free",
        "start": "2016-08-15T11:40:00+01:00",
        "end": "2016-08-15T11:50:00+01:00"
      }
    },
    {
      "resource": {
        "resourceType": "Schedule",
        "id": "14",
        "meta": {
          "versionId": "1469444400000",
          "profile": [
            "https://fhir.nhs.uk/STU3/StructureDefinition/GPConnect-Schedule-1"
          ]
        },
        "extension": [
          {
            "url": "https://fhir.nhs.uk/STU3/StructureDefinition/Extension-GPConnect-PractitionerRole-1",
            "valueCodeableConcept": {
              "coding": [
                {
                  "system": "https://fhir.nhs.uk/STU3/CodeSystem/CareConnect-SDSJobRoleName-1",
                  "code": "R0260",
                  "display": "General Medical Practitioner"
                }
              ]
            }
          }
        ],
        "serviceCategory": {
          "text": "General GP Appointments"
        },
        "actor": [
          {
            "reference": "Location/17"
          },
          {
            "reference": "Practitioner/2"
          }
        ],
        "planningHorizon": {
          "start": "2016-08-15T09:00:00+01:00",
          "end": "2016-08-15T12:00:00+01:00"
        }
      }
    },
    {
      "resource": {
        "resourceType": "Practitioner",
        "id": "2",
        "meta": {
          "versionId": "636064088099800115",
          "profile": [
            "https://fhir.nhs.uk/STU3/StructureDefinition/CareConnect-GPC-Practitioner-1"
          ]
        },
        "identifier": [
          {
            "system": "https://fhir.nhs.uk/Id/sds-user-id",
            "value": "111122223333"
          }
        ],
        "name": [
          {
            "family": "Black",
            "given": [
              "Sarah"
            ],
            "prefix": [
              "Mrs"
            ]
          }
        ],
        "gender": "female"
      }
    },
    {
      "resource": {
        "resourceType": "Location",
        "id": "17",
        "meta": {
          "versionId": "636064088100870233",
          "profile": [
            "https://fhir.nhs.uk/STU3/StructureDefinition/CareConnect-GPC-Location-1"
          ]
        },
        "name": "The Trevelyan Practice",
        "address": {
          "line": [
            "Trevelyan Square",
            "Boar Ln",
            "Leeds"
          ],
          "postalCode": "LS1 6AE"
        },
        "telecom": {
          "system": "phone",
          "value": "03003035678",
          "use": "work"
        },
        "managingOrganization": {
          "reference": "Organization/23"
        }
      }
    },
    {
      "resource": {
        "resourceType": "Organization",
        "id": "23",
        "meta": {
          "versionId": "636064088098730113",
          "profile": [
            "https://fhir.nhs.uk/STU3/StructureDefinition/CareConnect-GPC-Organization-1"
          ]
        },
        "identifier": [
          {
            "system": "https://fhir.nhs.uk/Id/ods-organization-code",
            "value": "A00001"
          }
        ],
        "name": "The Trevelyan Practice",
        "address": {
          "line": [
            "Trevelyan Square",
            "Boar Ln"
          ],
          "city": "Leeds",
          "district": "West Yorkshire",
          "postalCode": "LS1 6AE"
        },
        "telecom": {
          "system": "phone",
          "value": "03003035678",
          "use": "work"
        }
      }
    }
  ]
}