appointment-book

The appointment-book hook fires when a user is scheduling one or more future appointments for a patient. It allows CDS services to provide coverage and prior authorization guidance while appointments are being proposed or booked — including recommendations about scheduling, required documentation, or coverage limitations.

Defined by the CDS Hooks appointment-book specification. Implemented by Payerbox for CRD per the Da Vinci CRD IG.

Endpoint

POST <base>/cds-services/appointment-book-crd

Auth

SMART Backend Services. See Authentication.

Context

Field	Optionality	Prefetch Token	Type	Description
userId	REQUIRED	Yes	string	The id of the current user (e.g., `Practitioner/123` or `PractitionerRole/abc`)
patientId	REQUIRED	Yes	string	The FHIR `Patient.id` of the current patient in context
encounterId	OPTIONAL	Yes	string	The FHIR `Encounter.id` of the current encounter in context
appointments	REQUIRED	No	Bundle	A Bundle of proposed `Appointment` resources that are being booked

Request Parameters

Field	Optionality	Type	Description
hook	REQUIRED	string	Must be `appointment-book`
hookInstance	REQUIRED	string	A universally unique identifier for this particular hook call
context	REQUIRED	object	Hook-specific contextual data (see Context table above)
fhirServer	OPTIONAL	URL	The base URL of the CDS Client's FHIR server
fhirAuthorization	OPTIONAL	object	OAuth 2.0 bearer access token for FHIR server access
prefetch	OPTIONAL	object	FHIR data that was prefetched by the CDS Client

Response

Coverage determinations for the proposed appointments are delivered as systemActions[] carrying the ext-coverage-information extension (the Coverage reference is taken from prefetch.coverage, since Appointment has no insurance element); cards are informational only. See CRD / System actions.

appointment-book is a primary CRD hook: when the decision service cannot evaluate an appointment present in the hook context, the response still carries a coverage-information system action for it with covered = conditional, info-needed = OTH, and a human-readable reason (no pa-needed claim), alongside an explanatory card.

Example

The response content depends on the external decision-making service configured via CDS_DECISION_SERVICE_URL. Actual Cards and links are generated by your decision service based on coverage requirements and prior authorization rules.

POST /cds-services/appointment-book-crd
Content-Type: application/json
Accept: application/json

{
  "hook": "appointment-book",
  "hookInstance": "c3d4e5f6-a7b8-9012-cdef-345678901234",
  "fhirServer": "https://ehr.example.com/fhir",
  "fhirAuthorization": {
    "access_token": "some-opaque-fhir-access-token",
    "token_type": "Bearer",
    "expires_in": 300,
    "scope": "user/Patient.read user/Appointment.read",
    "subject": "cds-service"
  },
  "context": {
    "userId": "Practitioner/dr-smith-123",
    "patientId": "1288992",
    "encounterId": "89284",
    "appointments": {
      "resourceType": "Bundle",
      "entry": [
        {
          "resource": {
            "resourceType": "Appointment",
            "id": "proposed-appt-001",
            "status": "proposed",
            "serviceType": [{ "coding": [{ "system": "http://snomed.info/sct", "code": "394802001", "display": "General medicine" }] }],
            "appointmentType": { "coding": [{ "system": "http://terminology.hl7.org/CodeSystem/v2-0276", "code": "FOLLOWUP", "display": "Follow-up" }] },
            "description": "Follow-up appointment for chronic condition management",
            "start": "2026-02-15T09:00:00Z",
            "end": "2026-02-15T09:30:00Z",
            "participant": [
              { "actor": { "reference": "Patient/1288992" }, "status": "accepted" },
              { "actor": { "reference": "Practitioner/dr-smith-123" }, "status": "accepted" }
            ]
          }
        }
      ]
    }
  },
  "prefetch": {
    "patient": {
      "resourceType": "Patient",
      "id": "1288992",
      "name": [{ "given": ["John"], "family": "Doe" }],
      "birthDate": "1970-01-01",
      "gender": "male"
    },
    "coverage": {
      "resourceType": "Coverage",
      "id": "cov-001",
      "status": "active",
      "beneficiary": { "reference": "Patient/1288992" },
      "payor": [{ "reference": "Organization/insurance-company-789" }]
    }
  }
}

{
  "cards": [
    {
      "uuid": "f6a7b8c9-d0e1-2345-f678-901234567890",
      "summary": "Appointment covered under patient's plan",
      "detail": "This follow-up visit is covered. No prior authorization required.",
      "indicator": "info",
      "source": {
        "label": "CRD Decision Service",
        "url": "https://cds.example.org",
        "topic": { "code": "coverage-info", "system": "http://hl7.org/fhir/us/davinci-crd/CodeSystem/temp" }
      }
    }
  ],
  "systemActions": [
    {
      "type": "update",
      "description": "Update the draft Appointment with CRD coverage information.",
      "resource": {
        "resourceType": "Appointment",
        "id": "proposed-appt-001",
        "status": "proposed",
        "serviceType": [{ "coding": [{ "system": "http://snomed.info/sct", "code": "394802001", "display": "General medicine" }] }],
        "start": "2026-02-15T09:00:00Z",
        "end": "2026-02-15T09:30:00Z",
        "participant": [
          { "actor": { "reference": "Patient/1288992" }, "status": "accepted" },
          { "actor": { "reference": "Practitioner/dr-smith-123" }, "status": "accepted" }
        ],
        "extension": [
          {
            "url": "http://hl7.org/fhir/us/davinci-crd/StructureDefinition/ext-coverage-information",
            "extension": [
              { "url": "coverage", "valueReference": { "reference": "Coverage/cov-001" } },
              { "url": "covered", "valueCode": "covered" },
              { "url": "pa-needed", "valueCode": "no-auth" },
              { "url": "date", "valueDate": "2026-09-03" },
              { "url": "coverage-assertion-id", "valueString": "9c4e7d2b-1a5f-4e8c-b3d6-2f7a8e9c0d1b" }
            ]
          }
        ]
      }
    }
  ]
}