Overview

Due to the need to aggregate demand and plan Practitioner routes cancellations are operationally complex to manage. Cancellations are a specific part of an Organisation's Service Agreement, and in general cancellations are chargeable when the cancellation occurs less than 24 hours before the Estimated Time Of Arrival (ETA) of the Appointment. This is visible as appointment.estimatedTimeOfArrival in the GET Appointment by Id request. If the ETA is not set yet, then there is no charge for cancelling the appointment. Please refer to your agreement for the authoritative terms and conditions.

To cancel an appointment, use the POST /v1/appointments/{appointmentId}/cancel end point to post a cancellation object in the form:

{  
  "note": "Unable to contact Patient on their mobile or by email",  
  "causingEntity": "patient"
  "cancellingEntity": "organisation",
  "reasonCode": "patient_not_present"  
}

Important notes

It is only permitted to cancel an appointment once via an API. Further POSTs will cause an error
Heim Operations may update the cancellation entity following verification of the cancelling entity and reasons. This update is available by retrieving the cancellation object via a get request. The appointment.cancelled webhook is fired in the event of Heim Operations updating the cancellation entity
It is very helpful to provide a descriptive note in the cancellation entity that helps Heim Operations to validate the cancellation reason

Supported causing entities

The causing entity is used to determine whether the appointment should be chargeable. The causing entity is reviewed by the Heim Operations team as appointments are cancelled. The following causingEntities are supported:

causingEntity	Description
organisation	Where the cause of the appointment cancellation is due to your Organisation
patient	Where the cause of the appointment cancellation is due to the Patient
platform	Where the cause of the appointment cancellation is due to Heim
practitioner	Where the cause of the appointment cancellation is due to the Practitioner

Supported cancelling entities

The cancelling entity notes who is doing the cancellation. The following cancelling entities are supported:

cancellingEntity	Description
organisation	The cancelling entity should be set to "organisation" when a member of your operations team or an automation run by your system cancels the appointment
patient	The cancelling entity should be set to "patient" when you have allowed your patient to directly cancel the appointment via an interface that you share with them, such as through a dashboard on your customer portal or in your own mobile app

Supported reason codes

The following reason codes are supported via the API

reasonCode	Description
patient_cancelled	Patient cancelled
patient_not_present	Patient not present
patient_unwell	Patient unwell
patient_requested_reschedule	Patient requested reschedule
practitioner_late	Practitioner is delayed or late
practitioner_cancelled	Practitioner cancelled
incorrect_patient_information	Incorrect patient information (eg. address)
no_longer_required	No longer required
organisation_cancelled	Due to your request to cancel the appointment
operator_error	Created in error
duplicate_appointment	Duplicate appointment
organisation_requested_reschedule	Organisation requested reschedule
missing_organisation_provided_equipment	Due to missing equipment provided by you
organisation_service_issue	A problem with your service requires you to cancel
platform_service_issue	Due to Heim service issue