DEV Community: VBC Risk Analytics

Designing an API-First Value-Based Care Analytics Stack for MA Payers

VBC Risk Analytics — Fri, 10 Jul 2026 01:02:57 +0000

If you build software for Medicare Advantage (MA) plans, "analytics" usually arrives as a vague requirement and leaves as a pile of nightly batch jobs and a BI dashboard nobody trusts. This post is about treating value-based care analytics as an engineering problem: data contracts, idempotent scoring, and auditability baked into the API surface.

The domain in one paragraph

Each member has diagnoses (ICD-10-CM codes) that map to Hierarchical Condition Categories (HCCs). HCCs, plus demographics, produce a Risk Adjustment Factor (RAF) under the CMS-HCC V28 model. RAF drives the plan's payment. So the analytics platform's job is to take coded encounters in, and emit defensible RAF and gap insights out — reproducibly.

1. Model the inputs as contracts, not files

The single biggest source of bad analytics is loose ingestion. Define a strict schema for encounters and enforce it at the edge:

{
  "member_id": "SYNTH-100245",
  "dos": "2026-02-11",
  "dx_codes": ["E11.9", "I50.32", "N18.4"],
  "source": "claim",
  "provider_npi": "0000000000"
}

Reject malformed records loudly instead of silently dropping them. A diagnosis that never made it into the pipeline is a RAF dollar that quietly disappears.

2. Make RAF scoring a pure function

RAF computation should be deterministic: given the same member inputs and the same model version, you get the same score. Pin the model version explicitly.

You can build this yourself, but the hierarchy and coefficient logic is exactly what a scoring API exists to own. Calling one keeps your platform a pure pass-through:

import httpx, os


MODEL = "CMS-HCC-V28 Continuing Enrollee"


def compute_raf(member, model=MODEL):
    resp = httpx.post(
        "https://restapi.npidataservices.com/raf/api/v1/getScore",
        headers={
            "ApiKey": os.environ["RAF_API_KEY"],   # custom header, NOT Authorization: Bearer
            "Content-Type": "application/json",
            "accept": "application/json",
        },
        json={
            "model": model,
            "factor": "Community NonDual Aged",
            "age": member["age"],
            "gender": member["gender"],            # "MALE" | "FEMALE"
            # ICD-10-CM WITHOUT dots: "E11.9" -> "E119"
            "HCC_Codes": [c.replace(".", "") for c in member["dx_codes"]],
        },
        timeout=5.0,
    )
    resp.raise_for_status()
    return resp.json()["score"]["Total"]["Grand Total"]["RAF_Score"]

Two engineering points matter here. First, the hierarchy ("trumping" within an HCC family, where a more severe condition suppresses milder ones) is applied server-side — don't reimplement it, or you'll overstate the score by summing raw weights. Second, store the model string with every result; when you re-run history you must reproduce the score that was live at the time.

3. Treat suspecting as evidence-linked, not magic

A "suspect" condition should carry its supporting evidence (labs, meds, prior dx) as structured fields, so downstream consumers can rank by defensibility:

{ "member_id": "SYNTH-100245",
  "suspect_hcc": "HCC38",
  "evidence": ["a1c>9.0", "rx:insulin", "prior_dx:E11.65"],
  "confidence": 0.82 }

Suspects without an evidence array are a code smell — and an audit liability.

4. Build audit simulation as a first-class endpoint

The most underrated feature: let the plan sample its own population and model RADV extrapolation exposure before CMS does. It's just sampling + documentation scoring + an extrapolation formula over synthetic data, but exposing it as an API turns "are we defensible?" into a number.

Why API-first wins

Dashboards are a presentation layer; the durable asset is a clean, versioned API that any tool can consume. If you want the product-level view of what MA payers actually need from this stack in 2026, this guide lays it out, and the broader risk adjustment analytics platform for payers shows how the pieces compose end to end.

Build the contracts first. The dashboards get easy after that.

VBC Risk Analytics. Educational only — not coding, billing, or clinical advice; verify against the current CMS Rate Announcement. Synthetic data only.

How ICD-10 Codes Map to an HCC / RAF Score (and Why the Same Code Set Yields Different Scores)

VBC Risk Analytics — Wed, 08 Jul 2026 17:22:17 +0000

