DEV Community: VBC Risk Analytics

CDI Is the Missing Link in HCC Risk Capture (and It's a Data Problem)

VBC Risk Analytics — Tue, 11 Aug 2026 14:38:04 +0000

Most engineering teams building risk adjustment tooling treat clinical documentation as a black box: notes go in, codes come out, RAF scores get calculated. But if your HCC (Hierarchical Condition Category) capture rate is low, the problem usually isn't your scoring engine — it's upstream, in the documentation itself. This is where Clinical Documentation Improvement (CDI) becomes a data-engineering concern, not just a clinical one.

The capture gap, in concrete terms

A member can have a chronic condition that absolutely belongs in the CMS-HCC V28 model, but if the provider's note for the year doesn't document that the condition was evaluated and addressed, it never becomes a codable diagnosis, and it never contributes to the RAF (Risk Adjustment Factor) score. The condition is real. The data is missing. Multiply that across a panel and you have a systematic understatement of risk.

CDI exists to close that gap at the source. From a systems perspective, that means surfacing the right prompt to the right clinician at the right moment — which is squarely an engineering problem.

Where developers come in

A modern CDI workflow is a pipeline:

clinical note (NLP)  ->  candidate conditions
   ->  cross-check vs claims history + problem list
   ->  documentation gap?  ->  provider query/prompt
   ->  resolved diagnosis  ->  HCC mapping (V28)  ->  RAF

Each stage is testable. A few things to get right:

Evidence linkage. Every suggested condition should carry a pointer to the evidence (the lab value, prior claim, or note span) that triggered it. A prompt with no evidence is noise, and clinicians tune out noise fast.
Suppress the already-documented. If the condition is already captured for the year, don't prompt. Deduping against the current-year encounter set is essential.
Hierarchy awareness. In the HCC model, hierarchies mean a more severe condition supersedes a less severe one in the same family. Your suggestion logic should respect that so you're not prompting for a code that wouldn't add value.

Synthetic example

Consider a synthetic member with a documented history of CKD and a recent eGFR of 28. If the current-year note mentions kidney disease only in passing without staging, the CDI engine flags a documentation gap and suggests a clarification. The clinician confirms the stage, the diagnosis is documented, and the appropriate HCC is captured. No new clinical reality was invented — the documentation simply caught up to it. (All values here are synthetic; no PHI.)

The compliance guardrail

CDI is not a code-maximization tool. Every prompt has to be clinically defensible and every captured diagnosis must reflect a condition actually evaluated and addressed at the visit. Build your prompts to be neutral and evidence-based, not leading, so the resulting documentation holds up under a RADV (Risk Adjustment Data Validation) audit. If your engine nudges clinicians toward unsupported codes, you're building audit liability, not value.

Measuring whether it works

Track the boring metrics: query response rate, query agreement rate, recapture rate of chronic conditions year over year, and the delta between suspected and confirmed conditions. If your prompts have a low agreement rate, they're probably low-quality or poorly timed — fix the evidence linkage before you add more rules.

For the clinical playbook side of this — how CDI specialists actually structure queries and partner with providers — see the resources maintained by VBC Risk Analytics. The full featured article walks through the operating model end to end: CDI: The Missing Link to Improve HCC Risk Capture.

Done right, CDI is the difference between a scoring engine that's technically correct and a risk picture that's actually complete.

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

V24 vs V28: A Side-by-Side for Engineers

VBC Risk Analytics — Mon, 10 Aug 2026 17:28:38 +0000

You're not comparing two clinical philosophies — you're comparing two coefficient/crosswalk artifacts that must both run during the blend. Here's the diff that matters in code.

Concern	V24	V28
HCC IDs	one numbering	renumbered/reorganized — not 1:1 with V24
Payable categories	one set	revised; some V24-payable conditions drop
Coefficients	V24 table	re-estimated
Status during transition	weighted with V28	weighted with V24 (blend)

Implementation implications

No shared HCC enum. Tag every HCC value with its model version or you will eventually compare V24 #18 to V28 #18 and they are not the same thing.
Two crosswalks + two coefficient tables, both keyed by payment year. Treat them as versioned data, not config constants.
Blend at the RAF layer, not the HCC layer: blended = w24*RAF_v24 + w28*RAF_v28, weights from the payment-year Rate Announcement.
Golden tests per version. A fixed member set with expected RAF under each model; run on every coefficient-table update.

A side-by-side of the category remap, plus a calculator that outputs the same member under both models, is here: HCC V28 — useful as the reference for those golden tests.

The non-code part

All of this serves one goal: the accurate RAF for the documented patient under the correct payment-year blend. Engineering correctness here isn't pedantry — a silently wrong model version mis-funds real patients at scale. Cross-check your output against the V28 model before trusting it downstream.

Not coding, billing, or clinical advice. Confirm coefficients/weights 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: August 2026

How to Efficiently Compute RAF Scores for 100,000+ Members in a Nightly Batch Job

VBC Risk Analytics — Fri, 31 Jul 2026 18:06:11 +0000

The bottleneck is almost never the math — RAF scoring per member is cheap. The real pain is owning the model tables, plus a job that can't resume when it dies at 3 a.m. If you're scoring against CMS-HCC, the practical answer is to push the population through a managed Batch RAF API and keep your code as an orchestrator. That API is a 3-step async job, not a "POST a file, get JSON back" call — get that shape right and the rest is easy.

1. Submit, poll, download (3 steps)

Base URL https://www.vbcriskanalytics.com/raf-batch-api. Every request needs two headers — ApiKey: <your-batch-key> and an empty X-CSRF-TOKEN: (it's not Bearer).

# Step 1: submit as multipart/form-data -> returns a raf_batch_id
curl -X POST 'https://www.vbcriskanalytics.com/raf-batch-api/getPreProspectScore' \
  -H 'accept: */*' -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=@input_pre_prospective.csv;type=text/csv'
# -> {"code":201,"raf_batch_id":3400,"status":"Queued",
#     "check_status_url":".../raf-batch-api/check-status/3400"}

# Step 2: poll until Completed (Queued 201 -> Running 202 -> Completed 200)
curl '.../raf-batch-api/check-status/3400' -H "ApiKey: $RAF_BATCH_API_KEY" -H 'X-CSRF-TOKEN: '

# Step 3: get the signed download URL
curl '.../raf-batch-api/download/3400' -H "ApiKey: $RAF_BATCH_API_KEY" -H 'X-CSRF-TOKEN: '
# -> {"download_url":"https://...s3.amazonaws.com/...zip?X-Amz-...","status":"Completed"}

# Step 4: GET that S3 URL directly — NO ApiKey header, it EXPIRES in ~120s.
#          You get a .zip with a timestamped .xlsx of scored members.

Submit endpoints map to score types: /getPreProspectScore, /getPostProspectScore, /getPostCncntScore.

2. Get the CSV schema right — one row per (member, diagnosis)

This trips people up: it's not one row per member. Rows are grouped by ID:

ID,Gender,Age,ICD-10 CM Code,Flag
1,Male,65,E1122,Last_Year
1,Male,65,J449,Current_Year
2,Male,84,E1142,Last_Year

Gender is Male/Female, Age ≤ 125, the dot in the ICD-10 code is optional, and valid Flag values depend on score type (Pre-Prospective Last_Year/Current_Year; Post-Prospective New/Billed/Missed; Post-Concurrent No_Changes/Deletion/Addition plus a Modification_To column).

3. For throughput, fan out jobs and poll asynchronously

Split the population into CSV chunks, submit them all, then poll each to Completed:

import os, time, requests
BASE = "https://www.vbcriskanalytics.com/raf-batch-api"
H = {"ApiKey": os.environ["RAF_BATCH_API_KEY"], "X-CSRF-TOKEN": ""}

def submit(path):
    with open(path, "rb") as f:
        r = requests.post(f"{BASE}/getPreProspectScore", headers=H,
            data={"risk_model": "CMS-HCC-V28 Continuing Enrollee",
                  "risk_factor": "Community NonDual Aged"},
            files={"file": ("input.csv", f, "text/csv")})
    return r.json()["raf_batch_id"]

jobs = [submit(p) for p in chunk_paths]          # submit all chunks
for jid in jobs:                                 # then poll each
    while requests.get(f"{BASE}/check-status/{jid}", headers=H).json()["status"] != "Completed":
        time.sleep(5)
    url = requests.get(f"{BASE}/download/{jid}", headers=H).json()["download_url"]
    open(f"scored_{jid}.zip", "wb").write(requests.get(url).content)  # signed URL, no ApiKey

4. Make it idempotent

The API returns a durable raf_batch_id and a check-status URL, so persist those per chunk. A re-run can reattach to in-flight jobs instead of resubmitting them — a 3 a.m. failure becomes a cheap retry, not a full restart, and it doesn't waste your available hits quota.

A couple of gotchas

Validate before you submit so you don't burn quota on bad rows. The API returns specific codes: 418 invalid gender, 419 age > 125, 420 columns missing, 427 only CSV allowed, 429 invalid flag, 425/426 invalid risk model/factor, 430 license/limit.
Store the risk_model/risk_factor you submitted with each output so historical scores stay reproducible for audits.

Wrapping up

If you'd rather not maintain the model tables and hierarchies yourself, there's a good writeup on a managed approach to batch RAF scoring for large member populations, and the batch RAF API that handles the overnight throughput.

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

Engineering a Defensible Suspect-Condition Pipeline (Identify Validate Capture)

VBC Risk Analytics — Sat, 18 Jul 2026 02:56:28 +0000

Suspect-condition workflows are deceptively simple to prototype and surprisingly hard to make defensible. Anyone can flag "this member might have HCC X." Building a system whose output survives a RADV audit is a different problem. This is a walkthrough of the three stages and the engineering decisions that matter at each.

Stage 1: Identify

Identification is pattern detection over a member's clinical record — labs, medications, prior diagnoses, utilization. Model it as a set of rules or features that emit candidate HCCs:

def identify_suspects(member):
    suspects = []
    if member["labs"].get("a1c", 0) >= 9.0 and "insulin" in member["meds"]:
        suspects.append({"hcc": "HCC38", "trigger": "a1c>=9 + insulin"})
    if member.get("egfr") and member["egfr"] < 30:
        suspects.append({"hcc": "HCC326", "trigger": "egfr<30"})
    return suspects

The temptation is to maximize recall here — flag everything. Resist it. Every unvalidated suspect you generate is downstream work and downstream risk.

Stage 2: Validate (the stage that actually matters)

Validation attaches evidence to each suspect and scores its defensibility. This is the difference between a documentation opportunity and an audit liability.

def validate(suspect, member):
    evidence = collect_evidence(suspect["hcc"], member)  # labs, rx, prior dx
    suspect["evidence"] = evidence
    suspect["confidence"] = score_evidence(evidence)
    suspect["defensible"] = suspect["confidence"] >= 0.7
    return suspect

Key design rule: a suspect with an empty evidence array should never reach a coder. Make that a hard gate, not a soft warning. Under CMS-HCC V28 and current audit posture, a captured-but-unsupported diagnosis can be extrapolated across a contract into a real clawback — so "defensible by default" is the right engineering stance.

Stage 3: Capture

Capture routes validated suspects to the right human with the evidence inline, so the clinician or coder can confirm and document efficiently:

{ "member_id": "SYNTH-50921",
  "hcc": "HCC38",
  "confidence": 0.86,
  "evidence": ["a1c:9.4", "rx:insulin_glargine", "prior_dx:E11.65"],
  "action": "confirm_and_document" }

Track two metrics relentlessly: validated-suspect capture rate and audit-fail rate of captured codes. They tell you whether the pipeline produces durable revenue or just volume.

Don't reinvent the model layer

The mapping from clinical signals to HCCs — and the V28 weighting behind it — is version-sensitive and audit-relevant. Grounding the pipeline on a maintained engine for suspect conditions risk adjustment saves you from owning a copy of the model tables that drifts out of date.

The non-code framing of the same workflow is in Suspect Conditions: Identify, Validate, Capture.

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

Building a Population Health Risk Stratification Pipeline for MA Plans

VBC Risk Analytics — Wed, 15 Jul 2026 15:57:58 +0000

Risk stratification sounds like a data-science buzzword until you have to build the thing. For a Medicare Advantage plan, it's a concrete pipeline: take a population of members, score each one's clinical and financial risk, and rank them so care management and documentation teams know who to touch first. Here's how I'd architect it.

The core idea

Population health risk stratification = scoring + segmentation. You compute a per-member risk signal, then bucket members into tiers (e.g., rising-risk, high-risk, catastrophic) so finite resources go where they move outcomes and revenue most.

The mistake teams make is treating it as a single ML model. In practice you want a layered signal: a stable, explainable base (RAF + chronic conditions) plus optional predictive overlays. Explainability matters because care managers won't act on a black-box score, and auditors won't accept one.

Step 1: Build the member feature record

{
  "member_id": "SYNTH-77310",
  "age": 73,
  "hccs": ["HCC37_1", "HCC85", "HCC18"],
  "raf": 1.842,
  "gaps": ["a1c_overdue", "no_pcp_visit_180d"],
  "utilization": { "ed_visits_12m": 3, "inpatient_12m": 1 }
}

The RAF here is your defensible, model-grounded risk anchor under CMS-HCC V28. Everything else is supplemental signal.

Step 2: Score and tier

def risk_tier(member):
    base = member["raf"]
    util = 0.15 * member["utilization"]["ed_visits_12m"] \
         + 0.30 * member["utilization"]["inpatient_12m"]
    score = base + util
    if score >= 3.0:   return "catastrophic"
    if score >= 1.8:   return "high"
    if score >= 1.0:   return "rising"
    return "stable"

Keep the weights transparent and tunable. The point isn't a perfect model; it's a defensible, reproducible ranking your operational teams trust.

Step 3: Make "rising-risk" actionable

The tier that quietly drives the most ROI is rising-risk — members trending toward high cost who still have open documentation and care gaps. Surface their specific gaps (overdue labs, undocumented chronic conditions) so outreach has a concrete target instead of a vague "high risk" label.

Step 4: Close the loop with documentation

Stratification that doesn't feed back into documentation is half a system. When a rising-risk member has a suspected-but-undocumented chronic condition, that's both a care opportunity and a RAF-accuracy opportunity. The pipeline should emit those as work items.

Don't rebuild the risk model from scratch

You can hand-roll feature engineering, but the HCC mapping and V28 weighting logic is fiddly, version-sensitive, and audit-relevant. It's worth grounding the pipeline on a maintained VBC Risk Analytics population health risk stratification engine rather than maintaining your own copy of the model tables.

For the non-engineering framing of how MA plans use stratification operationally, see Population Health Risk Stratification for MA Plans.

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

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.

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.