POST/transactional-api/cancel-appointment

Cancel Appointment

Cancels an existing appointment for a patient. A cancellation reason is required. Returns 204 No Content on success.

Authorization: Bearer token (JWT). See Authentication.

Request

curl -L -X POST 'https://{tenantId}.api.england.medicus.health/transactional-api/cancel-appointment' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer <token>' \
  -d '{
    "appointmentId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "patientId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "cancellationReason": "string"
  }'

Body parameters

Field	Type	Required	Description
appointmentId	string<uuid>	Yes	The appointment to cancel.
patientId	string<uuid>	Yes	Medicus patient identifier. Must match the patient the appointment was booked for.
cancellationReason	string	Yes	Human-readable reason for cancellation. Must not be empty.

Responses

204 Appointment cancelled successfully.

400 Validation error.

5 possible code values

Code	Description	When
missing-patient-id	The patientId is required	patientId missing
invalid-patient-id	The patientId is not valid	patientId not a valid UUID
missing-appointment-id	The appointmentId is required	appointmentId missing
invalid-appointment-id	The appointmentId is not valid	appointmentId not a valid UUID
missing-cancellation-reason	The cancellationReason is required	cancellationReason is missing or blank

{
  "errors": [
    {
      "code": "missing-patient-id",
      "description": "The patientId is required"
    }
  ]
}

404 No appointment found for the given appointmentId and patientId combination.

{
  "errors": [
    {
      "code": "appointment-not-found",
      "description": "Appointment not found for this appointmentId and patientId."
    }
  ]
}

409 The appointment exists but cannot be cancelled in its current state.

{
  "errors": [
    {
      "code": "appointment-cannot-be-cancelled",
      "description": "The appointment cannot be cancelled because it has already started or has already been cancelled."
    }
  ]
}