FHIRfly
Dashboard

HCC Crosswalk API

Look up CMS Hierarchical Condition Category (HCC) risk adjustment mappings for ICD-10 diagnosis codes.

Overview

HCC (Hierarchical Condition Categories) is the risk adjustment model used by CMS for Medicare Advantage payment. FHIRfly provides fast lookups against the CMS HCC crosswalk, mapping ICD-10-CM diagnosis codes to condition categories across multiple model versions. Supports payment year 2026 with models V08, V21, V22, V24, and V28.

Endpoints

Method Path Description
GET /v1/hcc/:code Single ICD-10 to HCC lookup
POST /v1/hcc/_batch Batch lookup (up to 100)
GET /v1/hcc/reverse/:ccNumber Reverse lookup: find ICD-10 codes for an HCC
GET /v1/hcc/shapes List available response shapes

Single Lookup

Look up HCC mappings for Type 2 diabetes

Request
Node.js
const response = await fetch(
  "https://api.fhirfly.io/v1/hcc/E11.9",
  {
    method: "GET",
    headers: {
    "x-api-key": "YOUR_API_KEY",
  }
  }
);

const data = await response.json();
console.log(data);
Response
JSON
{
  "data": {
    "icd10_code": "E119",
    "icd10_display": "Type 2 diabetes mellitus without complications",
    "mappings": [
      {
        "model_version": "V28",
        "cc_number": "37",
        "cc_label": "Diabetes Mellitus without Complication",
        "payment_year": 2026
      },
      {
        "model_version": "V24",
        "cc_number": "19",
        "cc_label": "Diabetes without Complication",
        "payment_year": 2026
      }
    ]
  },
  "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"
    }
  }
}

Common HCC Mappings

ICD-10 Code Description HCC (V28)
E11.9 Type 2 diabetes without complications 37
I50.9 Heart failure, unspecified 226
J44.1 COPD with acute exacerbation 328
N18.3 Chronic kidney disease, stage 3 329
C50.911 Malignant neoplasm of breast 23

Batch Lookup

Look up multiple ICD-10 codes in a single request (up to 100):

Look up HCC mappings for multiple diagnoses

Request
Node.js
const response = await fetch(
  "https://api.fhirfly.io/v1/hcc/_batch",
  {
    method: "POST",
    headers: {
    "x-api-key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
    body: JSON.stringify({
    "codes": [
      "E11.9",
      "I50.9",
      "J44.1"
    ]
  })
  }
);

const data = await response.json();
console.log(data);
Response
JSON
{
  "count": 3,
  "results": [
    {
      "input": "E11.9",
      "code": "E11.9",
      "status": "ok",
      "data": {
        "icd10_display": "Type 2 diabetes mellitus without complications",
        "mappings": [
          {
            "model_version": "V28",
            "cc_number": "37",
            "cc_label": "Diabetes Mellitus without Complication"
          }
        ]
      }
    },
    {
      "input": "I50.9",
      "code": "I50.9",
      "status": "ok",
      "data": {
        "icd10_display": "Heart failure, unspecified",
        "mappings": [
          {
            "model_version": "V28",
            "cc_number": "226",
            "cc_label": "Heart Failure"
          }
        ]
      }
    },
    {
      "input": "J44.1",
      "code": "J44.1",
      "status": "ok",
      "data": {
        "icd10_display": "Chronic obstructive pulmonary disease with acute exacerbation",
        "mappings": [
          {
            "model_version": "V28",
            "cc_number": "328",
            "cc_label": "Chronic Obstructive Pulmonary Disease"
          }
        ]
      }
    }
  ],
  "meta": {
    "legal": {
      "license": "public_domain"
    }
  }
}

Batch with shape=full

When using shape=full on batch requests, the response includes meta.source with provenance information:

POST /v1/hcc/_batch?shape=full

{
  "count": 3,
  "results": [
    {
      "input": "E11.9",
      "code": "E11.9",
      "status": "ok",
      "data": {
        "icd10_display": "Type 2 diabetes mellitus without complications",
        "mappings": [
          { "model_version": "V28", "cc_number": "37", "cc_label": "Diabetes Mellitus without Complication" }
        ]
      }
    }
  ],
  "meta": {
    "source": {
      "name": "CMS HCC",
      "url": "https://www.cms.gov/medicare/payment/medicare-advantage-rates-statistics/risk-adjustment",
      "version": "PY2026",
      "fhirfly_updated_at": "2026-03-01T03:00:00Z"
    },
    "legal": {
      "license": "public_domain",
      "attribution_required": false
    }
  }
}

Reverse Lookup

Find all ICD-10 codes that map to a specific HCC condition category:

Find ICD-10 codes for HCC 37 (Diabetes without Complication)

Request
Node.js
const response = await fetch(
  "https://api.fhirfly.io/v1/hcc/reverse/37",
  {
    method: "GET",
    headers: {
    "x-api-key": "YOUR_API_KEY",
  }
  }
);

const data = await response.json();
console.log(data);
Response
JSON
{
  "data": {
    "cc_number": "37",
    "cc_label": "Diabetes Mellitus without Complication",
    "model_version": "V28",
    "icd10_codes": [
      {
        "code": "E119",
        "display": "Type 2 diabetes mellitus without complications"
      },
      {
        "code": "E139",
        "display": "Other specified diabetes mellitus without complications"
      }
    ],
    "total": 2
  },
  "meta": {
    "legal": {
      "attribution_required": false,
      "license": "public_domain",
      "source_name": "CMS HCC"
    }
  }
}

You can filter reverse lookups by model version using the model_version query parameter:

GET /v1/hcc/reverse/19?model_version=V24

Model Versions

FHIRfly supports the following CMS-HCC risk adjustment models:

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

Use the model_version query parameter to filter results to a specific model:

GET /v1/hcc/E11.9?model_version=V28

Response Shapes

Control the level of detail in responses with the shape query parameter:

Shape Description
compact ICD-10 code, display, CC numbers
standard + model versions, CC labels, payment year
full + ingest metadata, provenance 
# Minimal data
GET /v1/hcc/E11.9?shape=compact

# Standard data (default)
GET /v1/hcc/E11.9?shape=standard

# Full data with provenance
GET /v1/hcc/E11.9?shape=full

See Response Shapes for field details.

Required Scopes

  • hcc.read - Single, batch, and reverse lookups

See Also