Risk Adjustment FHIR Models

Note that Zus Risk Adjustment features are currently in public preview and are subject to change.

Risk adjustment data is stored as FHIR MeasureReport resources. There are two types:

Resource Type	Profile	Logical Identity	Purpose
Risk Gap	`individual-risk-gap`	patient + calendar year + HCC code	A potential diagnosis/coding gap for a single HCC
RAF Score	`raf-score-measure-report`	patient + builder + calendar year	Aggregated risk scores (potential, expected, actual) for a patient

Risk Gap MeasureReport

A Risk Gap represents a single HCC gap for a patient and calendar year.

Core fields

Field	Description
`measure`	`http://zusapi.com/quality/measure/risk/CMSv28`
`subject`	Reference to the patient (e.g., `Patient/{id}`).
`period`	Calendar year window (e.g., `2025-01-01` → `2025-12-31`).
`status`	Always `"complete"`.
`type`	Always `"individual"`.
`date`	When the gap was first calculated.

Within group[0] (the HCC group):

Field	Description
`group[0].code`	The HCC v28 code (CodeSystem: `http://terminology.hl7.org/CodeSystem/cmshcc`, version `28`). Any relevant ICD-10 codes (see below).
`group[0].measureScore`	The RAF coefficient for the HCC (when available).

Risk gap extensions

Risk gaps use extensions to capture key workflow and explanation metadata.

Gap type

Item	Value
Extension	`https://zusapi.com/fhir/StructureDefinition/risk/gap-type`
Type	string
Values	`recapture` \| `suspect` \| `net-new`

Confidence level

Item	Value
Extension	`https://zusapi.com/fhir/StructureDefinition/risk/gap-confidence-level`
Type	integer
Values	`1`–`5` (5 = high confidence, 4 = medium confidence, 1-3 = low confidence)

Status update history

Risk gaps maintain a timeline of status updates.

Level	URL / Field	Description
Container	`https://zusapi.com/fhir/StructureDefinition/risk/status-updates`	Extension container holding the status update history.
Element	`https://zusapi.com/fhir/StructureDefinition/risk/status-update`	A single status update entry.
Field	`https://zusapi.com/fhir/StructureDefinition/status`	One of `open-gap`, `closed-gap`, `expected-to-close-1st-party`, `expected-to-close-3rd-party`, `accepted-for-review`, `dismissed`.
Field	`https://zusapi.com/fhir/StructureDefinition/created`	Timestamp when the status was created.
Field	`https://zusapi.com/fhir/StructureDefinition/createdBy`	User/system identifier (e.g., automated calculation vs user action).
Field	`https://zusapi.com/fhir/StructureDefinition/status-source`	Comma-separated list of contributing sources (e.g., rules-based, AI, payer, user).
Field (optional)	`https://zusapi.com/fhir/StructureDefinition/substatuses`	Additional structured categorization (e.g., `resolved`, `acute-in-nature`).
Field (optional)	`https://zusapi.com/fhir/StructureDefinition/note`	Free-text note.

Hierarchy relationships (superseding/superseded)

HCCs can supersede other HCCs based on CMS hierarchy rules. Risk gaps can record those relationships using:

Relationship	Extension URL
Superseded by	`https://zusapi.com/fhir/StructureDefinition/risk/hierarchical-status/superseded-by`
Superseding	`https://zusapi.com/fhir/StructureDefinition/risk/hierarchical-status/superseding`

This allows analytics and UI to distinguish "top-level" gaps from gaps that are effectively covered by a higher-priority HCC.

Related clinical objects

Risk gaps can reference additional clinical context useful for human review (e.g., labs, medications, documents).

Level	URL	Description
Container	`https://zusapi.com/fhir/StructureDefinition/risk/related-clinical-objects`	Extension container holding related clinical objects.
Element	`https://zusapi.com/fhir/StructureDefinition/risk/related-clinical-object`	A single related clinical object reference.

ICD-10 codes

A single risk gap may include one or more ICD-10 codes associated with the HCC. ICD-10 codings can include extensions such as:

URL	Description
`https://zusapi.com/fhir/StructureDefinition/risk/last-encounter-diagnosis-recorded-date`	When that ICD-10 code last appeared as an encounter diagnosis.
`https://zusapi.com/fhir/StructureDefinition/risk/gap-source`	Identifies which source contributed the ICD-10 (e.g., rules-based, AI, payer).

Evidence references (`evaluatedResource`)

Risk gaps use evaluatedResource to link to the inputs that supported the gap:

Evidence type	What you'll see
Rules-based evidence	References to encounter-diagnosis `Condition` resources.
AI suspect evidence	References to supporting evidence resources (often with helpful display context)

Example Risk Gap resource

