> ## 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. # Patient Financial Counseling & Charity Care — Integration Documentation > Spec: PM-32 Status: ✅ Complete Last Updated: 2026-04-03 Owner: PM (Practice Management) **Spec:** [PM-32](../../../specs/pm/specs/PM-32-patient-financial-counseling-charity-care.md)\ **Status:** ✅ Complete\ **Last Updated:** 2026-04-03\ **Owner:** PM (Practice Management) *** ## Overview PM-32 adds a structured financial counseling workflow: income collection, FPL calculation, assistance program referral tracking, and charity care determination. It reads patient data from PM-01, writes insurance policies to PM-02, feeds charity indicator data to PM-16, informs sliding fee decisions to PM-21, and optionally integrates with PM-20 GFE and PF-08 forms. All integrations are **same-core data reads** (PM-01, PM-02, PM-16, PM-20, PM-21) or **platform layer** (PF-08 form snapshot). No direct cross-core imports. No event contracts are required for MVP; PM-02 eligibility trigger is a same-core function call. *** ## Integration Points ### 1. PM-01 (Patient Registration) | Attribute | Detail | | --------- | ------------------------------------------------------------------------------------------ | | Pattern | Same-core data reference (FK) | | Direction | PM-32 → PM-01 (reads patient) | | Data | `pm_financial_counseling_sessions.patient_id → pm_patients.id` | | Notes | Sessions and applications are patient-scoped; patient must exist before counseling session | ### 2. PM-02 (Insurance Policy Management & Eligibility) | Attribute | Detail | | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Pattern | Same-core function call | | Direction | PM-32 → PM-02 | | Trigger | When `pm_assistance_program_referrals.application_status` transitions to `approved` | | Action | Populate `policy_id` FK on referral; call PM-02 eligibility check for the new policy | | Notes | Policy must already exist in `pm_insurance_policies` or be created as part of approval; PM-32 links the referral to the policy; PM-02 owns eligibility verification | **Stub schema (approval action):** ```typescript theme={null} // Called when referral approved interface ApprovalPayload { referralId: string; // pm_assistance_program_referrals.id patientId: string; // pm_patients.id organizationId: string; policyId: string; // pm_insurance_policies.id — must exist } // After: trigger PM-02 eligibility check on policyId ``` ### 3. PM-16 (Patient Statement Generation & Billing Communications) | Attribute | Detail | | -------------- | ---------------------------------------------------------------------------------------------- | | Pattern | Same-core data read (live join) | | Direction | PM-16 → PM-32 tables | | Data | PM-16 queries `pm_charity_care_applications` to determine charity indicator | | Join condition | `approved_at IS NOT NULL AND (expiration_date IS NULL OR expiration_date > CURRENT_DATE)` | | Required index | `idx_pm_charity_care_applications_patient` on `(organization_id, patient_id, expiration_date)` | | Notes | No denormalized flag; no event required; PM-32 owns the data, PM-16 reads it | ### 4. PM-20 (Good Faith Estimate & Price Transparency) | Attribute | Detail | | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | Pattern | Informational reference (no direct data dependency for MVP) | | Direction | Financial counselor workflow context informs GFE process | | Notes | When patient receives financial counseling, counselor may trigger a GFE via PM-20 for out-of-pocket cost estimate; PM-32 does not generate GFEs. PM-20 may read charity status from PM-32 tables in future phases. | ### 5. PM-21 (Sliding Fee Discount Schedule Management) | Attribute | Detail | | ----------------- | --------------------------------------------------------------------------------------------------------------------------------------- | | Pattern | Same-core data read | | Direction | PM-21 → PM-32 tables | | Data | PM-21 reads `fpl_percentage` from most recent authoritative session in `pm_financial_counseling_sessions` to determine sliding fee tier | | Authoritative FPL | Most recent session with `income_verified_at IS NOT NULL`; fallback: most recent by `session_date` | | Notes | PM-21 owns the discount schedule; PM-32 owns the income/FPL data. PM-21 does not write to PM-32 tables. | ### 6. PF-08 (Forms) | Attribute | Detail | | --------- | --------------------------------------------------------------------------------------------------------------------------------------------------- | | Pattern | Platform layer (PF-08 form reference + snapshot) | | Direction | PM-32 → PF-08 (optional) | | Data | `pm_financial_counseling_sessions.form_id → pf_forms.id`; `form_snapshot JSONB` | | Notes | Optional: counselors may use a PF-08 intake form for income/asset collection; snapshot is stored for PHI audit trail even if PF-08 template changes | *** ## Platform Layers Used | Layer | Usage | | --------------------------------------- | ------------------------------------------------------------------------------------------ | | `@/platform/clinical` (patient context) | Read patient context for counseling session; `usePatientContext(patientId)` when available | | `@/platform/permissions` | `useHasPermission('pm.financial_counseling.view')`, `manage`, `approve_charity` | | `PF-30` (RBAC) | Permission keys seeded: `pm.financial_counseling.view`, `manage`, `approve_charity` | | `PF-10` (Notifications) | 30-day charity expiration reminder; annual review reminder | *** ## Event Contracts ### Events Consumed #### `pm_cost_estimate_generated` (from PM-48) * **Publisher:** PM-48 (Patient Cost Estimation & Financial Clearance) * **Event Name:** `pm_cost_estimate_generated` * **Version:** 1.0 * **Payload Schema:** ```typescript theme={null} { estimate_id: string; patient_id: string; organization_id: string; patient_estimated_responsibility: number; service_type: string; } ``` * **Subscription Rules:** Conditional — subscribe only when `patient_estimated_responsibility` exceeds the configured threshold (from PF-96 jurisdiction profile or `pm_module_settings.financial_clearance_threshold`) * **Threshold Behavior:** * Read `financial_clearance_threshold` from jurisdiction profile (PF-96) if available * Fallback to `pm_module_settings.financial_clearance_threshold` (default: \$1,000) * Auto-create PM-32 referral record when threshold exceeded * **Delivery Semantics:** At-least-once; idempotent via `estimate_id` (check for existing referral before creating) * **Retry Policy:** Standard retry with exponential backoff (3 attempts) * **Idempotency Keys:** `estimate_id` — prevent duplicate referrals * **ACL/Topic:** `pm.cost_estimates` topic * **Purpose:** Auto-route patients to financial counseling when estimated responsibility exceeds threshold * **Status:** 📝 Planned **Potential future events (post-MVP):** | Event | Producer | Consumers | Notes | | --------------------------------- | -------- | --------- | ---------------------------------------------------------------------------------------- | | `pm_charity_approved` | PM-32 | PM-16, FA | Notify statement generation and financial accounting of charity determination. Deferred. | | `pm_assistance_referral_approved` | PM-32 | PM-02 | Trigger eligibility check when referral status = approved. Currently a same-core call. | *** ## API Contracts No external API contracts for MVP. All data flows are internal (same-core or platform layer). **Future:** AHCCCS direct submission API (deferred per Out of Scope in PM-32 spec). *** ## Security * All tables behind `pm_has_org_access` SECURITY DEFINER RLS. * `pm.financial_counseling.approve_charity` is supervisor-level; not assigned to standard counselor role by default. * Income/financial data is PHI; no PHI written to logs; access via RLS + RBAC only. *** ## Pending Contracts No pending contracts for MVP. See PENDING\_CONTRACTS.md if future event contracts are needed. *** ## References * [PM-32 Spec](../../../specs/pm/specs/PM-32-patient-financial-counseling-charity-care.md) * [PM-16 Integration](./patient-statement-generation-billing-communications-integration.md) * [PM-20 Integration](./good-faith-estimate-price-transparency-integration.md) * [CROSS\_CORE\_INTEGRATIONS.md](./CROSS_CORE_INTEGRATIONS.md) * [CONTRACT\_VALIDATION\_CHECKLIST.md](./CONTRACT_VALIDATION_CHECKLIST.md)