> ## 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.

# Understanding the PDF output

> How to read every field on a `POST /v1/med-lists/from-documents` response — RxNorm specificity, ingredients, doses for combos and packs, coded routes, and the evidence trail.

This guide covers responses from `POST /v1/med-lists/from-documents`. The
FHIR endpoint (`POST /v1/medications/infer`) uses a related but different
response shape — see [Understanding the output](/guides/understanding-output)
for that one.

Every medication on a PDF response has the same shape. Some fields are
null when they don't apply, which the sections below explain.

## How specific is the RxNorm code?

`rxnorm_code` is the RxNorm code we resolved for the medication.
`rxnorm_tty` tells you what kind of RxNorm concept it is.

| `rxnorm_tty`                | What it represents                                    | Good for                                   |
| --------------------------- | ----------------------------------------------------- | ------------------------------------------ |
| `SCD` / `GPCK`              | Generic drug with ingredient, strength, and dose form | Prescribing, dispensing, dose calculations |
| `SBD` / `BPCK`              | Branded drug or pack with all the same detail         | Same, plus brand-aware workflows           |
| `SCDC` / `SBDC`             | Ingredient and strength, no dose form                 | Dose-aware logic that doesn't need a form  |
| `IN` / `PIN` / `MIN` / `BN` | Ingredient level (drug class, not a specific product) | Drug-interaction checks, allergy matching  |

When `rxnorm_tty` is `IN` or `PIN`, treat the medication as a drug-class
identifier. Don't use it for dose-specific reasoning.

`rxnorm_code` is `null` only when no RxNorm match exists. Rare.

## Ingredients

`ingredients[]` lists every active substance in the medication, each
with its strength.

```json theme={null}
"ingredients": [
  {
    "rxnorm_code": "10180",
    "name": "Sulfamethoxazole",
    "rxnorm_tty": "IN",
    "strength_quantity": "800",
    "strength_unit": "mg"
  },
  {
    "rxnorm_code": "10829",
    "name": "Trimethoprim",
    "rxnorm_tty": "IN",
    "strength_quantity": "160",
    "strength_unit": "mg"
  }
]
```

* Single-ingredient drugs have one entry.
* Combos (Bactrim, NuvaRing, amlodipine/valsartan) have one entry per
  ingredient.
* Packs (Trinessa-style 28-day kits) have one entry per distinct
  active ingredient in the pack.

Use the `rxnorm_code` on each ingredient for drug-interaction and
allergy logic. These ingredient-level codes are usually the right key
for class-level matching; the top-level `rxnorm_code` is often too
specific.

`strength_quantity` and `strength_unit` are `null` when we resolved
to an ingredient-only concept, or when no published strength exists
for the concept.

## Doses for single drugs, combos, and packs

`dose_quantity` and `dose_unit` differ depending on the kind of drug.

<AccordionGroup>
  <Accordion title="Single-ingredient drugs">
    A number plus a unit. Example: `"250"` and `"mg"`.

    `dose_quantity` is a string so range values (`"1-2"`) and decimals
    (`"12.5"`) survive verbatim.
  </Accordion>

  <Accordion title="Combo products packaged as one unit">
    A combo packaged as a single tablet, capsule, patch, or ring uses
    `"1"` plus the unit name. Example: Bactrim → `dose_quantity: "1"`,
    `dose_unit: "tablet"`. Per-ingredient strengths live on
    `ingredients[]`.
  </Accordion>

  <Accordion title="Packs (Trinessa-style)">
    Both `dose_quantity` and `dose_unit` are `null` for packs. The
    pack's identity is the `rxnorm_code` and `drug_name`; the breakdown
    is in `ingredients[]`.
  </Accordion>

  <Accordion title="Drugs we couldn't pin a dose on">
    Both are `null` when no dose was found in the source. You'll still
    get an ingredient-level `rxnorm_code` so you can flag the entry for
    clinical review.
  </Accordion>
</AccordionGroup>

## Routes are double-coded

`route` is the short abbreviation (`PO`, `IV`, `VAG`, `TD`, …) every
clinician recognizes. Alongside it we surface the matching SNOMED CT
and NCI Thesaurus codes:

```json theme={null}
"route": "PO",
"route_snomed_code": "26643006",
"route_ncit_code": "C38288"
```

Two coding systems so you can plug into whichever your downstream
system expects. The system URIs are constants and not repeated on
every entry:

* SNOMED CT: `http://snomed.info/sct`
* NCI Thesaurus: `http://ncithesaurus.nci.nih.gov`

Both code fields populate together. Both are `null` together when
`route` is null or falls outside the common routes we have codes for.

## The evidence trail

`sources[]` lists every place we found the medication. One entry per
mention across all submitted documents.

```json theme={null}
"sources": [
  { "document_name": "h_and_p.pdf", "page": 1, "evidence_text": "Pen-Vee K 250 MG Oral Tablet" },
  { "document_name": "discharge_summary.pdf", "page": 1, "evidence_text": "Penicillin V Potassium 500 MG Oral Tablet" },
  { "document_name": "referral_note.pdf", "page": 1, "evidence_text": "STOPPED: Penicillin V Potassium 250 MG Oral Tablet" }
]
```

A drug mentioned in three documents becomes one medication with three
sources. `evidence_text` is the raw line we found the mention on,
which makes it easy to show clinicians exactly which words drove each
output.

## Order of `medications[]`

Ordered most-current first, then alphabetically by `drug_name`. The
top of the list is what you'd hand a clinician for review.

## What's NOT on the response (yet)

* `status` and `status_conflict` — not surfaced yet; coming in a later release.
* `confidence` — not surfaced yet; coming in a later release.
* Source-vs-derived field provenance — not surfaced yet; coming in a later release.

## A worked example: Bactrim across three documents

H\&P says `"Bactrim 800/160 mg PO BID"`. Discharge says
`"sulfamethoxazole 800 mg / trimethoprim 160 mg oral tablet"`. Referral
says `"sulfamethoxazole/trimethoprim DS"`. All three become one entry:

```json theme={null}
{
  "drug_name": "sulfamethoxazole 800 MG / trimethoprim 160 MG Oral Tablet",
  "rxnorm_code": "198335",
  "rxnorm_tty": "SCD",
  "ingredients": [
    {
      "rxnorm_code": "10180", "name": "Sulfamethoxazole", "rxnorm_tty": "IN",
      "strength_quantity": "800", "strength_unit": "mg"
    },
    {
      "rxnorm_code": "10829", "name": "Trimethoprim", "rxnorm_tty": "IN",
      "strength_quantity": "160", "strength_unit": "mg"
    }
  ],
  "dose_quantity": "1",
  "dose_unit": "tablet",
  "route": "PO",
  "route_snomed_code": "26643006",
  "route_ncit_code": "C38288",
  "dose_form": "oral tablet",
  "frequency": "BID",
  "sources": [
    { "document_name": "h_and_p.pdf", "page": 1, "evidence_text": "Bactrim 800/160 mg PO BID" },
    { "document_name": "discharge_summary.pdf", "page": 1, "evidence_text": "sulfamethoxazole 800 mg / trimethoprim 160 mg oral tablet" },
    { "document_name": "referral_note.pdf", "page": 1, "evidence_text": "sulfamethoxazole/trimethoprim DS" }
  ]
}
```

What you can read off this:

* One entry, not three. Multiple mentions become one medication.
* Specific drug at the top, with both ingredient codes for class-level
  checks.
* Each ingredient carries its own strength.
* Route is coded in both SNOMED CT and NCI Thesaurus.
* The original text from each document is preserved in `sources`.