Data Enrichment
How Zus normalizes codes, adds groupings, classifies encounters and parses CDAs, without overwriting the original codings.
Clinical data is messy. Zus helps by cleaning up real-world data with our enrichment and aggregation engines to make data more usable and easier to query.
What is Data Enrichment?
Normalization: Mapping codes between terminologies (e.g., ICD10 to SNOMED) can be a pain. Zus aims to have as consistent coverage as possible for a preferred terminology so that you don’t have to do all the crosswalks. We do not require you to write in our preferred terminology as terminologies can perform different functions for different use cases, but it wouldn’t hurt!
Grouping: Zus tags resources with context-appropriate categories where possible (e.g., "Type 1 Diabetes with Complications" and "Type 2 Diabetes with Complications" would be grouped under “END03: Diabetes with Complications”). You can use these groupings to ask questions such as “which of my patients have diabetes?” Adding groupings to the original resources themselves reduces the complexity of your API calls so you don’t have to reference a different resource or mapping file.
Zus never overwrites original codings on a resource. Zus only adds enriched codings alongside the original codings in a clearly denoted manner so you know which code is original and which is Zus-enriched.
Conditions
Normalization
All coding is normalized to SNOMED wherever possible. ICD-9 codes will be translated into ICD-10 when an unambiguous (1:1 or Many:1) mapping is available.
Example raw codeable concept:
"code": {
"coding": [
{
"system": "urn:oid:2.16.840.1.113883.6.104",
"code": "401.9",
"display": "- HTN 401.9"
}
]
}Example Zus enriched codeable concept:
"code": {
"coding": [
{
"system": "urn:oid:2.16.840.1.113883.6.104",
"code": "401.9",
"display": "- HTN 401.9"
},
{
"extension": [
{
"url": "<https://zusapi.com/terminology/enrichment>",
"valueString": "ICD10"
}
],
"system": "<http://hl7.org/fhir/sid/icd-10>",
"code": "I16.9",
"display": "Hypertensive crisis, unspecified",
"userSelected": false
},
{
"extension": [
{
"url": "<https://zusapi.com/terminology/enrichment>",
"valueString": "SNOMED"
}
],
"system": "<http://snomed.info/sct>",
"code": "706882009",
"display": "Hypertensive crisis",
"userSelected": false
}
]
}Making a standard API call to view a Condition will show the enrichments:
GET {{fhir_url}}/Condition?_id=[unique condition id]
Groupings
Grouping codes for condition resources are primarily based on ICD-10 codes, though many condition resources may only have SNOMED codes. Zus typically will not “reverse map” SNOMED to ICD-10 because 1) there is typically a one-to-many relationship between SNOMED and ICD-10 and 2) Zus does not want to give the appearance that a condition was billed for without evidence (ICD-10 codes are used for billing). However, in limited circumstances we can provide an ICD-10-based grouping code for resources that only have a SNOMED code. Zus will provide the following groupings on condition resources where available.
Chronic Condition Indicator (CCI)
The Chronic Condition Indicator for ICD-10-CM (beta version) facilitates health services research by allowing the researcher to readily identify a diagnosis as indicating a chronic condition.
| Indicator | Examples |
|---|---|
| Chronic | Malignant cancer, diabetes, obesity, hypertension, and many mental health conditions |
| Acute | Aortic embolism, bacterial infection, pregnancy, and an initial encounter for an injury |
| Both | Persistent asthma with (acute) exacerbation, acute on chronic heart failure, and kidney transplant rejection |
| Not applicable* | External cause of morbidity codes, injury sequela codes, and codes starting with the letter Z for screening or observation. |
*Code cannot be used to identify a chronic or acute condition
Example:
{
"extension": [
{
"url": "<https://zusapi.com/terminology/enrichment>",
"valueString": "CCI"
}
],
"system": "<http://www.hcupus.ahrq.gov/toolssoftware/chronic_icd10/chronic_icd10.jsp>",
"code": "C",
"display": "Chronic",
"userSelected": false
}Clinical Classifications Software (CCS)
The Clinical Classifications Software Refined (CCSR) aggregates International Classification of Diseases, 10th Revision, Clinical Modification/Procedure Coding System (ICD-10-CM/PCS) codes into clinically meaningful categories.
Example:
{
"extension": [
{
"url": "<https://zusapi.com/terminology/enrichment>",
"valueString": "CCS"
}
],
"system": "<https://www.hcup-us.ahrq.gov/toolssoftware/ccsr/dxccsr.jsp>",
"code": "CIR008",
"display": "Hypertension with complications and secondary hypertension",
"userSelected": false
}Hierarchical Condition Categories (HCC)
CMS developed risk adjustment categories designed for use in the grouping of ICD-10 codes within the Medicare population.
Example:
{
"extension": [
{
"url": "https://zusapi.com/terminology/enrichment",
"valueString": "HCC"
}
],
"system": "http://terminology.hl7.org/CodeSystem/cmshcc",
"code": "59",
"display": "Major depressive disorder, single episode, mild",
"userSelected": false
}Medications
Normalization
All coding is normalized to RxNorm where possible. We will also check on the existing RxNorm code and display value and add the most up to date version into the extension. Zus enriches the following Medication-related resources: MedicationStatement, MedicationRequest, MedicationDispense, MedicationAdministration.
Example original codeable concept:
"coding": [
{
"system": "<http://hl7.org/fhir/sid/ndc>",
"code": "16729-002-01",
"display": "Glimepiride 2 MG"
}
]Example enriched codeable concept:
"coding": [
{
"system": "<http://hl7.org/fhir/sid/ndc>",
"code": "16729-002-01",
"display": "Glimepiride 2 MG"
},
{
"extension": [
{
"url": "<https://zusapi.com/terminology/enrichment>",
"valueString": "Standardization"
}
],
"system": "<http://www.nlm.nih.gov/research/umls/rxnorm>",
"code": "199246",
"display": "glimepiride 2 MG Oral Tablet",
"userSelected": false
}
]Making a standard API call to view a Medication-related resource will show the enrichments:
GET {{fhir_url}}/MedicationStatement?_id=[unique medication statement id]
Groupings
All grouping codes for medication activity resources are derived from RxNorm. Zus will provide the following related codes when they are available:
- Active Ingredient
- Brand Name
- Clinical Drug (TTY: SCD): The Clinical Drug level of RxNorm allows grouping of drugs by their active ingredient, route, and strength allowing you to roll-up both generic and branded drugs.
Active Ingredient Example:
{
"extension": [
{
"url": "<https://zusapi.com/terminology/enrichment>",
"valueString": "ActiveIngredient"
}
],
"system": "<http://www.nlm.nih.gov/research/umls/rxnorm>",
"code": "25789",
"display": "glimepiride",
"userSelected": false
}Brand Name Example:
{
"extension": [
{
"url": "<https://zusapi.com/terminology/enrichment>",
"valueString": "BrandName"
}
],
"system": "<http://www.nlm.nih.gov/research/umls/rxnorm>",
"code": "153592",
"display": "Amaryl",
"userSelected": false
}Clinical Drug Example:
{
"extension": [
{
"url": "<https://zusapi.com/terminology/enrichment>",
"valueString": "ClinicalDrug_TTY_SCD"
}
],
"system": "<http://www.nlm.nih.gov/research/umls/rxnorm>",
"code": "199246",
"display": "glimepiride 2 MG Oral Tablet",
"userSelected": false
}Encounters
Normalization
Where possible, the encounter class is enriched to the HL7 ActEncounter code resulting in one of the following Encounter.class codes: AMB, EMER, HH, IMP, OBSENC, PRENC, or VR.
Example
Example of type enrichment where only a CPT is available:
"resourceType": "Encounter",
"type": [
{
"coding": [
{
"system": "http://www.ama-assn.org/go/cpt",
"code": "99213"
}
]
}
],
Will be enriched to have an AMB type code.
"type": [
{
"coding": [
{
"system": "http://www.ama-assn.org/go/cpt",
"code": "99213"
},
{
"extension": [
{
"url": "https://zusapi.com/terminology/enrichment",
"valueString": "ActEncounterCode"
}
],
"system": "http://terminology.hl7.org/CodeSystem/v3-ActCode",
"code": "AMB",
"display": "ambulatory",
"userSelected": false
}
]
}
],Example of an enrichment where encounter class code and display are mismatched would be enriched from this:
"class": {
"system": "http://terminology.hl7.org/CodeSystem/v3-ActCode",
"code": "AMB",
"display": "Hospital Encounter"
},to this:
"type": [
{
"coding": [
{
"extension": [
{
"url": "https://zusapi.com/terminology/enrichment",
"valueString": "ActEncounterCode"
}
],
"system": "http://terminology.hl7.org/CodeSystem/v3-ActCode",
"code": "IMP",
"display": "inpatient",
"userSelected": false
}
]
}
],ADT Encounter Classification
Since July 21, 2026, Zus derives Encounter.class more accurately for encounters from ADT feeds. Before, an ADT encounter could get the wrong class, such as IMP for an outpatient or emergency visit. That class could carry into the Transition of Care Lens and create an inpatient episode that didn't happen.
- Radiology encounters are classified as ambulatory (
AMB). - Encounters with no usable class or type aren't used to create Transitions of Care.
These changes apply to Encounter and EpisodeOfCare resources automatically. See the changelog post.
Discharge Disposition
Since June 22, 2026, Zus normalizes Encounter.hospitalization.dischargeDisposition to the NUBC value set, http://www.nubc.org/patient-discharge. Before, the value passed through as it arrived from the source, so the same outcome could show up under different code systems.
- Zus maps each incoming coding with a fixed, first-match-wins set of rules.
- A recognized coding is replaced in place with its NUBC system, code and display.
- An unrecognized coding passes through unchanged. The original value is never dropped.
Outcomes such as home, skilled nursing facility, transfer, against medical advice and expired are now consistent across sources. The normalized value also appears in ZusHook payloads. See the changelog post.
CDA Parsing
These changes to how Zus turns CDA documents into FHIR resources took effect June 1, 2026. See the changelog post.
Negated Conditions and Allergies
When a CDA problem or allergy entry has negationInd="true", Zus writes a clear "no known" entry instead of a generic condition that just reads "Problem":
| Resource | SNOMED CT code | Display |
|---|---|---|
| Condition | 160245001 | No known problems |
| AllergyIntolerance | 716186003 | No known allergy |
Dependent Coverage
Zus creates a Coverage resource for every active CoverageRoleType relationship in a CDA, not only for policies the patient holds. For example, when the patient is listed as a dependent (famdep), the Coverage includes subscriber and policyHolder if the CDA has them.
Related pages
Updated 15 days ago