Skip to main content

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.

Module: Practice Management (PM)
Feature: Insurance & Eligibility Verification
Version: 1.0.0 | 2026-02-18

​
Permission Reference

Permission KeyDescriptionDefault Roles
pm.insurance.viewView patient insurance policiesorg_admin, site_admin, staff, readonly
pm.insurance.manageCreate / edit / terminate policiesorg_admin, site_admin, staff
pm.eligibility.runRecord eligibility check resultsorg_admin, site_admin, staff
pm.payers.viewView payer directoryorg_admin, site_admin, staff, readonly
pm.payers.manageCreate / edit / deactivate payersorg_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

FieldRequiredNotes
payer_name✅Display name shown in dropdowns
payer_typeOptionalcommercial / medicaid / medicare / tricare / workers_comp / other
electronic_payer_idOptional (needed for PM-15)X12 payer ID for 270/271 eligibility
clearinghouse_payer_idOptional (needed for PM-15)Routing ID for claim submission
phoneOptionalPayer provider services line
websiteOptionalPayer portal URL
is_activeAutoDefaults to true; false hides from dropdowns

​
Soft Delete vs. Deactivate

ActionEffectReversible
Deactivate (is_active = false)Hidden from dropdowns; historical records intactYes — click Activate
Remove (deleted_at set)Fully hidden from all UI; historical policies still reference itAdmin 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

ColumnTypeNotes
organization_idUUIDTenant key — required
patient_idUUIDFK → pm_patients.id
payer_idUUIDFK → pm_payers.id
policy_numberTEXTRequired; unique per org+patient+payer
priority_orderINTEGER1 = primary; COB ordering
statusTEXTactive / inactive / terminated
effective_dateDATERequired
termination_dateDATESet when policy terminated
custom_fieldsJSONBOrg-configurable extensions
deleted_atTIMESTAMPTZSoft 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

ColumnTypeNotes
check_typeTEXTreal_time / batch / manual
response_statusTEXTactive_coverage / inactive / not_found / error / pending
eligibleBOOLEANFinal determination
benefit_detailsJSONBStructured benefit data (see BenefitDetails type)
next_check_dueTIMESTAMPTZWhen to re-verify
request_trace_idTEXTClearinghouse reference (PM-15)
checked_byUUIDUser 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 FunctionPurpose
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

TableSELECTINSERTUPDATEDELETE
pm_payersorg membersorg membersorg members (WITH CHECK)org_admin only
pm_insurance_policiesorg membersorg membersorg members (WITH CHECK)org members
pm_eligibility_checksorg membersorg membersorg 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:
  1. PM-15: Clearinghouse Integration — SFTP/API connectivity to Availity, Change Healthcare, or Trizetto
  2. AHCCCS Online configuration — organization-level AHCCCS provider credentials stored as secrets
  3. Electronic Payer IDs configured on all payers in the directory
Once PM-15 is implemented, the check_type = 'real_time' flow will:
  1. Send a 270 inquiry to the clearinghouse
  2. Parse the 271 response into benefit_details JSONB
  3. 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