HomeGuidesAPI Reference
Log In

Cancelling appointments

This guide describes how to cancel appointments


Due to the need to aggregate demand and plan Practitioner routes cancellations are operationally complex to manage. Cancellations are are specific part of an Organisations Service Agreements, and in general cancellations are chargeable when the cancellation occurs less than 24 hours before the appointment.window.startAt date/time of 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 the mobile or by email",  
  "cancellingEntity": "organisation",  
  "reasonCode": "cannot_find_location"  

Important notes

  • It is only permitted to cancel an appointment once via an API. Further POSTs will cause an error
  • Ally 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 Ally Operations updating the cancellation entity
  • It is very helpful to provide a descriptive note in the cancellation entity that helps Ally Operations to validate the cancellation reason

Supported Cancelling Entities

The following cancelling entities are supported via the API

organisationThe cancelling entity should be set to "organisation" when a member of your operations team cancels the appointment.
patientThe 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

Supported Reason Codes

The following reason codes are supported via the API

practitioner_delayedPractitioner delayed
practitioner_cancelledPractitioner cancelled
patient_not_presentPatient not present
patient_cancelledPatient cancelled
platform_service_issueDue to Ally service issue
organisation_cancelledDue to your request to cancel the appointment