Apex MediSuite

Getting started#

Apex MediSuite is a US healthcare orchestration platform that runs Prior Authorization (PA) and Value-Based Care (VBC) on one decision spine. Instead of two disconnected products, a single patient record, workflow engine, versioned policy library and append-only audit trail sit underneath both modules — so an authorization is a step inside a care journey, a care gap knows when it is blocked on a payer decision, and every state change either side makes is visible to the other in real time.

The platform is API-first: every screen you see is a projection of server-side state, and every rule — who may act, which transitions are legal, what a denial requires — is enforced on the server, never in the browser. That design has a practical consequence for you as a user: if the UI lets you press a button that the rules forbid, the server refuses and tells you why. Several parts of this manual invite you to try exactly that, because watching the platform refuse an illegal action is the fastest way to understand how it protects the people in it.

The demo environment#

Signing in#

1. Open /app. You will see the sign-in screen with the synthetic-data demo banner and the platform points (CMS-0057-F-aligned SLA clocks, Governed AI, Defensible by design).
   What you should seeAn email + password form, and a click-to-fill panel listing the five demo roles.
2. Enter one of the credential pairs from the table below and press Sign in.
   What you should seeThe app shell loads with a left navigation tailored to your role — a Care Manager lands on My Work; a UM Nurse or Medical Director lands directly on the Review Queue.
3. Sessions use short-lived JWT access tokens (15 minutes) with a refresh token behind them. If a request returns 401 after a long idle period, sign in again.

Demo credentials#

Five seeded users cover the whole demo. Passwords are published intentionally — this is a synthetic environment.

Your first session, by role#

• Care Manager (jane@demo.aco) — start in My Work: one Critical task is waiting (post-ED follow-up for John Doe). Open his 360, then follow the VBC guide end-to-end on Sarah Martinez's retinal-exam gap — it is the one that requires a PA, so you will see both modules cooperate.
• VBC Manager (alex@demo.aco) — start on the Dashboard: every KPI is computed live from the same rows its drill-down shows, so numbers always reconcile. Then browse Patients and open a 360.
• UM Nurse (nurse@demo.payer) — open the Review Queue. If it is empty, have the Care Manager submit a PA first (how). Run the AI advisory, approve or pend — then press Deny and read the server's refusal. That refusal is the product's compliance story in one screen.
• Medical Director (md@demo.payer) — open the same queue and complete an adverse determination properly: 5-state criterion outcomes, a specific reason code and text, your MD credential recorded on the trace.
• Auditor (audit@demo.aco) — open Authorizations and view any PA's decision trace. Note what you cannot do: no review/decide buttons appear, and any write you attempt (say, Start Intervention on an open gap) is refused by the server with 403. Read-only is enforced server-side, not by the UI.

Core concepts#

Six ideas explain the whole platform. Everything in the role guides below is a combination of these.

Patient 360#

The Patient 360 is the single clinical workspace for one member: identity and coverage, the risk tier (HIGH / RISING / MEDIUM / LOW) with the evidence behind it, all open and closed care gaps, and every intervention with its full event timeline. Risk is never a bare score — each contributing factor carries its source and date (e.g. HbA1c 9.4% · lab · 2026-06-14), and the risk model version (apex-risk v3.2 in the demo) is displayed with it, so the number is explainable and reproducible.

Care gaps & their states#

A care gap is a measurable difference between recommended and delivered care, tied to a versioned quality measure (e.g. CDC-HBA1C, measure package MY2026.1). Every gap answers two questions on its face: why is it open (the evidence that opened it) and what closes it (the clinical evidence the measure requires). A gap moves through these states:

Intervention lifecycle#

An intervention is the unit of care-team work on one gap: who owns it, what has happened, what comes next. Its state machine is enforced server-side — any transition not in this diagram returns 409 Illegal intervention transition.

Teal = the states involved in the cross-module handshake. Dark = terminal success. Red = exception outcomes.

Prior Authorization lifecycle#

A PA request has eleven states. In the demo environment intake validation passes synchronously, so a successful submission lands directly in IN_REVIEW with its SLA clock already running.

Rule & policy packages#

Coverage rules are data, not code. A rule package (e.g. UHC-MA-EYE-014) is versioned and effective-dated, keyed by payer + line of business + service codes, and carries the criteria themselves — each with an ID, plain-language text and the evidence type that satisfies it. The policy resolver picks the newest active version matching the member's coverage and the requested CPT. When a PA is created, the package key and version are snapshotted onto the request, so the decision is always judged — and can always be replayed — against the exact criteria in force at submission, even after the package is updated.

