AppointmentResponse — Reply to an appointment
An actor — patient, practitioner, room — replies to an appointment proposal. Accept, decline, counter-propose: AppointmentResponse records each RSVP.
Purpose
AppointmentResponse represents a participant's reply to a proposed Appointment.
When the system creates an appointment with multiple participants (clinician,
patient, room, device), each can reply individually — one AppointmentResponse per
actor. The overall Appointment status depends on the aggregated replies:
booked only if all required participants have accepted.
Key fields
| Field | Type | Cardinality | Role |
|---|---|---|---|
identifier | Identifier[] | 0..* | External identifiers. |
appointment | Reference(Appointment) | 1..1 | Mandatory. Target appointment. |
proposedNewTime | boolean | 0..1 | true = counter-proposal with another slot. |
start | instant | 0..1 | Proposed/accepted start. |
end | instant | 0..1 | Proposed/accepted end. |
participantType | CodeableConcept[] | 0..* | Participant role. |
actor | Reference(Patient | Group | Practitioner | PractitionerRole | RelatedPerson | Device | HealthcareService | Location) | 0..1 | Responding participant. |
participantStatus | code | 1..1 | Mandatory. accepted, declined, tentative, needs-action. |
comment | string | 0..1 | Free-form comment. |
recurring | boolean | 0..1 | Applies to the whole series. |
occurrenceDate | date | 0..1 | Targeted occurrence (if recurring). |
recurrenceId | positiveInt | 0..1 | Occurrence ID in the series. |
Lifecycle
An Appointment is created in proposed or pending: the
server generates one AppointmentResponse needs-action per required
participant. Each reply updates the participant's status in
Appointment.participant[]. When all required participants have
accepted, the Appointment flips to booked.
JSON example
A patient confirms their 20 May 2026 appointment:
{
"resourceType": "AppointmentResponse",
"id": "ar-001",
"identifier": [{ "system": "urn:oid:1.2.34", "value": "AR-2026-05-15-001" }],
"appointment": { "reference": "Appointment/apt-2026-05-20-001" },
"proposedNewTime": false,
"start": "2026-05-20T10:00:00+02:00",
"end": "2026-05-20T10:30:00+02:00",
"participantType": [{
"coding": [{
"system": "http://terminology.hl7.org/CodeSystem/v3-ParticipationType",
"code": "ATND",
"display": "attender"
}]
}],
"actor": { "reference": "Patient/doe-john" },
"participantStatus": "accepted",
"comment": "Confirmed, I will arrive 10 minutes early",
"recurring": false,
"occurrenceDate": "2026-05-20"
}Common pitfalls
- No sync with Appointment.participant.status — creating an AppointmentResponse without updating the Appointment-side status leaves the EHR confused.
- Counter-proposal without
start/end—proposedNewTime=truemust come with a new slot, otherwise there is nothing actionable. - Reply for an unlisted actor —
actormust be part of Appointment.participant[]. - Ambiguous recurrence —
recurring=truewithoutoccurrenceDateapplies to all occurrences: often unintentional. - Confusing with Appointment.participant.status — the formal reply is a resource; the status is denormalized for fast reads.
Related resources
- Appointment — target proposal.
- Schedule / Slot — underlying availability.
- Patient, Practitioner — typically
actor.