DEV Community: VBC Risk Analytics

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