What is AppointmentResponse?

The AppointmentResponse resource tracks how participants respond to appointment requests. It indicates acceptance, rejection, or other status.

Participant Status Values

Create an AppointmentResponse

curl -X POST https://api.esus.health/fhir/AppointmentResponse \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/fhir+json" \
  -d '{
    "resourceType": "AppointmentResponse",
    "appointment": {
      "reference": "Appointment/d4e5f6a7-b8c9-0123-def4-567890abcdef"
    },
    "participantStatus": "accepted",
    "actor": {
      "reference": "Patient/3fa85f64-5717-4562-b3fc-2c963f66afa6"
    },
    "participantType": [{
      "coding": [{
        "system": "http://terminology.hl7.org/CodeSystem/v3-ParticipationType",
        "code": "PAT",
        "display": "Patient"
      }]
    }],
    "comment": "I will be there on time"
  }'

Practitioner Response

AppointmentResponse resources are NOT generated automatically: neither a plain POST /fhir/Appointment nor the $book operation creates an AppointmentResponse. Every response must be created explicitly. To record that a practitioner accepted, POST one with their actor and participantStatus: "accepted":

# Practitioner response (created explicitly)
{
  "resourceType": "AppointmentResponse",
  "appointment": { "reference": "Appointment/d4e5f6a7-b8c9-0123-def4-567890abcdef" },
  "participantStatus": "accepted",
  "actor": { "reference": "Practitioner/a7b1c2d3-e4f5-6789-abcd-ef0123456789" },
  "participantType": [{
    "coding": [{
      "code": "PPRF",
      "display": "Primary Performer"
    }]
  }]
}

Search Responses

# Get all responses for an appointment
curl "https://api.esus.health/fhir/AppointmentResponse?appointment=Appointment/d4e5f6a7-b8c9-0123-def4-567890abcdef" \
  -H "Authorization: Bearer YOUR_TOKEN"

# Get pending responses for a practitioner
curl "https://api.esus.health/fhir/AppointmentResponse?actor=Practitioner/a7b1c2d3-e4f5-6789-abcd-ef0123456789&participantStatus=needs-action" \
  -H "Authorization: Bearer YOUR_TOKEN"

Handling Rejections

When a participant declines:

curl -X POST https://api.esus.health/fhir/AppointmentResponse \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/fhir+json" \
  -d '{
    "resourceType": "AppointmentResponse",
    "appointment": { "reference": "Appointment/d4e5f6a7-b8c9-0123-def4-567890abcdef" },
    "participantStatus": "declined",
    "actor": { "reference": "Patient/3fa85f64-5717-4562-b3fc-2c963f66afa6" },
    "comment": "Schedule conflict - will call to reschedule"
  }'

Then the parent Appointment status should be updated to cancelled or noshow.