---
description: appointment-book CDS Hook — fires when an appointment is being scheduled
---

# 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](https://cds-hooks.hl7.org/hooks/appointment-book/). Implemented by Payerbox for [CRD](../../prior-auth/crd.md) per [Da Vinci CRD STU 2.0.1](https://hl7.org/fhir/us/davinci-crd/STU2.0.1/).

## Endpoint

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

## Auth

SMART Backend Services. See [Authentication](../authentication.md).

## 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 |

## Example

{% hint style="info" %}
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.
{% endhint %}

{% tabs %}
{% tab title="Request" %}

```http
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" }]
    }
  }
}
```

{% endtab %}

{% tab title="Response" %}

```json
{
  "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" }]
              }
            }
          ]
        }
      ]
    }
  ]
}
```

{% endtab %}
{% endtabs %}