• API Hub
  • Search loading...

    API Hub

    Explore and Make use of Nationally Defined Messaging APIs


    Read an appointment

    Use case for reading an appointment resource.

    API Use Case

    This specification describes a single use cases. For complete details and background please see the Appointment Management Capability Bundle.


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


    The Consumer system:

    API Usage

    The Consumer System SHALL only use the read appointment capability to retrieve future appointments, where the appointment start dateTime is after the current date and time. If the appointment start date is in the past the provider SHALL return an error.

    Request Operation

    FHIR Relative Request

    GET /Appointment/[id]

    FHIR Absolute Request

    GET https://[proxy_server]/https://[provider_server]/[fhir_base]/Appointment/[id]

    Request Headers

    Consumers SHALL include the following additional HTTP request headers:

    Header Value
    Ssp-TraceID Consumer’s TraceID (i.e. GUID/UUID)
    Ssp-From Consumer’s ASID
    Ssp-To Provider’s ASID
    Ssp-InteractionID urn:nhs:names:services:gpconnect:fhir:rest:read:appointment-1

    Payload Request Body


    Error Handling

    Provider systems:

    • SHALL return an GPConnect-OperationOutcome-1 resource that provides additional detail when one or more data fields are corrupt or a specific business rule/constraint is breached.
    • SHALL return an error if the appointment being read is in the past (the appointment start dateTime is before the current date and time).

    Examples of other scenarios which may result in error being returned:

    • Where a Logical identifier of the resource is not valid/can’t be found on the server, a 404 HTTP Status code would be returned with the relevent OperationOutcome resource.
    • Where insufficient data about an appointment is present in the provider system to populate an appointment resource which validates to the GPConnect-Appointment-1 profile, an 500 HTTP Status code should be returned, together with the appropriate OperationOutcome resource providing diagnostic detail.

    Refer to Development - FHIR API Guidance - Error Handling 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 execution of the operation.
    • SHALL return Appointment resources that conform to the GPConnect-Appointment-1 resource profile.
    • SHALL include the URI of the GPConnect-Appointment-1 profile StructureDefinition in the Appointment.meta.profile element of the returned appointment resource.
    • SHALL include the versionId of the current version of the appointment resource.
    • SHALL include all relevant business identifier details (if any) for the appointment resource.
    	"resourceType": "Appointment",
    	"id": "148",
    	"meta": {
    		"versionId": "1503310820000",
    		"lastUpdated": "2017-11-08T10:20:20.000+00:00",
    		"profile": ["https://fhir.nhs.uk/STU3/StructureDefinition/GPConnect-Appointment-1"]
    	"contained": [{
    		"resourceType": "Organization",
    		"id": "1",
    		"meta": {
    			"profile": ["https://fhir.nhs.uk/STU3/StructureDefinition/CareConnect-GPC-Organization-1"]
    		"name": "Test Organization Name",
    		"telecom": [{
    			"system": "phone",
    			"value": "0300 303 5678"
    	"extension": [{
    		"url": "https://fhir.nhs.uk/STU3/StructureDefinition/Extension-GPConnect-BookingOrganisation-1",
    		"valueReference": {
    			"reference": "#1"
    	"status": "booked",
    	"reason": {
    		"coding": [{
    			"system": "http://snomed.info/sct",
    			"code": "00001",
    			"display": "Default Appointment Type"
    		"text": "Default Appointment Type"
    	"description": "GP Connect Appointment description 148",
    	"start": "2017-08-21T10:20:00.000+00:00",
    	"end": "2017-08-21T10:50:00.000+00:00",
    	"slot": [{
    		"reference": "Slot/544"
    		"reference": "Slot/545"
    		"reference": "Slot/546"
    	"created": "2017-10-09T13:48:41+01:00",
    	"comment": "Test Appointment Comment 148",
    	"participant": [{
    		"actor": {
    			"reference": "Patient/2"
    		"status": "accepted"
    		"actor": {
    			"reference": "Location/1"
    		"status": "accepted"
    		"actor": {
    			"reference": "Practitioner/2"
    		"status": "accepted"



    var client = new FhirClient("http://gpconnect.aprovider.nhs.net/GP001/STU3/1/");
    client.PreferredFormat = ResourceFormat.Json;
    var resource = client.Read<Appointment>("Appointment/148");


    FhirContext ctx = FhirContext.forStu3();
    IGenericClient client = ctx.newRestfulGenericClient("http://gpconnect.aprovider.nhs.net/GP001/STU3/1");
    Appointment appointment = client.read().resource(Appointment.class).withId("148").execute();
    Tags: appointments

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