If you're building anything that touches Medicare Advantage risk adjustment, sooner or later you hit this question:

"How do ICD-10 codes map to an HCC / RAF score?"

The short answer that trips most people up: ICD-10-CM codes don't carry a RAF weight individually. There's a pipeline between the diagnosis code and the number, and skipping a step gives you a wrong score. Here's the whole chain.

The Pipeline

1. ICD-10 → HCC

Each qualifying diagnosis maps into a Hierarchical Condition Category (HCC) — a clinically grouped bucket. Many ICD-10 codes collapse into a single HCC, and not every ICD-10 code maps to a payable HCC at all. The crosswalk is many-to-one, and it's lossy by design.

2. Apply the hierarchies

Within a disease family, only the most severe HCC is kept. A more severe HCC "traps" the milder related HCCs so the model doesn't pay twice for the same underlying problem.

The critical part for implementers: do this before you sum anything. If you sum coefficients first and trump later, you'll double-count.

3. Sum the coefficients

RAF = demographic_factor
    + Σ (coefficient for each surviving HCC)
    + interaction_terms

The demographic factor comes from age/sex (and enrollment characteristics). Interaction terms are extra weight for specific disease combinations — they aren't just additive HCCs.

4. Mind the model version

This is the one that silently breaks reconciliations. CMS-HCC V24 and V28 use different HCC maps and different coefficients. The exact same set of ICD-10 codes produces a different RAF depending on the model year you run it against. If two systems disagree on a member's score, "which model version?" is the first question to ask.

What You Actually Need Programmatically

To compute this yourself, you need four artifacts — all keyed to the correct payment year:

A current ICD-10 → HCC crosswalk for the target model version
The hierarchy (trumping) table
The coefficient table
The interaction list

Get the payment year wrong on any one of these and the score is wrong. These tables change annually with the CMS Rate Announcement, so a cached copy from two years ago is a bug waiting to happen.

Sanity-Checking Your Implementation

Disclosure: I'm the CEO of VBC Risk Analytics and we build rafscorecalculator.com, so I have a financial interest in what follows. With that caveat out of the way — if you want to verify your own implementation, the RAF Score Calculator walks the ICD-10 → HCC → RAF chain with worked examples and computes a member under both V24 and V28. It's handy as a reference oracle for unit tests when you're validating your own crosswalk logic.

This is a general explanation of the mechanics, not coding or billing advice. HCC and coefficient specs change every payment year — always validate against the current CMS Rate Announcement rather than a table you cached last cycle.

If you're implementing this and hit an edge case with hierarchies or interaction terms, drop it in the comments.

Automating RAF Scoring in Real Time: An Architecture Walkthrough

VBC Risk Analytics — Thu, 02 Jul 2026 16:38:37 +0000

If you've ever built a batch RAF job, you know the awkward truth: by the time the score lands, the encounter that produced it is long over. The interesting engineering challenge is moving that calculation from a nightly batch to a real-time, event-driven service. Here's how I think about the architecture.

What we're computing

The Risk Adjustment Factor (RAF) is built from demographic factors plus clinical conditions expressed as Hierarchical Condition Categories (HCCs), each weighted by a coefficient under CMS-HCC V28. The math itself is simple addition. The hard part is doing it as data arrives, deterministically, with an audit trail.

For the conceptual background on why real-time scoring improves accuracy, this writeup on how RAF score automation works is a good companion read.

Event-driven, not batch

The shift is from "scan everything nightly" to "recompute the affected member when their data changes."

new_diagnosis_event ──> map ICD-10 -> HCC ──> recompute member RAF ──> emit score event

A new confirmed diagnosis, a corrected code, or a model-year change triggers a recompute of just that member, not the whole population.

import httpx, os


MODEL = "CMS-HCC-V28 Continuing Enrollee"   # pinned, never implicit