The audit trail#

Every consequential action — sign-ins and failures, every patient view, every transition, every decision — appends an event to a hash-chained, append-only audit log: each row carries the hash of the previous row, so any tampering breaks the chain, and an integrity self-check can recompute it end-to-end at any time. Events record the actor, role, object, patient, structured detail (criteria version, credential, denial code…) and a correlation ID that ties one user action to every row it produced. The current correlation ID is shown in the app's top bar — quote it when reporting an issue and the operator can reconstruct your exact request.

Roles & permissions#

Ten roles are defined. A role is a fixed set of permissions checked on every API call — the UI merely hides what you cannot do; the server is what refuses. The five demo users cover the roles marked below; the others exist in the model for production deployments.

Permission matrix#

= has a seeded demo user. admin.all satisfies any permission check — platform_admin effectively holds every permission. Note that medical_director is the only role holding pa.decide, and only care_manager, provider and pa_coordinator can create PAs.

The credential rule#

Tenant isolation is equally absolute: every query filters by the tenant in your token. An object in another tenant returns 404 — the platform never reveals whether it exists.

VBC guide — care manager & VBC manager walkthroughs#

Sign in as jane@demo.aco (Care Manager) or alex@demo.aco (VBC Manager) to follow along.

The Dashboard

1. Open Dashboard in the left navigation.
   What you should seeKPI tiles — Patients, High Risk, Open Care Gaps, Active Interventions, Open Tasks — computed live from the same rows their drill-downs show. Change anything anywhere in the app and the numbers move with it; they are never hardcoded.

The Patients list

1. Open Patients.
   What you should seeThe tenant-scoped roster — in the demo, John Doe and Sarah Martinez, both HIGH risk, with member ID, PCP and program. A note reminds you that every view is audited with your identity and a correlation ID — that is literally true; check the audit trail as the Auditor later.

Patient 360 & risk evidence

1. Click a patient row to open their 360.
   What you should seeThree panels: the header with DOB, member ID and risk badge; a "Risk — why?" box listing each factor with source and date (for John Doe: HbA1c 9.4% · lab, ED visit · adt, Missed follow-up · scheduling) plus the model version apex-risk v3.2; then Care Gaps and Interventions.
2. Read a gap's row: measure key and version, status, priority, and the why-open narrative (Sarah: "No retinal exam in 24 months; HbA1c 10.1%."). Every gap justifies itself.

Starting an intervention (with automatic PA check)

1. On an OPEN gap, click Start Intervention.
2. Before creating anything, the platform silently runs a PA requirement check for the gap's service code against the member's active coverage (a CRD-style discovery call — see the PA guide).
   What you should seeFor Sarah's retinal exam (CPT 92250) the toast reads "Intervention created — PA REQUIRED under UHC-MA-EYE-014 v3". For a service with no matching policy the toast reads "no PA required (policy trace logged)" — the check itself is audited either way.
3. The intervention appears in the Interventions panel in state IDENTIFIED, its first timeline event reading "created — context inherited from care gap". The gap moves to IN_PROGRESS.
4. Try clicking Start Intervention again for the same gap: the server answers 409 Active intervention exists. One gap, one active intervention — duplicates are blocked at the API.

Outreach → engaged → schedule

1. On the IDENTIFIED intervention, click Begin outreach → state becomes OUTREACH.
2. Click Patient responded → ENGAGED. Every click appends a timestamped event to the timeline.
3. Click Schedule → SCHEDULED — unless a linked PA is still pending. If you launched a PA that has not been decided, the server refuses with 409 Scheduling gated: PA-2026-xxxxx is IN_REVIEW.
   What you should seeWhile the PA is pending the intervention sits in AWAITING_AUTH with a stopwatch chip ("awaiting payer decision") and no schedule button at all. The moment the PA is approved, the intervention flips to AUTH_APPROVED automatically and the button returns as Schedule (auth on file).

Recording completion evidence & auto-closure

1. On a SCHEDULED intervention, click Record completion evidence. This simulates the EHR/claims completion feed a production deployment receives automatically.
2. Choose the evidence type — lab, encounter or procedure — and enter the CPT observed (e.g. 83036 for the HbA1c gap, 92250 for the retinal exam), then Send event.
3. The closure rule is deterministic: the evidence type must be clinical and the CPT (or measure key) must match the gap's measure.
   What you should seeOn a match: "Care gap closed automatically; evidence recorded" — the intervention passes through COMPLETED to GAP_CLOSED and the gap becomes CLOSED. On a mismatch: "Evidence insufficient — gap stays IN_PROGRESS (logged)" and an audit event records exactly what was offered and rejected.
