Search loading...

API Hub

Explore and Make use of Nationally Defined Messaging APIs

 

Search for free slots

Use case for searching for free slots within a date range

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 Slot start date/time. Slot.start
end date Slot end date/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

The following parameters SHALL be included 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

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

The following parameters MAY be included to minimise the number of API calls required to prepare an appointment booking:

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

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 with both system and code elements of the search token:

Parameter system Parameter code
https://fhir.nhs.uk/Id/ods-organization-code The booking (consumer) organisation ODS code, e.g. A11111
https://fhir.nhs.uk/STU3/CodeSystem/GPConnect-OrganisationType-1 The booking (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 would look something like one of the following:

GET /Slot?start=ge2017-10-20T00:00:00&end=le2017-10-31T23:59:59&status=free&_include=Slot:schedule&_include:recurse=Schedule:actor:Practitioner&_include:recurse=Schedule:actor:Location&searchFilter={OrgTypeCodeSystem}|{OrgTypeCode}&searchFilter={OrgODSCodeSystem}|{OrgODSCode}
GET /Slot?start=ge2017-10-20T00:00:00&end=le2017-10-31T23:59:59&status=free&_include=Slot:schedule&searchFilter={OrgTypeCodeSystem}|{OrgTypeCode}&searchFilter={OrgODSCodeSystem}|{OrgODSCode}

Booking multiple adjacent slots

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

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}
          {&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}
          {&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 an 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.

        • Consumer systems SHALL NOT send the _include:recurse=Location:managingOrganization parameter at the current time. Please see Known issues for more details.

      • 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 are associated with the Slot resources matching the query

  • 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": [
    {
      "fullUrl": "Slot/1584",
      "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"
          }
        ],
        "schedule": {
          "reference": "Schedule/14"
        },
        "status": "free",
        "start": "2016-08-15T11:30:00.000+01:00",
        "end": "2016-08-15T11:59:59.000+01:00"
      }
    },
    {
      "fullUrl": "Slot/1644",
      "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"
          }
        ],
        "schedule": {
          "reference": "Schedule/14"
        },
        "status": "free",
        "start": "2016-08-15T12:00:00.000+01:00",
        "end": "2016-08-15T12:29:59.000+01:00"
      }
    },
    {
      "fullUrl": "Schedule/14",
      "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"
                }
              ]
            }
          }
        ],
        "actor": [
          {
            "reference": "Location/17"
          },
          {
            "reference": "Practitioner/2"
          }
        ],
        "comment": "Schedule 1 for general appointments"
      }
    },
    {
      "fullUrl": "Practitioner/2",
      "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": "S001"
          }
        ],
        "name": {
          "family": [ "Black" ],
          "given": [ "Sarah" ],
          "prefix": [ "Mrs" ]
        },
        "gender": "female"
      }
    },
    {
      "fullUrl": "Location/17",
      "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/14"
        }
      }
    },
    {
      "fullUrl": "Organization/14",
      "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": "O001"
          }
        ],
        "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"
        }
      }
    }
  ]
}

Examples

C#

var client = new FhirClient("http://gpconnect.aprovider.nhs.net/GP001/STU3/1/");
client.PreferredFormat = ResourceFormat.Json;

[ to add ]

FhirSerializer.SerializeResourceToJson(resource).Dump();

Java

FhirContext ctx = FhirContext.forStu3();
IGenericClient client = ctx.newRestfulGenericClient("http://gpconnect.aprovider.nhs.net/GP001/STU3/1");

[ to add ]

System.out.println(ctx.newJsonParser().setPrettyPrint(true).encodeResourceToString(responseBundle));
Tags: appointments

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