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 thege
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 thele
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”. -
status=free
specifies that only free slots will be returned. Note: the slot status value offree
SHALL be specified, other slot status values are not permitted. _include=Slot:schedule
specifies that associatedSchedule
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
andend
parameters is greater than a two week period - the
status
parameter is absent or is present with a value other thanfree
- 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 typesearchset
containing:Slot
resources for the organisation which:- have a
status
offree
- and fall fully within the requested date range. That is, free slots which start before the
start
parameter and free slots which end afterend
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
- have a
-
Schedule
resources associated with the returnedSlot
resources -
Practitioner
resources associated to the returnedSchedule
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
- SHALL populate the
-
Location
resources associated with the returnedSchedule
resources, where requested by the consumer using the_include:recurse=Schedule:actor:Location
parameter-
The
Location
referenced from theSchedule
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 theLocation
resources (viaLocation.managingOrganization
) associated with theSchedule
-
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 theOrganization
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
andOrganization
resources SHALL be returned where they are are associated with theSlot
resources matching the query -
SHALL meet General FHIR resource population requirements populating all fields for
Schedule
andSlot
where data is available, excluding those listed below -
SHALL NOT populate the
specialty
field onSchedule
orSlot
{
"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));