4. Try sending mismatched evidence on purpose (wrong CPT). The gap does not close — and notice that an approved PA never closed it either. Approval changes permission, evidence changes state.

My Work

1. Open My Work.
   What you should seeA prioritized queue where every task answers two questions in its own columns: why am I seeing this (e.g. "Post-ED follow-up + HbA1c gap (ED 08/02, HbA1c 9.4)") and what should I do ("Start Intervention"), with priority and due date. An Open 360 button jumps straight to the patient.

Prior Authorization guide#

Submission side: sign in as jane@demo.aco. Review side: nurse@demo.payer, then md@demo.payer.

The requirement check

Before any request is drafted, POST /pa/requirement-check answers the question providers ask first: does this service need prior authorization under this member's plan? The resolver matches the member's active coverage (payer + line of business) and the CPT code against the versioned policy library and returns a three-valued answer: yes, no, or unknown when no policy matches — unknown is never collapsed into "no". The response names the governing package and version (UHC-MA-EYE-014 v3 for Sarah's retinal exam) and lists the documentation types its criteria demand, and the whole lookup is written to the audit trail. In the UI this runs automatically when you start an intervention; the pattern mirrors Da Vinci CRD (Coverage Requirements Discovery).

Launching a PA from an intervention

1. On an intervention in IDENTIFIED, click Launch PA.
   What you should seeA form with the member line read-only and the service CPT pre-filled from the care gap — context is inherited, not re-typed. You supply the ICD-10 diagnosis and choose urgency: Standard — 7-day SLA or Expedited — 72h SLA.
2. Click Submit PA. The request is created with an idempotency key, so a double-click or a network retry returns the same PA instead of creating a duplicate.
   What you should seeA toast with the new reference and its deadline: "PA-2026-xxxxx submitted — SLA due …". The linked intervention parks in AWAITING_AUTH and the gap shows AWAITING_AUTH too.
3. The policy package and version in force are snapshotted onto the request, and the submission passes intake validation into IN_REVIEW with the decision clock running.

The review queue & SLA clocks

Sign in as the UM Nurse. The Review Queue lists every PA in the tenant, newest first: reference, patient, CPT/ICD-10, status, the SLA due timestamp for anything IN_REVIEW, the policy snapshot and the auth number once issued. Decision deadlines are stamped at submission — 72 hours for expedited requests, 7 calendar days for standard — matching the CMS-0057-F timeframes in force since January 1, 2026. The clock is data on the request itself, so it survives into reporting and the audit trail.

AI advisory — what it does and cannot do

1. Click Review on an IN_REVIEW PA, then Run criteria analysis in the AI advisory box.
   What you should seeAn advisory panel labeled with the model and version (apex-um v1.8) and the tag "cannot decide" — e.g. "Criteria package evaluated: 3/3 MET on available evidence. Approval probability high. Advisory only." The toast confirms: "AI advisory recorded — no state change".
2. What happened server-side: an advisory row was appended to the decision trace carrying the model version, criteria version and per-criterion outcomes. What cannot happen: the advisory endpoint has no code path that touches PA state. The AI can read, evaluate and recommend — approving, pending and denying are exclusively human actions, and denial is exclusively a credentialed physician's action.

Approve, pend — and the deny guard

1. In the review dialog, record the criterion outcomes. Outcomes are 5-state — MET, NOT_MET, UNKNOWN, NOT_APPLICABLE, NEEDS_HUMAN_REVIEW — never collapsed to yes/no.
2. As the UM Nurse: Pend (needs more information; the PA can re-enter review later) and Approve both succeed — approval issues an auth number valid for 180 days.
3. Still as the nurse, press Deny.
   What you should seeThe dialog itself warns you: "You are not a physician: the server will refuse a denial regardless of this UI." And it does — 403 Adverse determinations require a medical director. The button exists so you can confirm the server enforces the rule.
4. Sign in as the Medical Director and deny properly: enter a specific denial reason code and text (e.g. MED-NEC-001 + the clinical rationale). Leave the reason empty and the server answers 422 Denial requires a specific reason code and text — generic denials are rejected by design, matching the CMS-0057-F specific-denial-reason requirement.
   What you should seeOn a valid denial: PA → DENIED with the reason stored on the request, your MD:Ophthalmology credential recorded on the decision row, and the linked intervention logging a pa.denied event flagging that an appeal or alternative plan is required.

Reading the decision trace

Open any PA's Detail view. Below the service, policy snapshot and auth/denial fields sits the decision trace: one row per review action, in order. Each row shows its kind — ai_advisory (with model version) or human (with the reviewer's credential) — the disposition, and the criteria version it was judged against. Together with the hash-chained audit events behind it, the trace makes every decision reproducible: inputs, rule version, evidence outcomes, actor and credential, timestamps. This is the artifact an auditor, an accreditor or opposing counsel would read — and the platform is built so it reads well.

