Book a slot on this contact's linked CRM record
POST/api/contacts/:contact/crm/appointment
Creates an appointment in the connected CRM for the record this contact is linked to.
Refused when the contact carries more than one linked record.
Picking one of a person's two charts is how somebody is sent to a clinic
on the wrong one, so ambiguity answers 409 crm_ambiguous_link and the
link has to be resolved first.
A service is required. Measured against the live provider: a booking carrying only a person and a time is answered with HTTP 500, and stays a 500 with staff, room and status added — it is the service line that makes it a booking. Staff, room and status are optional because the same measurement showed the provider accepts a booking without them.
Before writing, the adapter re-asks availability and searches for a
booking that already matches the intent; a match is adopted rather
than duplicated (200 with write.verification: adopted), because this
provider has no idempotency key and a timed-out attempt may have landed.
After writing, the record is read back and what comes back is what is
reported — a clinic that moved the time is named in
write.observed.mismatched, never silently corrected.
Requires Contact update, the crm.write permission, and the tenant's
own appointment write switch.
Request
Responses
- 200
- 201
- 409
- 422
A booking matching this intent already existed and was adopted.
Booked. The card is re-rendered beside the write result.
Not connected, not linked, ambiguous link, or writing closed for this
operation. The error key says which.
A precondition refused the write — a missing service, a slot the provider says is taken, or a draft that could never be a booking.