> ## Documentation Index
> Fetch the complete documentation index at: https://docs.medlistiq.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Enrichments catalog

> Every semantic enrichment MedListIQ adds to raw FHIR medication data.

<Note>
  This catalog documents enrichments produced by **`/v1/medications/infer`**
  (the FHIR endpoint). The PDF endpoint
  (**`/v1/med-lists/from-documents`**) runs many of the same enrichments
  — route codes, dose form, ingredient details — but folds them
  directly into the response fields instead of surfacing a separate
  `enrichments[]` list. See [Med lists from PDFs](/from-documents#response-shape)
  for the PDF response shape.
</Note>

MedListIQ accepts messy, under-coded FHIR and returns clean, standards-rich
medication data. "Enrichment" means: we took a free-text value, a missing code,
or an implicit concept — and added the explicit terminology codes that
downstream systems need.

Every enrichment is deterministic and rule-based. The full list of what we
applied to a given medication is surfaced in `provenance[med_id].enrichments`
when you request `verbosity="full"`.

## Medication identity

### RxNorm canonicalization

Raw input often contains free-text drug names, NDC codes, branded names, or
locally-coded medications. We map them to a canonical RxNorm coding and stamp
every medication with it — so downstream systems can rely on a single
consistent code per drug regardless of where the data originated.

* **System**: `http://www.nlm.nih.gov/research/umls/rxnorm`

### Deduplication

The same drug can appear as a `MedicationRequest` from the EHR, a
`MedicationDispense` from the pharmacy, and a `MedicationStatement` reported by
the patient — sometimes with different display strings, different codings, or
no code at all. We reconcile them into one `InferredMedication` per drug, the
way a pharmacist would read across the sources and consolidate.

### Dose form inference

Tablet, capsule, patch, solution, suspension — inferred from the canonical
drug record when the input didn't carry a discrete `form` field.

### Display name cleanup

SNOMED display strings ship with semantic tags like `"Oral route (qualifier
value)"`. We strip the parenthetical tags so UIs can render clean labels
(`"Oral route"`) without post-processing.

## Dosage semantics

### Routes

Free-text routes like `"oral"`, `"by mouth"`, or `"PO"` get mapped to both
**SNOMED CT** and **NCI Thesaurus** codings.

* **SNOMED**: `http://snomed.info/sct` — e.g., `26643006` (Oral route)
* **NCIT**: `http://ncicb.nci.nih.gov/xml/owl/EVS/Thesaurus.owl` — e.g., `C38288` (Oral)

### Administration methods

Method text (`"inject"`, `"infuse"`, `"apply topically"`) gets mapped to
SNOMED CT + NCIT.

* **SNOMED**: method concepts under `129445006` (Administration — action)
* **NCIT**: procedure concepts

### Frequency

Prescription-style frequency abbreviations and natural-language phrases are
mapped into standard code systems:

* **FHIR v3 GTSAbbreviation**: `http://terminology.hl7.org/CodeSystem/v3-GTSAbbreviation` — `QD`, `BID`, `TID`, `QID`, `QHS`, `PRN`, etc.
* **NCIT**: matching frequency concepts for interop with NCI-coded systems

### Timing events

Textual timing anchors like `"at bedtime"`, `"in the morning"`, `"with meals"`
are mapped to FHIR's event-timing and v3 TimingEvent vocabularies:

* **FHIR event-timing**: `http://hl7.org/fhir/event-timing` — `MORN`, `AFT`, `EVE`, `NIGHT`
* **v3 TimingEvent**: `http://terminology.hl7.org/CodeSystem/v3-TimingEvent` — `HS` (bedtime), `AC` (before meals), `PC` (after meals)

### Duration extraction

Duration phrases in free-text sig strings (`"for 7 days"`, `"x 10 days"`) are
parsed out and surfaced as structured `duration` objects with UCUM units.

* **UCUM**: `http://unitsofmeasure.org` — `d` (day), `wk` (week), `mo` (month)

### Dose quantity + range

Numeric dose fields are surfaced with explicit UCUM units. Ranges like
`"1-2 tablets"` are preserved as structured `low`/`high` rather than flattened.

## Clinical context

### Indications

`reasonCode` free-text and partial codings are enriched with both SNOMED CT
and ICD-10-CM where mappings are available.

* **SNOMED**: `http://snomed.info/sct`
* **ICD-10-CM**: `http://hl7.org/fhir/sid/icd-10-cm`

## Prescription-label sig

A human-readable `sig` string is composed from the structured dosage fields —
the kind of string a pharmacist or patient would see on a prescription label.
Example:

> `"Take 1 tablet by mouth twice daily with meals for 10 days"`

This is built from the enriched dosage components — route, frequency, timing
events, duration — not from the original free-text `patientInstruction`. If
the input was fully structured with no sig text, we still produce one.

## Status + confidence

Each medication is stamped with a `status` (`active`, `completed`, `stopped`,
`cancelled`, `unknown`) and a `confidence` score. This is inference, not
enrichment of source fields — see the [Understanding the output
guide](/guides/understanding-output) for the signal logic and confidence math.

## What gets reported

When you request `verbosity="full"`, every enrichment we applied appears in
the provenance block:

```json theme={null}
{
  "provenance": {
    "med_abc123": {
      "sources": ["MedicationRequest/mr-1", "MedicationDispense/md-1"],
      "evidence": ["active_order", "recent_dispense"],
      "enrichments": [
        "rxnorm_canonicalized",
        "route_snomed_added",
        "route_ncit_added",
        "frequency_coded",
        "dose_form_inferred",
        "sig_composed"
      ]
    }
  }
}
```

This is the audit trail. Every terminology code in the response is accounted
for — either present in the input, or added by an enrichment with a named tag.