Feb 4, 2026: Improved HCC Version Clarity in Conditions

We’ve updated how HCC (Hierarchical Condition Category) codes are represented and displayed to make CMS versioning clearer and reduce ambiguity across data and UI.

What Changed

• Explicit HCC versioning on Conditions: HCC codings now include a version field (e.g., v24 or v28), allowing you to clearly identify which CMS risk model a condition is associated with. This applies to both Lens-enriched condition views and Raw Condition resources. Lens resources will have both versions listed when appropriate.

[
  {
    "url": "https://zusapi.com/lens/extension/relatedCoding",
    "valueCoding": {
      "code": "96",
      "display": "Specified Heart Arrhythmias",
      "system": "http://terminology.hl7.org/CodeSystem/cmshcc",
      "version": "v24"
    }
  },
  {
    "url": "https://zusapi.com/lens/extension/relatedCoding",
    "valueCoding": {
      "code": "238",
      "display": "Specified Heart Arrhythmias",
      "system": "http://terminology.hl7.org/CodeSystem/cmshcc",
      "version": "v28"
    }
  }
]

{
  "code": "238",
  "display": "Specified Heart Arrhythmias",
  "extension": [
    {
      "url": "https://zusapi.com/terminology/enrichment",
      "valueString": "CMSHCC"
    }
  ],
  "system": "http://terminology.hl7.org/CodeSystem/cmshcc",
  "userSelected": false,
  "version": "v28"
}

• Datamart behavior: HCC version information is available in data marts on raw Condition records only, via CMS HCC–specific columns for v24 and v28 in the Condition table. This information is not exposed in the lens-based condition tables such as lens_snomed_condition.
• Updated ZAP display: In the ZAP Conditions list, the HCC indicator (pill) is shown only for v28 HCCs, aligning the UI with the current CMS model and avoiding confusion when multiple HCC versions exist for the same clinical condition.

Together, these changes make it easier for clinical, product, and analytics teams to reason about condition risk, reporting, and downstream use cases with confidence.