• API Hub
  • Search loading...

    API Hub

    Explore and Make use of Nationally Defined Messaging APIs

     

    Cancel an appointment for a patient at an organisation

    Use case for cancelling an appointment for a patient with a given organisation.

    Use case

    The typical flow to cancel an appointment is:

    1. Search by NHS Number for, or otherwise obtain, a Patient resource.
    2. Search for Appointment resources for the Patient resource.
    3. Choose an Appointment resource and cancel it by amending the status to cancelled.

    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

    Prerequisites

    Consumer

    The consumer system:

    API usage

    The consumer system SHALL only use the cancel appointment capability to cancel future appointments where 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

    PUT /Appointment/[id]
    

    FHIR absolute request

    PUT 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 (that is, GUID/UUID)
    Ssp-From Consumer’s ASID
    Ssp-To Provider’s ASID
    Ssp-InteractionID urn:nhs:names:services:gpconnect:fhir:rest:cancel:appointment-1

    Payload request body

    The request payload is a profiled version of the standard FHIR® Appointment resource. See the FHIR resources page for more details.

    Consumer systems:

    • SHALL send an Appointment resource that conforms to the GPConnect-Appointment-1 profile.
    • SHALL include the URI of the GPConnect-Appointment-1 profile StructureDefinition in the Appointment.meta.profile element of the appointment resource.

    Only the following data elements can be modified when performing an appointment cancellation:

    • the appointment status MUST be updated to “cancelled”
    • the appointment cancellation-reason extension SHALL be included with the cancellation reason details

    On the wire, a JSON serialised request would look something like the following:

    {
    	"resourceType": "Appointment",
    	"id": "9",
    	"meta": {
    		"versionId": "636068818095315079",
    		"lastUpdated": "2016-08-15T19:16:49.971+01: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"
    		}
    	},
    	{
    		"url": "https://fhir.nhs.uk/STU3/StructureDefinition/Extension-GPConnect-AppointmentCancellationReason-1",
    		"valueString": "Free text cancellation reason."
    	}],
    	"status": "cancelled",
    	"description": "Free text description updated.",
    	"start": "2016-05-30T10:00:00+01:00",
    	"end": "2016-05-30T10:25:00+01:00",
    	"slot": [{
    		"reference": "Slot/1",
    		"display": "Slot 1"
    	}],
    	"created": "2017-10-09T13:48:41+01:00",
    	"comment": "Free text comment.",
    	"participant": [{
    		"actor": {
    			"reference": "Patient/1",
    			"display": "Mr. Mike Smith"
    		},
    		"status": "accepted"
    	},
    	{
    		"actor": {
    			"reference": "Location/32",
    			"display": "Leeds GP Clinic"
    		},
    		"status": "accepted"
    	}]
    }
    

    Error handling

    The provider system:

    • SHALL return an GPConnect-OperationOutcome-1 resource that provides additional details when one or more data fields are corrupt or a specific business rule/constraint is breached.
    • SHALL return an error if any appointment details other than the appointment status and cancellation-reason fields are attempted to be updated.
    • SHALL return an error if the appointment being cancelled is in the past (the appointment start dateTime is before the current date and time).

    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 an Appointment resource that conform to the GPConnect-Appointment-1 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 each appointment resource.
    • SHALL have updated the appointment status to “cancelled”.
    • SHALL have updated the appointment cancellation-reason in line with any details supplied in the request.
    {
    	"resourceType": "Appointment",
    	"id": "9",
    	"meta": {
    		"versionId": "636068818095315079",
    		"lastUpdated": "2016-08-15T19:16:49.971+01: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"
    		}
    	},
    	{
    		"url": "https://fhir.nhs.uk/STU3/StructureDefinition/Extension-GPConnect-AppointmentCancellationReason-1",
    		"valueString": "Free text cancellation reason."
    	}],
    	"status": "cancelled",
    	"description": "Free text description updated.",
    	"start": "2016-05-30T10:00:00+01:00",
    	"end": "2016-05-30T10:25:00+01:00",
    	"slot": [{
    		"reference": "Slot/1",
    		"display": "Slot 1"
    	}],
    	"created": "2017-10-09T13:48:41+01:00",
    	"comment": "Free text comment.",
    	"participant": [{
    		"actor": {
    			"reference": "Patient/1",
    			"display": "Mr. Mike Smith"
    		},
    		"status": "accepted"
    	},
    	{
    		"actor": {
    			"reference": "Location/32",
    			"display": "Leeds GP Clinic"
    		},
    		"status": "accepted"
    	}]
    }
    

    Examples

    C#

    var client = new FhirClient("http://gpconnect.aprovider.nhs.net/GP001/STU3/1");
    client.PreferredFormat = ResourceFormat.Json;
    var appointment = client.Read<Appointment>("Appointment/9");
    // Cancel The Appointment
    appointment.Status = Appointment.AppointmentStatus.Cancelled;
    appointment.Extension.Add(new Extension("https://fhir.nhs.uk/STU3/StructureDefinition/Extension-GPConnect-AppointmentCancellationReason-1",new FhirString("Free text cancellation reason.")));
    var cancelledAppointment = client.Update<Appointment>(appointment);
    FhirSerializer.SerializeResourceToJson(cancelledAppointment).Dump();
    

    Java

    // Read appointment to be updated
    FhirContext ctx = FhirContext.forStu3();
    IGenericClient client = ctx.newRestfulGenericClient("http://gpconnect.aprovider.nhs.net/GP001/STU3/1");
    Appointment appointment = client.read().resource(Appointment.class).withId("9").execute();
    
    // Amend appointment status and cancellation reason
    appointment.setStatus(AppointmentStatusEnum.CANCELLED);
    ExtensionDt extension = new ExtensionDt(false);
    extension.setUrl("https://fhir.nhs.uk/STU3/StructureDefinition/Extension-GPConnect-AppointmentCancellationReason-1");
    extension.setValue(new StringDt("Free text cancellation reason."));
    appointment.addUndeclaredExtension(extension);
    
    // Cancel appointment
    MethodOutcome response = client.update()
    	.resource(appointment)
    	.prefer(PreferReturnEnum.REPRESENTATION)
    	.preferResponseType(Appointment.class)
    	.execute();
    
    System.out.println(fhirContext.newJsonParser().setPrettyPrint(true).encodeResourceToString(response.getResource()));
    
    Tags: appointments

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