> ## Documentation Index
> Fetch the complete documentation index at: https://docs.encoreos.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Real-Time Eligibility at Check-In — Integration Document

> Status: \U0001F4CB Stub — Schemas to be completed during implementation Last Updated: 2026-03-02 Integration Pattern: Event (appointment status trigger) +…

**Status:** 📋 Stub — Schemas to be completed during implementation\
**Spec:** [PM-34](../../../specs/pm/specs/PM-34-realtime-eligibility-checkin.md)\
**Last Updated:** 2026-03-02\
**Integration Pattern:** Event (appointment status trigger) + Data (pm\_eligibility\_checks, pm\_checkin\_discrepancies) + Platform Layer (PF-10 notifications)

***

## Integration Overview

PM-34 adds a real-time eligibility check-in layer that:

1. Listens for PM-03 appointment `checked_in` status transitions.
2. Invokes PM-02 eligibility verification; stores result with `trigger_context = 'checkin'`.
3. Detects discrepancies against last-known eligibility; creates `pm_checkin_discrepancies` records.
4. Optionally sends PF-10 notifications to front desk.
5. Feeds copay/coinsurance to PM-07 charge defaults.

***

## Integration Points

### PM-03 (Appointment Scheduling) → PM-34

**Pattern:** Event subscription or direct call from check-in UI\
**Trigger:** Appointment status transitions to `checked_in`\
**Data exchanged:**

| Field             | Source           | Destination                                         | Notes                   |
| ----------------- | ---------------- | --------------------------------------------------- | ----------------------- |
| `appointment_id`  | pm\_appointments | pm\_eligibility\_checks                             | FK for trigger context  |
| `patient_id`      | pm\_appointments | PM-02 call params                                   | Patient for eligibility |
| `organization_id` | pm\_appointments | pm\_eligibility\_checks, pm\_checkin\_discrepancies | Tenant isolation        |

**Contract:** TODO — define event payload or API call when PM-03 appointment-status trigger is implemented.\
**Status:** 📋 Planned

***

### PM-34 → PM-02 (Insurance & Eligibility Verification)

**Pattern:** Data / API call\
**Description:** PM-34 invokes PM-02 eligibility check with `trigger_context = 'checkin'`; stores `appointment_id` on result row.\
**Request parameters:**

| Parameter         | Type | Source                            | Notes                    |
| ----------------- | ---- | --------------------------------- | ------------------------ |
| `patient_id`      | UUID | pm\_appointments                  | Patient                  |
| `policy_id`       | UUID | pm\_insurance\_policies (primary) | Primary insurance policy |
| `trigger_context` | TEXT | PM-34                             | `'checkin'`              |
| `appointment_id`  | UUID | pm\_appointments                  | Optional FK              |

**Response:** pm\_eligibility\_checks row (existing PM-02 schema + new `trigger_context`, `appointment_id`, `is_stale` columns).\
**Timeout:** Org-configurable; default 10s (PM-28 `checkin_eligibility_timeout_seconds`). On timeout: `is_stale = true`, discrepancy created.\
**Status:** 📋 Planned

***

### PM-34 → PF-10 (Notifications)

**Pattern:** Platform Layer\
**Trigger:** Discrepancy record created\
**Condition:** `pm_module_settings.checkin_eligibility_notification_enabled = true`\
**Notification target:** Users with `pm.checkin.eligibility.manage` in the same organization

**Payload schema:**

```json theme={null}
{
  "type": "pm_checkin_discrepancy",
  "organization_id": "uuid",
  "appointment_id": "uuid",
  "patient_id": "uuid",
  "discrepancy_type": "new_plan | copay_change | ...",
  "discrepancy_id": "uuid"
}
```

**Status:** 📋 Planned

***

### PM-34 → PM-07 (Charge Management)

**Pattern:** Data\
**Description:** When a charge is created for the appointment, PM-07 reads the latest eligibility check (trigger\_context = 'checkin') and auto-populates copay/deductible remaining in charge defaults.\
**Fields consumed:**

| Eligibility Field     | PM-07 Target                       | Notes                                     |
| --------------------- | ---------------------------------- | ----------------------------------------- |
| copay\_amount         | charge defaults copay field        | Auto-populated; overridable by front desk |
| deductible\_remaining | charge defaults deductible display | Informational                             |

**Status:** 📋 Planned

***

### PM-12 (Patient Portal / Kiosk) → PM-34 → PM-02

**Pattern:** Event or API call\
**Description:** When patient confirms or updates insurance in PM-12 portal/kiosk flow, PM-12 triggers PM-02 verification via PM-34 logic with `trigger_context = 'portal'` or `'kiosk'`.\
**Status:** 📋 Planned — PM-12 owns the UI trigger; PM-34 defines the `trigger_context` values and discrepancy handling.

***

### PM-34 → PM-30 (Coordination of Benefits)

**Pattern:** Data (soft dependency)\
**Description:** COB order (primary/secondary payer sequence) is read from `pm_insurance_policies`. PM-30 integration is additive when available; no hard dependency.\
**Status:** 📋 Planned (soft dependency; no blocking)

***

## Platform Layers Used

| Layer                              | Purpose                                                    |
| ---------------------------------- | ---------------------------------------------------------- |
| `@/platform/scheduling`            | Appointment and encounter context                          |
| `@/platform/notifications` (PF-10) | Front desk discrepancy alert                               |
| `@/platform/permissions`           | `pm.checkin.eligibility.view`, `.manage` permission checks |

***

## Security & Tenant Isolation

* `pm_checkin_discrepancies`: RLS enabled; `organization_id` on all rows; SECURITY DEFINER helper `pm_has_org_access`.
* `pm_eligibility_checks` new columns: covered by existing PM-02 RLS.
* No PHI in event payloads beyond IDs; detail fetched via RLS-protected query.

***

## Contract Validation Checklist

* [ ] Event payload schemas completed for PM-03 → PM-34 trigger
* [ ] PM-02 API call parameters documented with types
* [ ] PF-10 notification payload schema validated
* [ ] PM-07 field mapping documented with column names from types.ts (post-Phase 1)
* [ ] Security: organization\_id present in all payloads; no PHI in notification body
* [ ] Timeout and error handling documented for PM-02 call