Claim Risk Platform Capabilities Guide (Layman's Version)

What This Platform Is

This platform is an API-first system that helps healthcare billing teams catch payment risk before claims are submitted, estimate what they should get paid, and generate cleaner appeals when claims are denied.

In plain terms: it helps you avoid losing money from preventable billing mistakes.

The Problem Space in Plain English

Healthcare billing is complicated because every claim depends on many moving parts:

• The procedure code must match the diagnosis.
• Prior authorization rules vary by payer.
• Contract rules and payment behavior vary by payer and plan.
• Small documentation misses can lead to denials.
• Denials are expensive to fix after the fact.

Most organizations still do this with manual checks, spreadsheet logic, and staff experience. That works, but it is slow, inconsistent, and hard to scale.

Why this matters

• Preventable denials reduce cash flow.
• Teams spend hours appealing avoidable denials.
• Reimbursement variance is hard to spot early.
• Different payers behave differently, so one-size-fits-all rules fail.

Why This Is Different

Most legacy rule engines rely on static if/then rules that break when payer behavior shifts. This platform combines payer-aware modeling, segment support controls, and probability calibration so scores stay useful as data patterns change. Instead of treating every payer and claim type the same, it adjusts confidence by segment and flags low-support conditions for manual review. The result is practical automation with guardrails, not black-box scoring without context.

What the Platform Solves

The platform gives you pre-submission risk signals and post-submission support through APIs.

Unified API note:

• POST /v1/score is the primary endpoint.
• payload shape depends on workflow.
• Legacy workflow-specific scoring endpoints remain for backward compatibility and are being de-emphasized in public docs.

1. Denial Risk Scoring API

Primary endpoint: POST /v1/score with workflow="healthcare.denial"

What it does:

• Scores each claim with a denial probability.
• Supports regime-aware routing (synthetic_v1, cms_v1, commercial_beta) with explicit override options.
• Uses frozen regime model versions for synthetic_v1 and cms_v1 so routing behavior stays reproducible.
• Assigns a risk tier (high/medium/low).
• Returns top contributing factors.
• Returns routing metadata (distribution_profile, routing_source) for auditability.
• Provides recommended next action.

Layman value:

• You can focus staff review on the claims most likely to be denied.
• You can prevent denials instead of reacting to them later.

2. Prior Authorization Risk Prediction API

Primary endpoint: POST /v1/score with workflow="healthcare.prior_auth"

What it does:

• Estimates prior auth failure risk before submission.
• Uses payer-aware behavior patterns.
• Returns support/confidence context by segment.

Layman value:

• Teams can fix auth issues earlier.
• Low-risk requests move faster; high-risk requests get human attention.

3. Reimbursement Estimate API

Primary endpoint: POST /v1/score with workflow="healthcare.reimbursement"

What it does:

• Predicts expected payment/allowed amount.
• Surfaces potential underpayment patterns.
• Tracks payer-level bias and monthly performance.

Layman value:

• Finance teams get better payment expectations.
• You can detect suspicious underpayment faster.

4. Appeal Generation API

Endpoint: POST /v1/claims/appeals/generate (beta/enterprise)

What it does:

• Generates structured appeal drafts.
• Includes required sections and claim details.
• Includes policy-citation references with guardrails.

Layman value:

• Staff spend less time drafting appeals.
• Output quality is more consistent and review-ready.

5. Historical Tracking APIs

Endpoints:

• GET /v1/claims/{external_claim_id}/appeals/history
• GET /v1/claims/{external_claim_id}/prior-auth/history
• GET /v1/claims/{external_claim_id}/reimbursement/history

Discovery endpoints:

• GET /v1/workflows
• GET /v1/limits
• GET /v1/usage

What they do:

• Return stored result history by claim.
• Help with auditing, troubleshooting, and trend review.

Layman value:

• Easy to see what happened for a specific claim over time.

5.1 Outcome Feedback API

Endpoint:

• POST /v1/feedback

What it does:

• Accepts structured post-outcome feedback linked to a prior scoring response.
• Uses the scoring response x-request-id as request_id.
• Validates that request_id exists, is recent, and matches the same caller + workflow endpoint.
• Stores feedback as telemetry events for calibration/drift monitoring.

Data safety controls:

• notes is optional and capped to short text.
• PHI-like patterns are rejected in notes.
• Freeform claim text/documents are intentionally not accepted.

Layman value:

• Gives you a direct way to tell the system when reality disagrees with predictions.
• Improves long-term model trust and calibration without manual spreadsheets.

6. Billing + API Key Service for Monetization and Access Control

Token-service endpoints:

• POST /v1/billing/checkout/session
• POST /v1/billing/webhooks/stripe
• POST /v1/apikeys/issue
• POST /v1/apikeys/{api_key_id}/revoke
• GET /v1/billing/accounts/{email}/usage
• POST /v1/tokens/issue (legacy/internal JWT support)
• POST /v1/control-plane/auth/signup and POST /v1/control-plane/auth/login (self-serve dashboard auth)
• POST /v1/control-plane/setup-links (admin-generated one-time onboarding links)
• POST /v1/control-plane/setup-links/redeem (setup-link -> dashboard session)
• GET /v1/control-plane/workspace and POST /v1/control-plane/workspace ({"workspace_name":"..."})
• GET/POST /v1/control-plane/workspace/api-keys (self-serve key list + create)
• POST /v1/control-plane/workspace/api-keys/{api_key_id}/rotate
• POST /v1/control-plane/workspace/api-keys/{api_key_id}/revoke
• POST /v1/control-plane/sessions/logout

What it does:

• Creates Stripe Checkout sessions for paid plans.
• Activates/deactivates access based on webhook-driven billing state.
• Issues hashed, scoped API keys tied to billing accounts.
• Tracks monthly and workflow-level usage for metered billing.
• Supports one-time setup links so customers can self-serve key create/rotate/revoke in dashboard flows.
• Enforces free-tier and paid-tier usage envelopes automatically.

Layman value:

• You can launch free + usage-based pricing without custom billing infrastructure.
• Customers only access what their plan allows.
• Billing state and API access stay synchronized.

7. Reliability, Monitoring, and Drift Awareness

Operational capabilities include:

• Structured logging.
• Health and readiness endpoints (/health, /readyz).
• Metrics endpoints (/metrics public scrape, /metrics.json protected snapshot requiring metrics:read) for route-level latency/error visibility.
• Model/version logging.
• Response-level calibration metadata (calibration_method, calibration_version) on denial and prior-auth endpoints.
• Segment-support and drift diagnostics.
• Alerting when downgrade rates exceed thresholds.
• DB-backed request-id validation for feedback events so multi-instance deployments stay consistent.

Layman value:

• You can trust what is running in production.
• You can catch model behavior changes before they hurt performance.

7.1 Secure-by-default runtime posture

The platform now ships with security-oriented defaults so pilot teams do not start from an insecure baseline:

• API authentication is enabled by default.
• Local Postgres is bound to loopback by default instead of being exposed broadly.
• Token issuance requires an explicit admin token (no built-in dev admin fallback token).
• Token helper TLS verification is on by default.
• API and token service containers run as a non-root runtime user.

Layman value:

• Lower deployment risk during pilots.
• Fewer accidental exposures from default settings.
• Cleaner security-review posture for enterprise buyers.

8. Simulation and Validation Framework

The platform includes simulation tooling to test:

• Denial target metrics (AUC, capture, lift, calibration).
• Reimbursement business targets (MAPE, monthly accuracy, diagnostic R2).
• Cross-model integrity and segment stability.

Layman value:

• You can prove performance with repeatable reports before pilots.

8.1 Latest validation snapshot (2026-02-17 UTC)

Recent validation artifacts:

• local 5-seed report: artifacts/test-reports/local-full-5seed-validation-20260216T225006Z.md
• Fly 5-seed fast report: artifacts/test-reports/fly-full-5seed-validation-20260216T235231Z.md
• Fly dual-machine rerun: artifacts/test-reports/fly-two-machine-rerun-20260217T004535Z.md

Plain-language summary:

• Local run quality gates were strong for prior auth/reimbursement and mostly strong for denial.
• Fly run quality was directionally similar, but latency was higher than local.
• In the dual-machine Fly rerun, both API machines stayed up during benchmark + simulation and latency improved to about 529 ms p95, but still missed the strict < 500 ms target.

Machine profile used in the dual-machine rerun:

• API: two shared machines, each 4 vCPU / 4096 MB
• Postgres: one shared machine 4 vCPU / 4096 MB
• token service: one shared machine 2 vCPU / 1024 MB

How It Works End-to-End (Simple View)

1. Claim data comes in through an API request.
2. The platform validates inputs and checks authorization.
3. A model scores risk or predicts payment.
4. The response includes score + explanation context.
5. Results are logged and can be queried later by claim ID.
6. Monitoring tracks quality, drift, and runtime health.
7. Readiness checks (/readyz) signal whether the service is safe to receive traffic.
8. Metrics surfaces (/metrics, /metrics.json) show machine-scrape telemetry and a compact human-readable snapshot; /metrics.json requires metrics:read.

Unified response semantics

• All workflows return a unified score, risk_level, confidence, model_version, and explanation.top_factors.
• Workflow-specific values are returned under details:
• denial: details.denial
• prior auth: details.prior_auth
• reimbursement: details.reimbursement
• For reimbursement workflow, top-level score is a normalized risk score derived from reimbursement ratio (1 - reimbursement_ratio).

Example Workflow (Concrete)

Example scenario:

• A clinic submits an outpatient claim with a billed amount near $1,200.
• The denial API returns a high risk score (for example 0.71) and flags missing prior auth documentation plus a modifier pattern risk.
• Staff verifies auth details and corrects documentation before submission.
• The claim is submitted with lower preventable denial risk, reducing downstream rework and appeal effort.

Who This Is For

• RCM teams at provider organizations.
• Billing teams at specialty practices.
• Clearinghouse and workflow automation vendors.
• AI agent builders integrating billing-risk intelligence.

How You Deploy This

The platform is designed to plug into existing systems through APIs. You can integrate it into current RCM software, clearinghouse workflows, or internal automation tools without replacing your EHR. Teams typically call the APIs during pre-submission claim review, then use history endpoints and logs for audit and operations.

What This Platform Is Not

• It is not a full claims clearinghouse replacement.
• It is not an EHR.
• It is not a payer contract management system.
• It does not remove human review for edge cases.

It is a decision-support and automation layer for claim risk and payment intelligence.

Glossary and Acronyms

Core Business Terms

• Claim: A bill sent to an insurance payer for a healthcare service.
• Denial: A payer decision not to pay a claim (fully or partly).
• Allowed Amount: The amount a payer says is eligible for reimbursement.
• Reimbursement: The payment made by the payer for a claim.
• Prior Authorization (Prior Auth): Payer approval required before certain services.
• Appeal: A formal request to reconsider a denied claim.
• Out-of-Network (OON): Provider is not contracted with the payer's network.
• Frequency Edit: Payer rule that denies duplicate or too-frequent billing.

Healthcare Coding Acronyms

• CPT: Current Procedural Terminology. Procedure/service billing codes maintained by AMA.
• ICD-10-CM: International Classification of Diseases, 10th Revision, Clinical Modification. Diagnosis coding system.
• HCPCS: Healthcare Common Procedure Coding System. Includes codes for supplies/services not fully covered by CPT.
• Modifier: A short code (such as -25, -59) attached to a procedure code to clarify billing context.
• NPI: National Provider Identifier. Unique provider identifier used in U.S. healthcare transactions.

Revenue Cycle / Admin Acronyms

• RCM: Revenue Cycle Management. End-to-end process from patient scheduling to final payment collection.
• CMS: Centers for Medicare & Medicaid Services. U.S. federal agency that publishes major healthcare payment data and rules.
• EHR: Electronic Health Record. Clinical system where patient records and encounter details are stored.
• EDI: Electronic Data Interchange. Standardized electronic format for healthcare transactions.
• X12 837: Standard EDI transaction for submitting healthcare claims.
• X12 835: Standard EDI transaction for payment and remittance details.
• X12 278: Standard EDI transaction often used for prior authorization requests.
• EOB: Explanation of Benefits. Document explaining what the payer covered and why.
• ERA: Electronic Remittance Advice. Electronic version of payment/remittance detail.

Security and Access Acronyms

• JWT: JSON Web Token. Signed token used for API authentication/authorization.
• API Key / Token Scope: Permission boundary controlling what an API client can do.
• TLS/HTTPS: Encrypted web transport protocol that protects data in transit.
• PHI: Protected Health Information. Individually identifiable health data.
• HIPAA: Health Insurance Portability and Accountability Act. U.S. law governing PHI privacy/security requirements.

ML and Metrics Acronyms

• ML: Machine Learning. Statistical models that learn patterns from data.
• AUC (ROC AUC): Area Under the ROC Curve. Measures ranking quality (higher is better, 0.5 is random).
• CI: Confidence Interval. Estimated range where a metric likely falls.
• ECE: Expected Calibration Error. Measures how well predicted probabilities match observed outcomes (lower is better).
• MAPE: Mean Absolute Percentage Error. Average percentage prediction error for regression (lower is better).
• R2: Coefficient of Determination. How much variance a regression model explains (higher is generally better).
• p95 Latency: 95th-percentile response time. 95% of requests are faster than this value.
• Bootstrap: Resampling method used to estimate metric uncertainty (such as confidence intervals).
• Drift: Data distribution changes over time that can degrade model performance.

Practical Takeaway

If you are a non-technical stakeholder, the easiest way to think about this platform is:

• It predicts where claims are likely to fail.
• It estimates what claims should pay.
• It helps teams appeal denials with structured, policy-grounded drafts.
• It wraps all of that in secure, monitorable APIs that can be sold as a product.