Insurance &
Claim Management
Campus-scoped providers, negotiated price rates, pre-authorization, claims, and settlements under /dashboard/insurance. Billable tariffs reprice invoices without rewriting doctor-share cash basis — see Billing.
Purpose
Recover revenue from insurers/TPAs: register providers, maintain tariffs, obtain pre-auth, submit/approve/reject/settle claims, and reprice eligible invoices to negotiated rates — while patient prints and doctor-share math stay correct.
Who uses it
- → Insurance / TPA coordinators
- → Billing supervisors (apply-insurance on invoices)
- → Claims officers (submit / approve / settle)
- → Finance AR (Finance → Claims queue read view)
Claim Lifecycle
Providers & Tariffs
Register campus insurers; maintain InsuranceProviderPriceRate rows (target kind + catalog UUID, unit price, effective dates).
Pre-Authorization
Create pre-auth for planned high-cost care; track pending/approved/partial/denied; use before expiry.
Apply Insurance & Claim
Reprice invoice billable lines from mapped tariffs; build claim from encounter/invoice; submit → approve/reject.
Settle & Reconcile
Settle approved claims; doctor-share accrues only when invoice is paid (cash or settle). Finance Claims queue ages outstanding AR.
Features
Provider Management
Campus registry of insurers/TPAs the hospital works with.
Each payer has different contacts, submission habits, and tariffs.
insurance:manage-providers | manage; active/inactive; Working-in stamp.
Price Rates
Negotiated unit prices per catalog/service target on a provider.
Billable invoice amounts must match contracted tariffs.
/dashboard/insurance/providers/[id]/price-rates — insurance:price-rates:manage (+ geo).
Billable vs Share Base
Tariffs change unitPrice/totalPrice; shareBase* stays cash for doctor-share.
Clinician share must not inflate/deflate with insurer discounts.
Documented in docs/info/INSURANCE-BILL-VS-SHARE-BASE.md; prints/SMS/KPIs use billable.
Pre-Authorization
Advance approval requests with validity windows.
Denied pre-auth often means non-payment for elective procedures.
/dashboard/insurance/pre-auths; expired pre-auths cannot support billing.
Claims & Settlements
Draft → submit → approve/reject → settle lifecycle with rejection reasons.
Outstanding claims are major AR risk.
insurance:submit|approve|reject|settle; Finance claims-queue for aging follow-up.
Reporting & Evidence
Exports, pricing audits in compliance bundle, realtime insurance_updates sockets.
Governance and training need durable tariff/apply-insurance evidence.
insurance:export does not alone open hub; pricing audits listed in compliance export docs.
Technical Architecture
| Field | Type | Institutional Role |
|---|---|---|
| branchId | UUID | Clinical campus — must match invoice/claim. |
| claimStatus | Enum | Draft, submitted, approved, rejected, settled/paid. |
| unitPrice | Decimal | Tariff / billable amount after apply-insurance. |
| shareBase* | Decimal | Cash share base on invoice lines (unchanged by tariff). |
Note: Sensitive fields use AES-256 field-level encryption where applicable.
Governance & Power
insurance:viewinsurance:submitinsurance:preauth:submitinsurance:approveinsurance:rejectinsurance:settleinsurance:manage-providersinsurance:price-rates:manageTariff ready
Campus provider + price rates configured.
Pre-auth / care
Approve high-cost care; deliver services.
Reprice & claim
Apply-insurance then submit claim.
Settle
Payment received; invoice paid; share may accrue.