Search loading...

API Hub

Explore and Make use of Nationally Defined Messaging APIs

 

Search for free slots

Details the Search for free slots interaction

Use case

A consuming system requests available slots from a provider system matching the selected date/time range and for a specific service.

Security

  • Utilises a JSON Web Token (JWT) to transmit Consumer system identity and authorisation details.
  • Is routed through the SSP (Spine secure Proxy)
  • Utilises TLS Mutual Authentication for system level authentication.

Search parameters

Servers MUST support the following search parameters that MAY be passed to the API. In some use cases clients may not be able to support the complete parameter list, so may omit unsupported parameters (so Servers must cater for parameters not being present).

Name Type Description Paths
service token The appropriate service id of the service for which Slots are being requested schedule.actor:healthcareservice
status token The free/busy status of the slots status
start dateTime Slot start date/time. A dateTime or Instant in the format yyyy-mm-ddThh:mm:ss+hh:mm. start
start dateTime Slot start date/time. A dateTime or Instant in the format yyyy-mm-ddThh:mm:ss+hh:mm. start

NB start is included twice to allow for the definition of the start and end of ‘The time window within which Slots must start’. Additional query parameters MAY be used. However, if these are not supported by the Server, they SHOULD be ignored.

_include parameters

Provider systems MUST support the following include parameters. However, if a resource is not supported, then only supported resources MUST be returned, rather than an error:

Name Description Paths
&_include=Slot:schedule Include Schedule Resources referenced within the returned Slot Resources Slot.schedule
&_include=Schedule:actor:Practitioner Include Practitioner Resources referenced within the returned Schedule Resources Schedule:actor:Practitioner
&_include=Schedule:actor:PractitionerRole Include Practitioner Role Resources referenced within the returned Schedule Resources Schedule:actor:PractitionerRole
&_include=Schedule:actor:HealthcareService Include HealthcareService Resources referenced within the returned Schedule Resources Schedule:actor:HealthcareService
&_include=HealthcareService.providedBy Include Organization Resources referenced within the returned HealthcareService Resources HealthcareService.providedBy
&_include=HealthcareService.location Include Location Resources referenced within the returned HealthcareService Resources HealthcareService.location

RESTful Query

The request body is sent using an http GET method.

The following query demonstrates a full request for information:

http://[FHIR base URL]/Slot
?schedule.actor:healthcareservice=918999198999
&start=ge2019-05-09T10:00:00+00:00
&start=le2019-05-09T10:30:00+00:00
&status=free
&_include=Slot:schedule
&_include=Schedule:actor:Practitioner
&_include=Schedule:actor:PractitionerRole
&_include=Schedule:actor:HealthcareService
&_include=HealthcareService.location
&_format=json

Response

Success

Provider systems:

  • MUST return a 200 OK HTTP status code on successful retrieval of “free” slot details.
  • MUST include the Slot resources which meet the requested criteria.
  • MAY implement paging as described here to limit the number of resources returned.
  • MAY implement an upper limit on returned Slots that excludes Slots which would fall into the requested time window.

The response Bundle MUST only contain resources related to the returned Slot resources. If no free slots are returned then no resources SHOULD be returned within the response Bundle. Related resources SHOULD NOT be duplicated (where for example they are related to multiple Slots).

Failure

Provider systems:

  • If the request fails because either no valid JWT is supplied or the supplied JWT failed validation, the response MUST include a status of 403 Forbidden. This MUST be accompanied by an OperationOutcome resource providing additional detail.

  • If the request fails because the query string parameters were invalid or unsupported, the response MUST include a status of 400 Bad Request.
  • If the request fails because of a server error, the response MUST include a status of 500 Internal Server Error.

Failure responses with a 4xx status SHOULD NOT be retried without taking steps to address the underlying cause of the failure.

Failure responses with a 500 status MAY be retried.

Sample response