def on_diagnosis_event(event):
    member = load_member(event.member_id)
    resp = httpx.post(
        "https://restapi.npidataservices.com/raf/api/v1/getScore",
        headers={
            "ApiKey": os.environ["RAF_API_KEY"],   # custom header, NOT Bearer
            "Content-Type": "application/json",
            "accept": "application/json",
        },
        json={
            "model": MODEL,
            "factor": "Community NonDual Aged",
            "age": member.age,
            "gender": member.gender,               # "MALE" | "FEMALE"
            "HCC_Codes": member.icd10_no_dots,      # e.g. ["E119", "I509"]
        },
        timeout=5.0,
    )
    resp.raise_for_status()
    score = resp.json()                            # itemized, additive components
    emit("raf.updated", {
        "member_id": member.id,
        "raf": score["score"]["Total"]["Grand Total"]["RAF_Score"],
        "breakdown": score["score"],               # Demographic + Diagnosis + interactions
        "model": MODEL,
    })

Determinism is the whole ballgame

Real-time scoring is only useful if it's reproducible. Two requirements:

Pin the model version. A score computed today must be reproducible later. Pass model explicitly (e.g. "CMS-HCC-V28 Continuing Enrollee"); never let the crosswalk float implicitly.
Itemize the output. A bare RAF is undebuggable and indefensible. The getScore response is already itemized into additive components — Demographic, per-HCC Diagnosis, Disease Interaction, and a Total block — each carrying both a RAF_Score (coefficient) and an MA_Payment (dollars). That structure is exactly what you need when a RADV (Risk Adjustment Data Validation) audit asks how a number was derived.

{
  "api_usage_log_id": 439229,
  "score": {
    "Demographic": { "Age and Gender": { "MA_Payment": 3453.58, "RAF_Score": 0.332 } },
    "Diagnosis": {
      "HCC 226": { "MA_Payment": 3744.84, "RAF_Score": 0.36 },
      "HCC 38":  { "MA_Payment": 1726.79, "RAF_Score": 0.166 },
      "HCC 328": { "MA_Payment": "1321.10", "RAF_Score": 0.127 },
      "HCC Count": { "Count": 5, "MA_Payment": 520.12, "RAF_Score": 0.05 }
    },
    "Disease Interaction": {
      "DIABETES_HF": { "MA_Payment": 1165.06, "RAF_Score": 0.112 },
      "HF_KIDNEY":   { "MA_Payment": 1830.81, "RAF_Score": 0.176 }
    },
    "Total": {
      "Grand Total": { "MA_Payment": 19826.87, "RAF_Score": 1.906 },
      "MA_Adjusted": { "MA_Payment": 17485.55, "RAF_Score": 1.681 },
      "Normalized":  { "MA_Payment": 18581.88, "RAF_Score": 1.786 }
    }
  },
  "score_cnt": 9,
  "status": "success"
}

(Synthetic.) One parsing gotcha: some fields — like HCC 328's MA_Payment above — come back as a quoted string ("1321.10"), so coerce to a number defensively rather than assuming JSON floats.

Idempotency and ordering

Events arrive out of order and get redelivered. Two defenses:

Idempotent recompute. Recomputing from the member's current state (not by incrementally mutating a score) means a duplicate event is harmless.
Version your member state. Tag each recompute with the input version so a late-arriving stale event can be safely ignored.

Batch still has a place: backfill and roster-wide reruns

