Insurance

What it does

Insurance is the platform's payer-side module. It covers payer and plan registry, member coverage administration, eligibility checking, claims adjudication, and remittance with provider-side reconciliation.

Where to find it

• Insurance → Payers — /insurance/payers
• Insurance → Eligibility — /insurance/eligibility
• Insurance → Adjudication — /insurance/adjudication
• Insurance → Remittance — /insurance/remittance

You need insurance.payer.read to open the registry screen. Plan and member tabs additionally require insurance.plan.read and insurance.member.read. The eligibility screen requires insurance.eligibility.read to view and insurance.eligibility.write to run checks. The adjudication screen requires insurance.adjudication.read to view the worklist and line decisions; insurance.adjudication.write is required for manual review actions when the backend exposes them. The remittance screen requires insurance.remittance.read to view runs, payment advice, and reconciliation; insurance.remittance.write is required to create and post remittance runs. If the Insurance section is missing from your sidebar, you either lack the route permission or the insurance module is not activated for your facility.

Payer registry

1. Open Insurance → Payers.
2. On the Payers tab, choose Register payer.
3. Enter the payer name, code, and optional contact details.
4. Choose Available to — tenant-wide or this facility only — then save.

The table lists every payer visible in your scope, who published it, and whether it is tenant-wide or facility-local.

Plans and benefit schedules

1. Switch to the Plans tab.
2. Choose Register plan (requires at least one payer).
3. Select the payer, enter plan code/name, effective dates, and ISO currency.
4. Add one or more benefit schedule rows. Each row needs a benefit category from the concept dictionary — search by name or code, never type a free-text category.
5. Set covered/excluded, copay, coinsurance, limits, and prior-authorisation flags per row.

Benefit categories are validated server-side against the concept engine. An unknown concept id is rejected with a message naming the id.

Member coverage

1. Switch to the Member coverage tab.
2. Choose Add coverage (requires at least one plan).
3. Search for the person, choose the plan, and enter policy/member numbers and effective dates.
4. Save. Coverage is tied to your signed-in facility context on the backend.

Overlapping active coverage for the same person and plan is rejected by the server.

Eligibility check

1. Open Insurance → Eligibility.
2. Choose Member coverage row (pick an existing coverage row) or Person (the backend resolves active coverage for the service date).
3. Enter the service date for the planned care.
4. Add one or more benefit categories using the concept dictionary search — the same categories configured on plan benefit schedules.
5. Choose Check eligibility.

The Coverage answer panel shows, for each requested benefit:

• Status — Covered, Limited, or Excluded (never a bare "not covered").
• Reason — the rule or exclusion that produced the answer.
• Limits and usage — annual limit, amount used, and remaining when the plan tracks them.

When no active coverage exists on the service date, the panel shows a clear No active coverage message with the server reason — not a generic error.

Claims adjudication

1. Open Insurance → Adjudication.
2. The Worklist tab lists all claims in payer-side status (received, pended, in review, adjudicated, reversed).
3. Click a row to open Decision detail — per-line outcomes with coded denial reasons (never a bare "denied" badge alone).
4. Switch to Exception review for claims pended because rules could not decide cleanly (no active coverage, missing prior auth, duplicate paid claim, amount above review threshold, and similar). These are not auto-denied — the alert explains the exception reason and any workflow instance id.

Each line shows the service concept from the dictionary, claimed/allowed amounts, copay, deductible, coinsurance, and patient responsibility when the server returns them.

Adjudication history is append-only: re-adjudication adds a new row linked to the prior decision.

Remittance and provider reconciliation

1. Open Insurance → Remittance.
2. On Remittance runs, review draft and posted payment advice runs. Each row shows the remittance reference, payer, payment date, status, total paid, and line count.
3. Choose Create remittance run (requires write permission). Select the payer and payment date, then save a draft run. The server groups adjudicated claims for that payer into remittance lines.
4. For a Draft or Post failed run, choose Post to send approved amounts to the provider billing engine. A failed post-back stays retryable and shows the server reason — it is never silently swallowed.
5. Open Payment advice after selecting a run to see remittance lines: payer claim number, adjudication outcome, approved and patient-responsibility amounts, post-back status, and decision reason.
6. Open Provider reconciliation to compare payer remittance lines against provider billing insurance claims. Matched rows show the same approved amount on both sides; mismatches and missing provider claims are flagged. Click the provider claim link to open Billing → Insurance claims detail.

The remittance reference is carried on both payer and provider rows so finance can reconcile three books (payer decision, provider claim, ERP ledger) to one number.

Permissions

Action	Permission
View payer tab	insurance.payer.read
Register/edit/retire payers	insurance.payer.write
View plans tab	insurance.plan.read
Register/edit/retire plans	insurance.plan.write
View member coverage tab	insurance.member.read
Add/edit/retire coverage	insurance.member.write
Open eligibility screen	insurance.eligibility.read
Run eligibility checks	insurance.eligibility.write
Open adjudication worklist	insurance.adjudication.read
Manual review / re-adjudicate (when exposed)	insurance.adjudication.write
Open remittance screen	insurance.remittance.read
Create / post remittance runs	insurance.remittance.write

Troubleshooting

Symptom	Likely cause
The Insurance section is missing	No insurance.payer.read, or the insurance module is not activated.
/insurance/payers shows a denied state	Same as above — the permission gates the route.
Plans tab says you lack permission	Missing insurance.plan.read.
Register plan is disabled	No payer exists yet, or you lack insurance.plan.write.
Benefit save fails naming a concept id	The concept does not exist or is voided — pick a valid dictionary entry.
Member save fails on overlap	Another active coverage row exists for that person and plan.
Eligibility nav missing	No insurance.eligibility.read, or the insurance module is not activated.
Check eligibility disabled	Missing insurance.eligibility.write.
Eligibility answer shows excluded	Read the Reason line — it names the plan rule; status badge shows Excluded or Limited.
No active coverage on service date	Expected when coverage ended or has not started — not a server error.
Adjudication nav missing	No insurance.adjudication.read, or the insurance module is not activated.
Worklist empty	No claims submitted yet, or backend M18-004 not deployed.
Line shows Denied	Read the reason text and reason code beneath — adjudication never uses bare denial.
Exception review claim	Status Pended for review — open the exception tab; claim is not auto-denied.
Remittance nav missing	No insurance.remittance.read, or the insurance module is not activated.
Remittance runs empty	No adjudicated claims ready for payment, or backend M18-005 not deployed.
Post failed on remittance	Read the post-back failure alert — retry Post when billing is available.
Reconciliation Amount mismatch	Payer approved amount differs from provider claim — investigate before closing books.
Reconciliation Provider claim missing	Post-back did not link a billing claim — check remittance reference on both sides.