Clear (cancel) a contact's appointment

Finds the contact by contact_id or phone_number and cancels their appointment(s).

ALL of the contact's live upcoming appointments are soft-deleted in the appointments table, not just the soonest one — duplicate rows do occur (the AI setter, inbound webhooks, and the booking page each insert independently), and clearing one left the duplicate on the calendar. Past appointments are left alone as reporting history; if the contact has nothing upcoming, the single most recent appointment is cleared instead.

Once no live appointment remains, the contact's appointment_date, appointment_time, and appointment_date_display columns are nulled so the contact record and the calendar agree. If a live appointment still remains, those columns are left pointing at it.

A cancel that removed nothing returns success: false with reason no_appointment_to_clear — still HTTP 200, because the request was processed fine and the outcome was simply "nothing booked". Check success (or appointments_cleared), not the status code: a cancel arriving before the booking exists must not be read as a cancellation. Idempotent — calling it twice gives success: false the second time. Never creates a contact — an unknown identifier returns 404 with reason contact_not_found.

Required fields: one of contact_id / phone_number. No date/time.

DELETE

https://api.channelautomation.com/api/appointments

Authorization

BearerAuth
optional
HTTP Bearer (JWT)

ApiKeyAuth
optional
API key in header

Request body JSON required

contact_id
optional
string
Contact UUID. Either this or phone_number is required.

format: uuid
phone_number
optional
string
Contact phone number (any common format). Used if contact_id is not provided.

Returns

200

Request processed. success is the outcome, not the status code: true means at least one appointment was soft-deleted; false with reason no_appointment_to_clear means the contact had nothing booked and nothing was cancelled.

JSON

success
optional
boolean
True only if at least one appointment row was actually soft-deleted.
reason
optional
string
Present only when success is false. no_appointment_to_clear = the contact had no appointment (or a concurrent caller cleared it first).
contact_id
optional
string
format: uuid
appointment_id
optional
string
The soonest appointment cleared. Kept for callers written against the single-appointment response; use appointment_ids for the full set.

format: uuid
appointment_ids
optional
array of
string
Every appointment soft-deleted by this call.

format: uuid
appointment_cleared
optional
boolean
Mirrors success — true only if at least one row was cleared.
appointments_cleared
optional
integer
How many appointment rows the database actually soft-deleted.
contact_columns_cleared
optional
boolean
True only if the contact's appointment columns were actually nulled (confirmed by row count). False when a live appointment still remains, since the columns must keep pointing at it.
remaining_upcoming_appointments
optional
integer
or null
Live (non-deleted) appointments the contact still has after this call — non-zero means past appointments or rows beyond the 50-per-call cap remain. Null if the check itself failed.

400

Missing identifier (neither contact_id nor phone_number)

JSON

success
optional
boolean
error
optional
string
Human-readable error message.
reason
optional
string
Short error code for programmatic handling. Possible values:
- missing_phone
- missing_adate
- missing_atime
- missing_workspace
- missing_workspace_context
- contact_upsert_failed
- contact_upsert_exception
- datetime_resolution_failed
- appointment_insert_failed
- appointment_insert_exception
- unhandled_exception
Additional values returned by PUT /api/appointments:
- missing_identifier (neither contact_id nor phone_number provided)
- invalid_contact_id (contact_id is not a valid UUID)
- contact_not_found
- contact_lookup_failed
- appointment_lookup_failed
- appointment_update_failed
- feature_disabled (APPOINTMENT_UPDATE_API flag is off for the workspace)

401

Authentication required

JSON

error
optional
string
success
optional
boolean

403

API key lacks contacts.write permission

404

No contact found for the provided identifier in this workspace (reason contact_not_found). A contact that exists but has no appointment is NOT a 404 — that returns 200 with success: false and reason no_appointment_to_clear.

JSON

success
optional
boolean
error
optional
string
Human-readable error message.
reason
optional
string
Short error code for programmatic handling. Possible values:
- missing_phone
- missing_adate
- missing_atime
- missing_workspace
- missing_workspace_context
- contact_upsert_failed
- contact_upsert_exception
- datetime_resolution_failed
- appointment_insert_failed
- appointment_insert_exception
- unhandled_exception
Additional values returned by PUT /api/appointments:
- missing_identifier (neither contact_id nor phone_number provided)
- invalid_contact_id (contact_id is not a valid UUID)
- contact_not_found
- contact_lookup_failed
- appointment_lookup_failed
- appointment_update_failed
- feature_disabled (APPOINTMENT_UPDATE_API flag is off for the workspace)

500

Clearing the appointment failed (DB error)

JSON

success
optional
boolean
error
optional
string
Human-readable error message.
reason
optional
string
Short error code for programmatic handling. Possible values:
- missing_phone
- missing_adate
- missing_atime
- missing_workspace
- missing_workspace_context
- contact_upsert_failed
- contact_upsert_exception
- datetime_resolution_failed
- appointment_insert_failed
- appointment_insert_exception
- unhandled_exception
Additional values returned by PUT /api/appointments:
- missing_identifier (neither contact_id nor phone_number provided)
- invalid_contact_id (contact_id is not a valid UUID)
- contact_not_found
- contact_lookup_failed
- appointment_lookup_failed
- appointment_update_failed
- feature_disabled (APPOINTMENT_UPDATE_API flag is off for the workspace)

curl --request DELETE \ --url https://api.channelautomation.com/api/appointments \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --data ' { "contact_id": "cc2b8604-151d-43ab-a63b-762ffa825f3e", "phone_number": "+17198592496" } '

{ "success": true, "reason": "no_appointment_to_clear", "contact_id": "f245e2a3-e141-4d41-912c-b1c1f5bd5598", "appointment_id": "21634f0d-2156-4d4b-a142-2e7c783a9212", "appointment_ids": [ "497f6eca-6276-4993-bfeb-53cbbbba6f08" ], "appointment_cleared": true, "appointments_cleared": 1, "contact_columns_cleared": true, "remaining_upcoming_appointments": 0 }