{
    "resourceType": "Bundle",
    "id": "a56382a1-dce2-483a-8426-65b727b66809",
    "meta": {
        "lastUpdated": "2019-05-09T09:26:12.010+00:00"
    },
    "type": "searchset",
    "total": 8,
    "link":  [
        {
            "relation": "self",
            "url": "http://a2sibookingprovidertest.directoryofservices.nhs.uk:443/poc/Slot?_format=json&_include=Slot%3Aschedule&_include=Schedule%3Aactor%3APractitioner&_include=Schedule%3Aactor%3APractitionerRole&_include=Schedule%3Aactor%3AHealthcareService&_include=HealthcareService.location&schedule.actor%3Ahealthcareservice=918999198999&start=ge2019-05-09T10%3A00%3A00%2000%3A00&start=le2019-05-09T10%3A30%3A00%2000%3A00&status=free"
        }
    ],
    "entry":  [
        {
            "fullUrl": "http://a2sibookingprovidertest.directoryofservices.nhs.uk:443/poc/Slot/slot005",
            "resource": {
                "resourceType": "Slot",
                "id": "slot005",
                "meta": {
                    "profile":  [
                        "https://fhir.hl7.org.uk/STU3/StructureDefinition/CareConnect-Slot-1"
                    ]
                },
                "identifier":  [
                    {
                        "system": "https://tools.ietf.org/html/rfc4122",
                        "value": "5a889965-3db4-4c29-8003-676c247a763e"
                    }
                ],
                "schedule": {
                    "reference": "Schedule/sched1111"
                },
                "status": "free",
                "start": "2019-05-09T10:00:00.000+00:00",
                "end": "2019-05-09T10:15:00.000+00:00"
            }
        },
        {
            "fullUrl": "http://a2sibookingprovidertest.directoryofservices.nhs.uk:443/poc/Slot/slot006",
            "resource": {
                "resourceType": "Slot",
                "id": "slot006",
                "meta": {
                    "profile":  [
                        "https://fhir.hl7.org.uk/STU3/StructureDefinition/CareConnect-Slot-1"
                    ]
                },
                "identifier":  [
                    {
                        "system": "https://tools.ietf.org/html/rfc4122",
                        "value": "d939f0e0-d434-4962-a327-7ed52fde2b2e"
                    }
                ],
                "schedule": {
                    "reference": "Schedule/sched1111"
                },
                "status": "free",
                "start": "2019-05-09T10:15:00.000+00:00",
                "end": "2019-05-09T10:30:00.000+00:00"
            }
        },
        {
            "fullUrl": "http://a2sibookingprovidertest.directoryofservices.nhs.uk:443/poc/Slot/slot007",
            "resource": {
                "resourceType": "Slot",
                "id": "slot007",
                "meta": {
                    "profile":  [
                        "https://fhir.hl7.org.uk/STU3/StructureDefinition/CareConnect-Slot-1"
                    ]
                },
                "identifier":  [
                    {
                        "system": "https://tools.ietf.org/html/rfc4122",
                        "value": "50360c34-c1e0-42dd-b965-8e4dd79ed902"
                    }
                ],
                "schedule": {
                    "reference": "Schedule/sched1111"
                },
                "status": "free",
                "start": "2019-05-09T10:30:00.000+00:00",
                "end": "2019-05-09T10:45:00.000+00:00"
            }
        },
        {
            "fullUrl": "http://a2sibookingprovidertest.directoryofservices.nhs.uk:443/poc/Schedule/sched1111",
            "resource": {
                "resourceType": "Schedule",
                "id": "sched1111",
                "meta": {
                    "profile":  [
                        "https://fhir.hl7.org.uk/STU3/StructureDefinition/CareConnect-Schedule-1"
                    ]
                },
                "identifier":  [
                    {
                        "system": "https://system.supplier.co.uk/MyDiary/Numbering",
                        "value": "1015432"
                    }
                ],
                "actor":  [
                    {
                        "reference": "HealthcareService/918999198999"
                    },
                    {
                        "reference": "Practitioner/ABCD123456"
                    }
                ]
            }
        },
        {
            "fullUrl": "http://a2sibookingprovidertest.directoryofservices.nhs.uk:443/poc/HealthcareService/918999198999",
            "resource": {
                "resourceType": "HealthcareService",
                "id": "918999198999",
                "meta": {
                    "profile":  [
                        "https://fhir.hl7.org.uk/STU3/StructureDefinition/CareConnect-HealthcareService-1"
                    ]
                },
                "identifier":  [
                    {
                        "system": "https://system.supplier.co.uk/My/Services",
                        "value": "357"
                    }
                ],
                "providedBy": {
                    "reference": "https://directory.spineservices.nhs.uk/STU3/Organization/RR8"
                },
                "location":  [
                    {
                        "reference": "Location/loc2222"
                    }
                ],
                "name": "Service One"
            }
        },
        {
            "fullUrl": "http://a2sibookingprovidertest.directoryofservices.nhs.uk:443/poc/Practitioner/ABCD123456",
            "resource": {
                "resourceType": "Practitioner",
                "id": "ABCD123456",
                "meta": {
                    "profile":  [
                        "https://fhir.hl7.org.uk/STU3/StructureDefinition/CareConnect-Practitioner-1"
                    ]
                },
                "identifier":  [
                    {
                        "system": "https://fhir.nhs.uk/Id/sds-user-id",
                        "value": "ABCD123456"
                    },
                    {
                        "system": "https://fhir.nhs.uk/Id/sds-role-profile-id",
                        "value": "R0260"
                    }
                ],
                "name":  [
                    {
                        "family": "Webber",
                        "given":  [
                            "Libbie"
                        ],
                        "prefix":  [
                            "Dr"
                        ]
                    }
                ]
            }
        },
        {
            "fullUrl": "http://a2sibookingprovidertest.directoryofservices.nhs.uk:443/poc/PractitionerRole/R0260",
            "resource": {
                "resourceType": "PractitionerRole",
                "id": "R0260",
                "meta": {
                    "profile":  [
                        "https://fhir.hl7.org.uk/STU3/StructureDefinition/CareConnect-PractitionerRole-1"
                    ]
                },
                "code":  [
                    {
                        "coding":  [
                            {
                                "system": "https://fhir.hl7.org.uk/STU3/CodeSystem/CareConnect-SDSJobRoleName-1",
                                "code": "R0260",
                                "display": "General Medical Practitioner"
                            }
                        ]
                    }
                ]
            }
        },
        {
            "fullUrl": "http://a2sibookingprovidertest.directoryofservices.nhs.uk:443/poc/Location/loc1111",
            "resource": {
                "resourceType": "Location",
                "id": "loc1111",
                "meta": {
                    "profile":  [
                        "https://fhir.hl7.org.uk/STU3/StructureDefinition/CareConnect-Location-1"
                    ]
                },
                "name": "Location One"
            }
        }
    ]
}

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