Payerbox Docs

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 Da Vinci CRD STU 2.0.1.

Endpoint

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

Auth

SMART Backend Services. See Authentication.

Context

FieldOptionalityPrefetch TokenTypeDescription
userIdREQUIREDYesstringThe id of the current user (e.g., Practitioner/123 or PractitionerRole/abc)
patientIdREQUIREDYesstringThe FHIR Patient.id of the current patient in context
encounterIdOPTIONALYesstringThe FHIR Encounter.id of the current encounter in context
appointmentsREQUIREDNoBundleA Bundle of proposed Appointment resources that are being booked

Request Parameters

FieldOptionalityTypeDescription
hookREQUIREDstringMust be appointment-book
hookInstanceREQUIREDstringA universally unique identifier for this particular hook call
contextREQUIREDobjectHook-specific contextual data (see Context table above)
fhirServerOPTIONALURLThe base URL of the CDS Client's FHIR server
fhirAuthorizationOPTIONALobjectOAuth 2.0 bearer access token for FHIR server access
prefetchOPTIONALobjectFHIR data that was prefetched by the CDS Client

Example

The response content depends on the external decision-making service configured via CDS_DECISION_SERVICE_URL. Actual Cards, suggestions, 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 with a $20 copay. 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/cardType", "display": "Coverage Information" }
      }
    },
    {
      "uuid": "a7b8c9d0-e1f2-3456-7890-123456789abc",
      "summary": "Consider scheduling annual wellness visit",
      "detail": "Patient is due for annual wellness visit which is covered at 100% with no copay.",
      "indicator": "info",
      "source": {
        "label": "CRD Decision Service",
        "url": "https://cds.example.org",
        "topic": { "code": "clinical-reminder", "system": "http://hl7.org/fhir/us/davinci-crd/CodeSystem/cardType", "display": "Clinical Reminder" }
      },
      "suggestions": [
        {
          "uuid": "b8c9d0e1-f234-5678-90ab-cdef12345678",
          "label": "Add annual wellness visit",
          "actions": [
            {
              "type": "create",
              "description": "Schedule annual wellness visit",
              "resource": {
                "resourceType": "Appointment",
                "status": "proposed",
                "serviceType": [{ "coding": [{ "system": "http://snomed.info/sct", "code": "410620009", "display": "Annual wellness visit" }] }],
                "participant": [{ "actor": { "reference": "Patient/1288992" }, "status": "needs-action" }]
              }
            }
          ]
        }
      ]
    }
  ]
}

Last updated: