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

# Good Faith Estimate & Price Transparency — Integration

> Version: 1.0.0 Last Updated: 2026-02-27 Status: ✅ Complete Spec: PM-20-good-faith-estimate-price-transparency

**Version:** 1.0.0\
**Last Updated:** 2026-02-27\
**Status:** ✅ Complete\
**Spec:** [PM-20-good-faith-estimate-price-transparency](../../../specs/pm/specs/PM-20-good-faith-estimate-price-transparency.md)

***

## Overview

PM-20 implements No Surprises Act (NSA) Good Faith Estimate generation, delivery timing compliance, acknowledgment tracking, and dispute resolution for uninsured/self-pay patients. It depends on PF and same-core PM features only; no cross-core imports.

## Quick Reference

| I need to…                                  | Pattern                                                 | Location                                                       |
| ------------------------------------------- | ------------------------------------------------------- | -------------------------------------------------------------- |
| Identify self-pay patients for GFE          | PM-02 insurance status (uninsured/self-pay)             | [Contract: Same-Core (PM)](#contract-same-core-pm)             |
| Build estimate from scheduled services      | PM-03 appointment + PM-07 fee schedule                  | [Contract: Same-Core (PM)](#contract-same-core-pm)             |
| Deliver GFE via email/portal                | PF-10 notifications + PM-16 statement channels          | [Contract: Platform Foundation](#contract-platform-foundation) |
| Ensure tenant isolation on GFE/dispute data | RLS via `pm_has_org_access`; permission keys `pm.gfe.*` | [Security & Tenant Isolation](#security--tenant-isolation)     |

***

## Integration Matrix

| Integration                              | Spec          | Direction  | Pattern                    | Status     |
| ---------------------------------------- | ------------- | ---------- | -------------------------- | ---------- |
| Organizations & Sites                    | PF-01         | PM-20 → PF | Direct                     | 📝 Planned |
| RBAC / Permissions                       | PF-02 (PF-30) | PM-20 → PF | Direct                     | 📝 Planned |
| Notifications (GFE ready/delivered)      | PF-10         | PM-20 → PF | Platform Integration Layer | 📝 Planned |
| Patient Registration & Demographics      | PM-01         | PM-20 → PM | Same core                  | 📝 Planned |
| Insurance & Eligibility (self-pay check) | PM-02         | PM-20 → PM | Same core                  | 📝 Planned |
| Appointment Scheduling (trigger)         | PM-03         | PM-20 → PM | Same core                  | 📝 Planned |
| Charge Capture & Fee Schedules (rates)   | PM-07         | PM-20 → PM | Same core                  | 📝 Planned |
| Patient Statements & Communications      | PM-16         | PM-20 → PM | Same core                  | 📝 Planned |

### Cross-Core Summary (CROSS\_CORE\_INTEGRATIONS.md)

| From Core  | To Core                                                | Integration Pattern   | Status | Documentation                                                                                             |
| ---------- | ------------------------------------------------------ | --------------------- | ------ | --------------------------------------------------------------------------------------------------------- |
| PM (PM-20) | PF-01, PF-02, PF-10, PM-01, PM-02, PM-03, PM-07, PM-16 | Platform Layer / Data | 📝     | [PM-20 Good Faith Estimate & Price Transparency](./good-faith-estimate-price-transparency-integration.md) |

***

## Contract: Platform Foundation

### PF-01 (Organizations & Sites)

* **Usage:** Tenant context (`organization_id`) on all PM-20 tables; RLS and app-level filtering.
* **Contract:** Standard multi-tenant pattern; no custom API.

### PF-02 / PF-30 (Permissions)

* **Usage:** Permission keys `pm.gfe.view`, `pm.gfe.create`, `pm.gfe.manage` for UI and actions.
* **Contract:** Keys defined in spec; seeded in migration; checks via `pf_has_permission()` and `useHasPermission()`.

### PF-10 (Notifications)

* **Usage:** Optional notification when GFE is ready or delivered to patient.
* **Contract:** Use `@/platform/notifications` (Platform Integration Layer). Payload contains only system-generated UUIDs (`patient_id`, `gfe_id`, `organization_id`); no PHI in notification payloads. Display names resolved via authorized UI calls.

***

## Contract: Same-Core (PM)

### PM-01 (Patient Registration & Demographics)

* **Usage:** Patient context for GFE — `pm_good_faith_estimates.patient_id` references `pm_patients.id`. Patient name displayed on GFE list and detail views.
* **Contract:** Direct table join within PM core; FK enforced at database level.

### PM-02 (Insurance & Eligibility)

* **Usage:** Identify self-pay/uninsured patients eligible for GFE. PM-02 insurance status determines whether GFE is required per NSA.
* **Contract:** Query `pm_insurance_policies` for active policies; if none (or self-pay plan type), patient qualifies for GFE. Direct table access within PM.

### PM-03 (Appointment Scheduling)

* **Usage:** Scheduling trigger for GFE generation. `pm_good_faith_estimates.appointment_id` references `pm_appointments.id`. Appointment date determines delivery timing (1 vs 3 business days).
* **Contract:** Direct table access within PM. When a self-pay patient is scheduled, GFE generation can be triggered automatically or on demand. Appointment type drives CPT mapping for estimate itemization.

### PM-07 (Charge Capture & Fee Schedules)

* **Usage:** Fee schedule lookup for CPT code rates. GFE itemized amounts come from org fee schedule rates for mapped CPT codes.
* **Contract:** Direct query of `pm_fee_schedules` / `pm_fee_schedule_items` within PM. Appointment type → CPT mapping (via `pm_gfe_appointment_cpt_mapping`) provides codes; PM-07 fee schedule provides rates.

### PM-16 (Patient Statements & Communications)

* **Usage:** GFE delivery channels — portal posting, email delivery, print. Reuse PM-16 communication infrastructure where applicable.
* **Contract:** Direct PM hooks/queries for delivery method recording. Portal delivery uses PM-12 patient portal scope.

***

## Event Contracts

No cross-core events required for PM-20. Internal events (e.g., `gfe_generated`, `gfe_delivered`, `gfe_dispute_filed`) may be added for audit or workflow automation (PM-19); document in [EVENT\_CONTRACTS.md](EVENT_CONTRACTS.md) if added.

***

## API Contracts

No public cross-core APIs. Internal PM hooks and utilities (GFE build logic, business day calculation, variance monitoring) are documented in implementation tasks.

***

## Security & Tenant Isolation

* All PM-20 data scoped by `organization_id`; RLS via `pm_has_org_access` and app-level filter on every mutation.
* PHI: GFE and dispute data are PHI; no PHI in logs or notification payloads; access via RLS and permission keys only.
* Integration with PF-10: no PHI in notification payloads; use **system-generated UUIDs only** (`patient_id`, `gfe_id`, `organization_id`); resolve display names via **authorized API calls in the UI**.
* DELETE restricted to org admins via `pf_is_org_admin(auth.uid(), organization_id)`.
* UPDATE policies include `WITH CHECK` to prevent `organization_id` mutation.

***

## Open Items

* [ ] Confirm PM-19 workflow event registration for `gfe_generated` / `gfe_delivered` if automation is desired.
* [ ] Phase 2: GFE template management per service line/program (deferred from Phase 1).
* [ ] Phase 2: Org-configured holidays for business day calculation (Phase 1 uses calendar weekdays).