Encore OS — Documentation

Permission Reference

Permission Key	Description	Default Roles
`pm.insurance.view`	View patient insurance policies	org_admin, site_admin, staff, readonly
`pm.insurance.manage`	Create / edit / terminate policies	org_admin, site_admin, staff
`pm.eligibility.run`	Record eligibility check results	org_admin, site_admin, staff
`pm.payers.view`	View payer directory	org_admin, site_admin, staff, readonly
`pm.payers.manage`	Create / edit / deactivate payers	org_admin, site_admin, staff

Permissions are managed via Platform Foundation → Role Permissions (pf_role_permissions). Custom roles can be configured via the admin UI.

Payer Directory Setup

Required Fields

Field	Required	Notes
`payer_name`	✅	Display name shown in dropdowns
`payer_type`	Optional	commercial / medicaid / medicare / tricare / workers_comp / other
`electronic_payer_id`	Optional (needed for PM-15)	X12 payer ID for 270/271 eligibility
`clearinghouse_payer_id`	Optional (needed for PM-15)	Routing ID for claim submission
`phone`	Optional	Payer provider services line
`website`	Optional	Payer portal URL
`is_active`	Auto	Defaults to true; false hides from dropdowns

Soft Delete vs. Deactivate

Action	Effect	Reversible
Deactivate (`is_active = false`)	Hidden from dropdowns; historical records intact	Yes — click Activate
Remove (`deleted_at` set)	Fully hidden from all UI; historical policies still reference it	Admin SQL only

Recommendation: Use Deactivate for payers that are no longer contracted. Use Remove only for payers added by mistake with no associated policies.

Insurance Policy Data Model

`pm_insurance_policies` Schema

Column	Type	Notes
`organization_id`	UUID	Tenant key — required
`patient_id`	UUID	FK → `pm_patients.id`
`payer_id`	UUID	FK → `pm_payers.id`
`policy_number`	TEXT	Required; unique per org+patient+payer
`priority_order`	INTEGER	1 = primary; COB ordering
`status`	TEXT	active / inactive / terminated
`effective_date`	DATE	Required
`termination_date`	DATE	Set when policy terminated
`custom_fields`	JSONB	Org-configurable extensions
`deleted_at`	TIMESTAMPTZ	Soft delete — null = active

Unique Constraint

A composite unique constraint prevents duplicate policies:

UNIQUE (organization_id, patient_id, payer_id, policy_number)

If staff try to add the same policy twice, they will see a validation error.

Eligibility Check Data Model

`pm_eligibility_checks` Schema

Column	Type	Notes
`check_type`	TEXT	real_time / batch / manual
`response_status`	TEXT	active_coverage / inactive / not_found / error / pending
`eligible`	BOOLEAN	Final determination
`benefit_details`	JSONB	Structured benefit data (see BenefitDetails type)
`next_check_due`	TIMESTAMPTZ	When to re-verify
`request_trace_id`	TEXT	Clearinghouse reference (PM-15)
`checked_by`	UUID	User who recorded the check

Eligibility checks are append-only in practice — no delete RLS policy exists. Historical checks are retained for audit.

RLS Security Model

All three tables use FORCE ROW LEVEL SECURITY with SECURITY DEFINER helper functions to prevent RLS recursion:

Helper Function	Purpose
`pm_has_org_access(org_id, user_id)`	Delegates to `pf_has_org_access` — tenant isolation
`pm_can_access_insurance_policy(user_id, policy_id)`	Policy-scoped SELECT check
`pm_can_modify_insurance_policy(user_id, policy_id)`	Policy-scoped UPDATE check

Policy Summary

Table	SELECT	INSERT	UPDATE	DELETE
`pm_payers`	org members	org members	org members (WITH CHECK)	org_admin only
`pm_insurance_policies`	org members	org members	org members (WITH CHECK)	org members
`pm_eligibility_checks`	org members	org members	org members (WITH CHECK)	— (no hard delete)

Phase 2: Real-Time Eligibility (PM-15)

Phase 1 supports manual eligibility entry only. Real-time 270/271 transactions require:

PM-15: Clearinghouse Integration — SFTP/API connectivity to Availity, Change Healthcare, or Trizetto
AHCCCS Online configuration — organization-level AHCCCS provider credentials stored as secrets
Electronic Payer IDs configured on all payers in the directory

Once PM-15 is implemented, the check_type = 'real_time' flow will:

Send a 270 inquiry to the clearinghouse
Parse the 271 response into benefit_details JSONB
Record the check automatically with request_trace_id from the clearinghouse

AHCCCS-Specific Configuration (Deferred to PM-15)

AHCCCS member ID is stored on pm_patients.ahcccs_member_id (PM-01)
AHCCCS payer type = medicaid in the payer directory
AHCCCS is always the payer of last resort (highest priority_order number)
AHCCCS Online eligibility portal: https://www.healthearizonaplus.gov

Domain Events

`pm_eligibility_verified`

Published to the platform event bus after every eligibility check insert. Payload schema:

{
  "check_id": "string",
  "patient_id": "string",
  "policy_id": "string | null",
  "organization_id": "string",
  "eligible": "boolean",
  "response_status": "string",
  "check_type": "string",
  "next_check_due": "string | null",
  "timestamp": "string"
}

Downstream consumers (planned):

CL-01: Update patient chart coverage indicator
PM-08: Gate claim submission on eligibility status

Insurance & Eligibility Verification — User Guide Prior Authorization — User Guide

Guides

Patient Registration & Portal

Scheduling & Resources

Eligibility & Authorizations

Claims & Clearinghouse

Revenue Cycle & Charges

Payments & Statements

Contracts & Value-Based Care

Estimates & Financial Counseling

Payers & Provider Enrollment

Compliance & Audit

Insurance & Eligibility Verification — Admin Guide

Permission Reference

Payer Directory Setup

Required Fields

Soft Delete vs. Deactivate

Insurance Policy Data Model

`pm_insurance_policies` Schema

Unique Constraint

Eligibility Check Data Model

`pm_eligibility_checks` Schema

RLS Security Model

Policy Summary

Phase 2: Real-Time Eligibility (PM-15)

AHCCCS-Specific Configuration (Deferred to PM-15)

Domain Events

`pm_eligibility_verified`

​Permission Reference

​Payer Directory Setup

​Required Fields

​Soft Delete vs. Deactivate

​Insurance Policy Data Model

​pm_insurance_policies Schema

​Unique Constraint

​Eligibility Check Data Model

​pm_eligibility_checks Schema

​RLS Security Model

​Policy Summary

​Phase 2: Real-Time Eligibility (PM-15)

​AHCCCS-Specific Configuration (Deferred to PM-15)

​Domain Events

​pm_eligibility_verified

Permission Reference

Payer Directory Setup

Required Fields

Soft Delete vs. Deactivate

Insurance Policy Data Model

`pm_insurance_policies` Schema

Unique Constraint

Eligibility Check Data Model

`pm_eligibility_checks` Schema

RLS Security Model

Policy Summary

Phase 2: Real-Time Eligibility (PM-15)

AHCCCS-Specific Configuration (Deferred to PM-15)

Domain Events

`pm_eligibility_verified`