The golden path — end to end#

This is the sequence that shows both modules cooperating on one journey. Run it with Sarah Martinez's Diabetic Retinal Exam gap — the seeded scenario where the service (CPT 92250) requires prior authorization under UHC-MA-EYE-014 v3.

API reference#

All endpoints are JSON over HTTPS. Authenticate with JWT bearer tokens: sign in to receive an access token (15-minute lifetime) and a refresh token, then send Authorization: Bearer <access_token> on every call and exchange the refresh token for a new pair as needed. The permission column names the permission the server checks — see the matrix for which roles hold it.

Operations extras: GET /ready (database readiness probe) and GET /ops/audit-verify (recomputes the audit hash chain end-to-end and reports integrity). Every response carries an X-Correlation-ID header matching the audit rows the request produced.

Troubleshooting#

Most "errors" in this platform are guards doing their job. Here is what each status means and what to do.

Glossary#

Prior Authorization (PA)

A payer's advance approval that a service is medically necessary and covered before it is delivered. The unit of work in the PA module.

Utilization Management (UM)

The payer discipline of reviewing care requests against clinical criteria — the review queue, nurses and medical directors in this platform.

Adverse determination

A denial (or partial approval) of requested care. Here it requires a physician credential and a specific reason — never automation.

SLA / TAT

Service-level agreement / turnaround time — the decision deadline on a PA. Stamped at submission: 72 hours expedited, 7 calendar days standard, per CMS-0057-F.

CMS-0057-F

The CMS Interoperability and Prior Authorization final rule. Its decision timeframes and specific-denial-reason requirements have been in force since January 1, 2026; its API requirements (Prior Authorization, Patient Access, Provider Access, Payer-to-Payer) take effect January 1, 2027.

Care gap

A measurable difference between recommended and delivered care for one member, tied to a versioned quality measure and closable only by clinical evidence.

HEDIS

A widely used set of healthcare quality measures. The demo's measure keys (e.g. CDC-HBA1C, EED-RETINAL) follow this style of gap logic with explicit measure versions.

FHIR

Fast Healthcare Interoperability Resources — the modern HL7 standard for healthcare data exchange. The platform's integration surface is designed around FHIR R4 patterns.

CRD / DTR / PAS

The Da Vinci implementation guides for electronic PA: Coverage Requirements Discovery (is PA needed?), Documentation Templates & Rules (collect the evidence), Prior Authorization Support (submit and track). The requirement-check → launch → review flow mirrors this pattern, which the HTI-4 rule is building into certified EHRs.

X12 278

The legacy EDI transaction for PA requests/responses. Channel provenance on each PA records whether it arrived via FHIR, X12 278 or portal.

NCD / LCD

National / Local Coverage Determinations — Medicare's published coverage policies; the kind of source content a production policy library encodes as rule packages.

Rule package

A versioned, effective-dated bundle of coverage criteria keyed by payer, line of business and service codes. PAs snapshot the version they were judged under.

Gold carding

State-law programs exempting consistently-approved providers from PA for certain services — one reason PA applicability must be configuration, not code.

Idempotency key

A client-supplied token on PA creation guaranteeing that retries return the original request instead of creating duplicates.

Decision trace

The ordered record of every review action on a PA — kind (machine / human / AI advisory), criteria version, 5-state outcomes, credential, model version — sufficient to reproduce the decision later.

Correlation ID

A per-request identifier stamped on responses, logs and audit rows, tying one user action to everything it caused.

ACO

Accountable Care Organization — a provider group accountable for the total cost and quality of a population. The demo tenant is an ACO.

Medicare Advantage (MA)

Medicare benefits administered by private plans — the line of business on the demo members' coverage, and a primary target of CMS-0057-F.

TCOC / PMPM

Total cost of care / per-member-per-month — the financial lenses of value-based contracts that population dashboards ultimately roll up to.

Risk stratification

Ranking members by predicted need (HIGH / RISING / MEDIUM / LOW here), with each factor carrying provenance and the scoring model versioned.