Real-time handles the steady-state stream, but you still need a batch path for the initial population load and for re-scoring everyone after a model-year change. That runs against a separate batch API as a 3-step job (base https://www.vbcriskanalytics.com/raf-batch-api, auth ApiKey: <key> plus an empty X-CSRF-TOKEN: header on every call):

# 1) submit a CSV of (member, diagnosis) rows -> returns a job id
curl -X POST https://www.vbcriskanalytics.com/raf-batch-api/getPreProspectScore \
  -H "ApiKey: $RAF_BATCH_API_KEY" \
  -H "X-CSRF-TOKEN: " \
  -F "risk_model=CMS-HCC-V28 Continuing Enrollee" \
  -F "risk_factor=Community NonDual Aged" \
  -F "file=@members.csv"
# -> {"code":201,"raf_batch_id":3400,"status":"Queued","check_status_url":"..."}


# 2) poll status: Queued -> Running -> Completed (Completed returns a download_url)
curl https://www.vbcriskanalytics.com/raf-batch-api/check-status/3400 \
  -H "ApiKey: $RAF_BATCH_API_KEY" -H "X-CSRF-TOKEN: "


# 3) download the result (short-lived ~120s signed S3 .zip wrapping an .xlsx)
curl -L https://www.vbcriskanalytics.com/raf-batch-api/download/3400 \
  -H "ApiKey: $RAF_BATCH_API_KEY" -H "X-CSRF-TOKEN: " -o results.zip

The CSV is one row per (member, diagnosis) with columns ID,Gender,Age,ICD-10 CM Code,Flag, where Flag (the Pre-Prospective Flag) is Last_Year or Current_Year. Treat the download URL as ephemeral — it expires in about two minutes, so fetch it immediately once status is Completed.

Don't let automation launder bad data

This is the failure mode worth stating plainly: automation amplifies whatever logic you give it. If a mapping is wrong or a diagnosis is unsupported, real-time scoring just produces wrong numbers faster and at scale. Build the accuracy into the rules — unsupported-HCC checks, specificity flags — upstream of the scorer, not as an afterthought.

Testing

Synthetic fixtures only. Generate illustrative members that exercise each HCC family and interaction term. Never test against live records.
Golden tests. Pin known inputs to known outputs per model version, so a coefficient change can't silently alter historical scores.

The payoff

An event-driven, deterministic RAF service puts an accurate, explainable score where it can influence care and documentation in the moment — and makes audit defense a query rather than a scramble. The full conceptual treatment of accuracy gains lives in the companion article above; this post is the architecture behind it.

VBC Risk Analytics. Educational only — not coding, billing, or clinical advice; verify against the current CMS Rate Announcement. Synthetic data only.

HCC V28 Transition Timeline & Phase-In Impact

VBC Risk Analytics — Wed, 01 Jul 2026 18:12:56 +0000

V28 didn't replace V24 overnight. CMS blends the two models over multiple payment years, which means for the duration of the transition your RAF is a weighted mix of two models. If your pipeline treats the switch as a flag flip, your numbers are wrong.

The blend, conceptually

blended_RAF = w_v28 * RAF_v28 + w_v24 * RAF_v24
# w_v28 increases each payment year until V28 is 100%

The exact weights per payment year are set in the CMS Rate Announcement.

Re-read it for the actual year — do not hard-code last year's split.

What that does to your data

YoY RAF deltas are contaminated. Part of any year-over-year change is just w_v28 increasing. Decompose every trend into model shift vs. true population/documentation shift, or your dashboards mislead.
Two engines, not one. You must compute both RAF_v24 and RAF_v28 for every member through the entire blend, then weight. Retire V24 only when its weight reaches zero.
Category drift. Some conditions that paid under V24 don't under V28; documentation that was sufficient before can under-capture now. Re-baseline historical members under the V28 model to see your real exposure. A category-by-category view of the V24-vs-V28 differences helps you spot which families to watch.

Minimal ops checklist

Load both coefficient/crosswalk sets, keyed by payment year.
Compute V24 + V28 per member; apply the year's blend weights.
Report model-shift and true-shift as separate series.
Re-score history under V28 for a clean baseline.
Re-verify weights and category counts against the current CMS Rate Announcement.

A side-by-side of the remap — plus a tool that computes a member under both models, so you can see the blend's effect on a real case — is here: HCC V28.

The point of all this is accuracy under the correct blended model for the payment year — not chasing a higher number.

Not coding, billing, or clinical advice. Phase-in weights change by payment year — confirm against the current CMS Rate Announcement.

Reviewed by the VBC Risk Analytics Risk Adjustment & Coding Team.

Last updated: July 2026

Risk Stratification as a Data Pipeline: Turning RAF Into a Worklist

VBC Risk Analytics — Thu, 25 Jun 2026 15:08:09 +0000

Risk stratification sounds like a clinical strategy, but for the engineers who build it, it's a ranking pipeline. You take a population, score each member's expected need, sort, and hand a care team a prioritized list. This post is about how that pipeline is actually wired in a Medicare Advantage context.

The goal, stated as a function

stratify(population) -> ranked_list_of_members_by_expected_need

The hard parts are choosing the score, making it explainable, and refreshing it on a cadence that's useful to humans.

The inputs

A useful stratification model blends several signals. In Medicare Advantage, the natural backbone is the same data that drives funding accuracy:

- RAF (Risk Adjustment Factor) — the normalized expected-cost score built from demographics and HCCs (CMS-HCC V28).

HCC composition — which conditions, not just the total. Two members with the same RAF can need very different interventions.
Utilization signals — recent admissions, ED visits, polypharmacy.
Gaps — suspected-but-undocumented conditions (a stratification model that ignores gaps under-ranks the sickest, least-documented members). This is exactly the approach walked through in this medicare advantage risk adjustment case study, where risk data became a concrete outreach list. ## A minimal scoring sketch python def member_score(m): """Synthetic, illustrative weighting only.""" score = m.raf * W_RAF score += m.recent_admissions * W_ADMIT score += len(m.open_gaps) * W_GAP score += m.polypharmacy_flag * W_RX return score ranked = sorted(population, key=member_score, reverse=True)

The weights are policy decisions, not engineering ones — surface them in config, don't bury them in code. Your clinical leadership will want to tune them, and your auditors will want to see them.

Explainability is not optional

A stratification score that a care manager can't interrogate is a score they won't trust. For every ranked member, emit the contribution breakdown:

{
  "member_id": "SYNTH-10293",
  "score": 3.8,
  "drivers": {
    "raf": 2.1,
    "recent_admissions": 1.0,
    "open_gaps": 0.5,
    "polypharmacy": 0.2
  }
}

Now "why is this member #1?" has a one-glance answer.

Refresh cadence and stability

- Recompute on a schedule (often monthly) and snapshot each run.

Watch for churn. If members thrash in and out of the top tier week to week, your weights are too sensitive — care teams need stability to actually act.
Track outcomes back to the score. The point isn't the ranking; it's whether outreach to high-ranked members changed anything.

Engineering guardrails

Synthetic data only in dev and test. Generate illustrative populations.
Version the model. A stratification run should be reproducible later.
Separate scoring from action. The pipeline ranks; humans decide. Don't auto-trigger interventions off a raw score.

The payoff

Done well, stratification connects the backward-looking RAF to forward-looking care: instead of reconciling last year's risk, you're deciding who to reach this month. For the full data-side walkthrough that complements this pipeline view, see the Medicare Advantage risk stratification guide.

VBC Risk Analytics. Educational only — not coding, billing, or clinical advice; verify against the current CMS Rate Announcement. Synthetic data only.

HCC V28 Explained: What Actually Changed from V24

VBC Risk Analytics — Tue, 09 Jun 2026 14:56:35 +0000

If you maintain anything that touches risk adjustment, the CMS-HCC model version is effectively a breaking dependency upgrade — and the industry is mid-migration from V24 to V28. Here's the changelog view.

The HCC map was reorganized and renumbered — V24 HCC numbers do not line up with V28.
The count of payment HCCs changed and a number of categories were constrained or removed.
Coefficients were re-estimated, so the same member can produce a different RAF under V28 vs V24.
CMS is phasing V28 in over multiple payment years — both models are live simultaneously during the blend.

What this breaks in practice

Hard-coded HCC numbers. Any mapping table keyed on V24 HCC IDs is wrong under V28. Treat the model version as an explicit input through your whole pipeline, not a constant.
Trend comparisons. Year-over-year RAF deltas during the phase-in are partly model artifact, not real population change. If you don't separate "blend shift" from "true shift," your dashboards lie.
Conditions that used to pay. Some diagnoses that mapped to a paying category under V24 don't under V28. Documentation behavior that was fine before can quietly under-capture now.

The migration checklist

Load both coefficient sets; compute V24 and V28 in parallel during the blend years.
Recompute historical members under V28 to get a clean apples-to-apples baseline.
Flag members whose RAF moves materially between models — those are where documentation and care-gap workflows need attention. If you want a structured look at how V24 and V28 compare before you build the diff logic, that breakdown is a useful reference.
Re-verify phase-in percentages and category counts against the current CMS Rate Announcement for the actual payment year — don't trust last year's numbers.

A side-by-side of the category remap and the phase-in schedule, plus a tool that computes a member under both models, is here: HCC V28. It's the fastest way to see, concretely, how a real member shifts under the V28 model before you trust your own implementation.

Why it's worth getting right

This isn't a cosmetic version bump. RAF drives Medicare Advantage funding; a quietly wrong model version means systematically wrong risk scores for real patients. Accuracy under the correct model — not score inflation — is the entire point.

Not coding, billing, or clinical advice. CMS-HCC specifications change by payment year — confirm against the current CMS Rate Announcement.

Written by Chin Ramamoorthi — CEO, VBC Risk Analytics. He has 20+ years across provider- and payer-side healthcare IT, including leading V24-to-V28 transition work on both the payer and provider side.
Reviewed by the VBC Risk Analytics Risk Adjustment & Coding Team.
Last updated: June 2026

Building an HCC Gap Analysis Pipeline (a developer's view of risk capture)

VBC Risk Analytics — Mon, 08 Jun 2026 08:18:40 +0000

If you write software for a Medicare Advantage plan, "HCC gap analysis" eventually lands on your desk as a data problem disguised as a clinical one. The clinical team says "we're leaving risk on the table." What they need from you is a pipeline that finds, ranks, and tracks the gaps. Here's how I think about building one.

The mental model

Start with definitions, because the acronyms compound fast:

HCC — Hierarchical Condition Category. The risk bucket a diagnosis rolls up into.
RAF — Risk Adjustment Factor. The score built from demographics plus HCC coefficients (CMS-HCC V28 is the current model).
A "gap" — a condition that is clinically supported somewhere in the data but is not captured as a coded, current-year HCC. Gap analysis is fundamentally a set-difference problem: suspected_hccs - documented_hccs, weighted by the RAF impact of each missing HCC. Step 1: Build the two sets Documented HCCs come from this year's confirmed claims/encounters, mapped through the current ICD-10 → HCC crosswalk. If you don't want to maintain your own crosswalk, the /getHCCCrosswalk sibling endpoint resolves ICD-10-CM codes to HCCs under a pinned model.

documented = {
    map_icd_to_hcc(dx, model="CMS-HCC-V28 Continuing Enrollee")
    for dx in current_year_diagnoses
    if dx.is_confirmed
}

Suspected HCCs come from weaker signals: prior-year HCCs that didn't recur, relevant labs, medications that imply a condition, and problem-list entries that never made it to a claim.

suspected = set()
suspected |= prior_year_hccs            # chronic conditions rarely resolve
suspected |= hccs_from_medications(rx)  # e.g., insulin -> diabetes family
suspected |= hccs_from_labs(labs)       # e.g., eGFR -> CKD staging

To turn a candidate condition set into a RAF impact, score it through the API. The endpoint is itemized, so you get a per-HCC coefficient back rather than a single opaque number:

curl -X POST https://restapi.npidataservices.com/raf/api/v1/getScore \
  -H "ApiKey: $RAF_API_KEY" \
  -H "Content-Type: application/json" \
  -H "accept: application/json" \
  -d '{
    "model": "CMS-HCC-V28 Continuing Enrollee",
    "factor": "Community NonDual Aged",
    "age": 66,
    "gender": "MALE",
    "HCC_Codes": ["E119", "C61", "N1832", "I509", "J449"]
  }'

Note the auth: a custom ApiKey: header, not Authorization: Bearer (a Bearer header returns 401). ICD-10-CM codes go in without dots (E11.9 -> E119).

Step 2: Compute the gap and weight it

A raw list of missing HCCs is noise. Engineers add value by ranking. The natural weight is the RAF coefficient — how much each closed gap would actually move the score.

gaps = suspected - documented
ranked = sorted(
    ({"hcc": h, "raf_delta": coefficient(h, "CMS-HCC-V28 Continuing Enrollee")} for h in gaps),
    key=lambda g: g["raf_delta"],
    reverse=True,
)

Now your clinical team gets a worklist sorted by impact instead of an undifferentiated dump. If you want the conceptual grounding for how those coefficients add up into a member's score, this RAF explainer is a solid reference — you can read more here.

Step 3: Close the loop with provenance

A gap you can't explain is a gap nobody will act on. For every suggested HCC, attach the evidence:

{
  "member_id": "SYNTH-00417",
  "suspected_hcc": "HCC38",
  "raf_delta": 0.31,
  "evidence": [
    {"type": "rx", "detail": "metformin (synthetic)"},
    {"type": "prior_hcc", "year": 2025}
  ],
  "status": "open"
}

Provenance is also what protects you later. A gap closed with documentation behind it survives a RADV (Risk Adjustment Data Validation) audit; a gap "closed" by guessing does not. Build the evidence trail from day one.

Step 4: Treat it as a recurring job, not a project

Gaps reopen. Members get new labs, conditions resolve, the model changes. Schedule the pipeline (monthly is common), snapshot the open/closed state, and track closure rate over time as your real KPI.

A few engineering gotchas

Use synthetic fixtures. Never test against live member data. Generate illustrative members that exercise each HCC family.
Pin the model version. A gap computed under V28 must be reproducible later; don't let the crosswalk float.
Idempotency. Re-running the pipeline shouldn't duplicate open gaps — key on (member, hcc, year). Wrapping up

HCC gap analysis isn't glamorous, but it's one of the highest-leverage pipelines you can build on the risk-adjustment side: it directly connects documentation quality to a plan's revenue accuracy and audit posture. If you want the broader, less code-heavy treatment of finding and closing these gaps, the full HCC gap analysis guide covers the program side that complements the pipeline above.

VBC Risk Analytics. Educational only — not coding, billing, or clinical advice; verify against the current CMS Rate Announcement. Synthetic data only.

Healthcare Risk Adjustment Tools from VBC Risk Analytics

VBC Risk Analytics — Tue, 21 Apr 2026 15:51:40 +0000

Healthcare data engineering is hard. Healthcare risk adjustment data engineering is a category of hard that deserves its own word.

If you've ever worked in health IT, you know the stack: EHR extracts that arrive in twelve different formats, ICD-10 codes that map to HCC categories under rules that change every model year, RAF scores that determine how much a health plan gets paid for every enrolled member, and CMS audits that can claw back millions if the documentation doesn't hold up.

At VBC Risk Analytics, we've spent years building API-first tools in this space. This introductory post covers what risk adjustment actually is, why it's technically interesting, and what we're building — with the hope of connecting with developers, data engineers, and health IT professionals who work in this domain.

What Is Risk Adjustment and Why Does It Matter?

Risk adjustment is the process Medicare uses to ensure that health plans are paid fairly based on the health status of their enrolled members. Sicker members cost more to care for, so a plan that enrolls a predominantly sick population gets higher payments to offset those costs. A plan that enrolls predominantly healthy members gets lower payments.

The mechanism that drives this is the Hierarchical Condition Category (HCC) model — specifically, the CMS-HCC model maintained by the Centers for Medicare and Medicaid Services. Every Medicare Advantage member gets a Risk Adjustment Factor (RAF) score that reflects their predicted cost relative to the average Medicare beneficiary.

A RAF score of 1.0 means the member is expected to cost exactly as much as the average. A score of 1.5 means 50% more than average. A score of 0.7 means 30% less.

The score is built by:

Taking the member's demographic data (age, sex, Medicaid eligibility, etc.)
Mapping their ICD-10 diagnosis codes to HCC categories
Applying interaction factors for certain combinations of conditions
Summing the coefficients from the CMS-HCC model

For a health plan with 100,000 Medicare Advantage members, even small errors in this calculation — missed diagnoses, mapping mistakes, documentation gaps — compound into significant over- or underpayment.

The Technical Complexity

This sounds straightforward until you get into the actual implementation.

The ICD-10-to-HCC mapping is not a simple lookup table. There are approximately 70,000 ICD-10-CM codes and 86 HCC categories in the CMS-HCC V28 model. Not all codes map to HCCs. Some codes map to multiple HCCs. The "hierarchical" part of HCC means that more severe conditions in a disease hierarchy suppress less severe ones — so if a patient has both HCC 18 (Diabetes with chronic complications) and HCC 19 (Diabetes without complication), only HCC 18 counts.

The model coefficients change with each model version. CMS transitioned from V24 to V28 over 2024-2026, blending the two models at different percentages each year. Code that was correct for V24 produces wrong answers for V28 if you don't update the coefficient tables.

The demographic adjusters depend on whether a member is community-dwelling or institutionalized, whether they have Medicaid, and whether they're in their initial enrollment period. Getting these wrong affects every member, not just the complex ones.

RADV audits add another layer. The Risk Adjustment Data Validation audit process has CMS selecting a sample of medical records and verifying that each HCC in the RAF score is supported by adequate documentation. Plans that fail RADV audits repay the overpayment — plus potential extrapolation penalties.

What VBC Risk Analytics Builds

Our platform at VBC Risk Analytics addresses the risk adjustment workflow end-to-end. A few things we've built:

RAF Score API: A REST endpoint that takes a member's demographics and ICD-10 codes and returns a fully calculated RAF score with HCC mapping details, model version, and coefficient breakdown. Handles V24, V28, and the blended transition percentages.

ICD-10 Data Lookup API: Fast lookup for ICD-10-CM codes — descriptions, HCC mappings, validity flags, hierarchy relationships. Useful for coding workflow tools, eligibility systems, and CDI applications.

RADV Audit Scrubber: Before a RADV audit happens, this tool reviews the documentation supporting each HCC against CMS audit criteria. It flags potential documentation deficiencies so they can be addressed before CMS asks for the medical records.

NPI Lookup API: Provider verification via the National Plan and Provider Enumeration System (NPPES), useful for linking clinical data to provider records.

Why API-First?

Most risk adjustment software is built as monolithic platforms — you buy the whole system or you buy nothing. We took an API-first approach because:

Most health plans and provider groups already have analytics infrastructure. They need specific capabilities, not replacement systems.
Health IT developers building EHR integrations, population health tools, and care management platforms need programmatic access to risk adjustment data.
APIs are testable, versionable, and composable in ways that dashboard-only tools aren't.

If you're building something in the health IT space and you need RAF scoring, ICD-10 lookup, or provider verification, check out the healthcare APIs at VBC Risk Analytics. We have documentation and sandbox access available.

What's Next

In future posts on Dev.to, I'll be going deeper on specific technical topics:

The ICD-10-to-HCC mapping algorithm — how it actually works under the hood
CMS-HCC V28 changes and what broke in existing implementations
RADV audit data modeling — structuring your documentation review pipeline
Building a risk stratification system from claims data
NPI verification edge cases and the mess that is provider data quality

If you work in health IT or healthcare data engineering, I'd love to connect. Drop a comment below or reach out through VBC Risk Analytics.

Building Healthcare Risk Adjustment Tools: An Introduction to VBC Risk Analytics

VBC Risk Analytics — Wed, 15 Apr 2026 11:32:48 +0000

Healthcare data engineering is hard. Healthcare risk adjustment data engineering is a category of hard that deserves its own word.

What Is Risk Adjustment and Why Does It Matter?

A RAF score of 1.0 means the member is expected to cost exactly as much as the average. A score of 1.5 means 50% more than average. A score of 0.7 means 30% less.

The score is built by:

Taking the member's demographic data (age, sex, Medicaid eligibility, etc.)
Mapping their ICD-10 diagnosis codes to HCC categories
Applying interaction factors for certain combinations of conditions
Summing the coefficients from the CMS-HCC model

The Technical Complexity

This sounds straightforward until you get into the actual implementation.

What VBC Risk Analytics Builds

Our platform at VBC Risk Analytics addresses the risk adjustment workflow end-to-end. A few things we've built:

NPI Lookup API: Provider verification via the National Plan and Provider Enumeration System (NPPES), useful for linking clinical data to provider records.

Why API-First?

Most risk adjustment software is built as monolithic platforms — you buy the whole system or you buy nothing. We took an API-first approach because:

Most health plans and provider groups already have analytics infrastructure. They need specific capabilities, not replacement systems.
Health IT developers building EHR integrations, population health tools, and care management platforms need programmatic access to risk adjustment data.
APIs are testable, versionable, and composable in ways that dashboard-only tools aren't.

What's Next

In future posts on Dev.to, I'll be going deeper on specific technical topics:

The ICD-10-to-HCC mapping algorithm — how it actually works under the hood
CMS-HCC V28 changes and what broke in existing implementations
RADV audit data modeling — structuring your documentation review pipeline
Building a risk stratification system from claims data
NPI verification edge cases and the mess that is provider data quality

If you work in health IT or healthcare data engineering, I'd love to connect. Drop a comment below or reach out through VBC Risk Analytics.