{
  "resourceType": "MeasureReport",
  "id": "7f8d650f-0721-44c5-b10d-fb5611330f0d",

  "meta": {
    "profile": [
      "https://zusapi.com/fhir/StructureDefinition/risk/individual-risk-gap"
    ]
  },

  "status": "complete",
  "type": "individual",
  "measure": "http://zusapi.com/quality/measure/risk/CMSv28",

  "subject": {
    "reference": "Patient/b8238362-db58-4076-8d72-972e5406b574"
  },
  "reporter": {
    "display": "Zus Health"
  },
  "period": {
    "start": "2026-01-01",
    "end": "2026-12-31"
  },
  "date": "2026-02-12",

  "extension": [
    {
      "url": "https://zusapi.com/fhir/identifier/universal-id",
      "valueString": "9133c588-5e7d-49a4-93ac-e2fa3bab695c"
    },
    {
      "url": "https://zusapi.com/fhir/StructureDefinition/risk/gap-type",
      "valueString": "suspect"
    },
    {
      "url": "https://zusapi.com/fhir/StructureDefinition/risk/gap-confidence-level",
      "valueInteger": 5
    },
    {
      "url": "https://zusapi.com/fhir/StructureDefinition/risk/status-updates",
      "extension": [
        {
          "url": "https://zusapi.com/fhir/StructureDefinition/risk/status-update",
          "extension": [
            {
              "url": "https://zusapi.com/fhir/StructureDefinition/risk/status-update/status",
              "valueString": "open-gap"
            },
            {
              "url": "https://zusapi.com/fhir/StructureDefinition/risk/status-update/created",
              "valueDateTime": "2026-02-12T05:45:44.845Z"
            },
            {
              "url": "https://zusapi.com/fhir/StructureDefinition/risk/status-update/created-by",
              "valueString": "zus-risk-gap-calculator"
            },
            {
              "url": "https://zusapi.com/fhir/StructureDefinition/risk/status-update/status-source",
              "valueString": "zus-rules"
            }
          ]
        }
      ]
    },
    {
      "url": "https://zusapi.com/fhir/StructureDefinition/risk/related-clinical-objects",
      "extension": [
        {
          "url": "https://zusapi.com/fhir/StructureDefinition/risk/related-clinical-object",
          "valueReference": {
            "display": "Serum glucose",
            "reference": "Observation/90592907-870e-473b-9f74-afc5285146c2"
          }
        },
        {
          "url": "https://zusapi.com/fhir/StructureDefinition/risk/related-clinical-object",
          "valueReference": {
            "display": "HbA1c",
            "reference": "Observation/7a759977-fe9c-45d8-8cc3-a1ebaec1153b"
          }
        },
        {
          "url": "https://zusapi.com/fhir/StructureDefinition/risk/related-clinical-object",
          "valueReference": {
            "display": "Lipid Panel",
            "reference": "Observation/90592907-870e-473b-9f74-afc5285146c2"
          }
        }
      ]
    }
  ],

  "group": [
    {
      "id": "risk-gap",
      "code": {
        "text": "HCC 38: Diabetes with Glycemic, Unspecified, or No Complications",
        "coding": [
          {
            "system": "http://terminology.hl7.org/CodeSystem/cmshcc",
            "version": "28",
            "code": "38",
            "display": "Diabetes with Glycemic, Unspecified, or No Complications"
          },
          {
            "system": "http://hl7.org/fhir/sid/icd-10-cm",
            "code": "E11.9",
            "display": "Type 2 diabetes mellitus without complications",
            "extension": [
              {
                "url": "https://zusapi.com/fhir/StructureDefinition/risk/last-encounter-diagnosis-recorded-date",
                "valueDateTime": "2024-11-19"
              },
              {
                "url": "https://zusapi.com/fhir/StructureDefinition/risk/gap-source",
                "valueString": "zus-rules"
              }
            ]
          }
        ]
      },
      "measureScore": {
        "value": 0.166
      }
    }
  ],

  "evaluatedResource": [
    {
      "type": "Condition",
      "reference": "Condition/1ce7da26-81b6-4d89-b2a7-f5f6dcc88f09",
      "display": "ICD-10 Code: E11.9 - Suspect Encounter Diagnosis"
    }
  ]
}

RAF Score MeasureReport

A RAF Score aggregates a patient's risk scores for a calendar year.

Core fields

Field	Description
`measure`	`http://zusapi.com/quality/measure/risk/CMSv28`
`subject`	Reference to the patient (e.g., `Patient/{id}`).
`period`	Calendar year window (e.g., `2025-01-01` → `2025-12-31`).
`status`	Always `"complete"`.
`type`	Always `"individual"`.
`date`	When the score was calculated.

The resource contains three group entries, each representing a different score:

Group ID	Description
`potential-raf-score`	Score if all non-dismissed risk gaps were paid.
`expected-raf-score`	Score using HCCs from gaps with status `expected-to-close-*` or `closed-gap`.
`actual-raf-score`	Score using only HCCs from risk gaps with status `closed-gap` (acknowledged by payer).

RAF Score extensions

Item	Value
Extension	`https://zusapi.com/fhir/StructureDefinition/risk/gap-raf-score-model`
Type	string
Values	`CNA` (Community Non-Dual Aged)

Example RAF Score resource

{
  "resourceType": "MeasureReport",
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",

  "meta": {
    "profile": [
      "https://zusapi.com/fhir/StructureDefinition/risk/raf-score-measure-report"
    ],
    "tag": [
      {
        "system": "https://zusapi.com/lens/owner",
        "code": "builder/abc123"
      }
    ]
  },

  "status": "complete",
  "type": "individual",
  "measure": "http://zusapi.com/quality/measure/risk/CMSv28",

  "subject": {
    "reference": "Patient/b8238362-db58-4076-8d72-972e5406b574"
  },
  "period": {
    "start": "2026-01-01",
    "end": "2026-12-31"
  },
  "date": "2026-02-12",

  "extension": [
    {
      "url": "https://zusapi.com/fhir/StructureDefinition/risk/gap-raf-score-model",
      "valueString": "CNA"
    }
  ],

  "group": [
    {
      "id": "potential-raf-score",
      "measureScore": {
        "value": 1.245
      }
    },
    {
      "id": "expected-raf-score",
      "measureScore": {
        "value": 0.892
      }
    },
    {
      "id": "actual-raf-score",
      "measureScore": {
        "value": 0.654
      }
    }
  ]
}

Risk Gap MeasureReport

Core fields

Risk gap extensions

Gap type

Confidence level

Status update history

Hierarchy relationships (superseding/superseded)

Related clinical objects

ICD-10 codes

Evidence references (evaluatedResource)

Example Risk Gap resource

RAF Score MeasureReport

Core fields

RAF Score extensions

Example RAF Score resource

Evidence references (`evaluatedResource`)