FHIRfly
Dashboard

HCC Crosswalk Search

Search CMS HCC risk adjustment crosswalk data.

Endpoint

GET /v1/hcc/search

Quick Start

Node.js
import { Fhirfly } from "@fhirfly-io/terminology";

const client = new Fhirfly({ apiKey: "YOUR_API_KEY" });

// Search for diabetes-related HCC mappings
const results = await client.hcc.search({
  q: "diabetes"
});

console.log(`Found ${results.total} mappings`);
for (const item of results.items) {
  console.log(`${item.icd10_code}: ${item.cc_label} (HCC ${item.cc_number})`);
}

Parameters

Text Search

Parameter Description Example
q General text search across ICD-10 descriptions and CC labels q=diabetes

Filters

Parameter Type Description Example
model_version string HCC model version V28, V24, V22
model_type string Model type community, institutional
cc_number string Condition category number 37
payment_year number Payment year 2026

Pagination & Response

Parameter Default Max Description
limit 20 100 Results per page
page 1 100 Page number
shape compact --- compact, standard, full
sort relevance --- relevance, cc_number, icd10_code

Example Response

{
  "facets": {
    "model_version": {
      "V28": 42,
      "V24": 38,
      "V22": 35
    },
    "payment_year": {
      "2026": 42
    }
  },
  "has_more": true,
  "items": [
    {
      "icd10_code": "E119",
      "icd10_display": "Type 2 diabetes mellitus without complications",
      "cc_number": "37",
      "cc_label": "Diabetes Mellitus without Complication",
      "model_version": "V28"
    },
    {
      "icd10_code": "E1165",
      "icd10_display": "Type 2 diabetes mellitus with hyperglycemia",
      "cc_number": "37",
      "cc_label": "Diabetes Mellitus without Complication",
      "model_version": "V28"
    }
  ],
  "limit": 2,
  "meta": {
    "legal": {
      "attribution_required": false,
      "citation": "CMS HCC Risk Adjustment Model. CMS.gov. Accessed 2026-03-15 via FHIRfly.",
      "license": "public_domain",
      "source_name": "CMS HCC"
    }
  },
  "page": 1,
  "total": 42,
  "total_capped": false
}

Use Cases

Find All Mappings for a Condition Category

Node.js
const results = await client.hcc.search({
  cc_number: "37",
  model_version: "V28"
});

Search by Diagnosis Description

Node.js
const results = await client.hcc.search({
  q: "heart failure",
  model_version: "V28"
});

Compare Across Model Versions

Node.js
// Find diabetes mappings in V24
const v24 = await client.hcc.search({
  q: "diabetes",
  model_version: "V24"
});

// Find diabetes mappings in V28
const v28 = await client.hcc.search({
  q: "diabetes",
  model_version: "V28"
});

Filter by Payment Year

Node.js
const results = await client.hcc.search({
  q: "chronic kidney",
  payment_year: 2026
});

Facets

HCC search returns these facets:

Facet Description
model_version Distribution by HCC model version
payment_year Distribution by payment year

Valid Values

Model Versions

  • V08 — Legacy community model
  • V21 — Community, non-dual aged
  • V22 — Community, non-dual aged (updated)
  • V24 — Community model (2020+)
  • V28 — Community model (2024+, current)

Required Scope

hcc.search

See Also