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

> How to read `status`, `confidence`, and `evidence` — and what to do with them.

This guide covers responses from `POST /v1/medications/infer`. The PDF
endpoint (`POST /v1/med-lists/from-documents`) uses a related but different
response shape — see [Med lists from PDFs](/from-documents#response-shape) for
its specific fields.

Every inferred medication from `/v1/medications/infer` comes back with three
fields you need to understand before acting on the data: **status**,
**confidence**, and (when `verbosity="full"`) an **evidence** trail.

## `status` — what we think the medication's state is

Status mirrors FHIR's `MedicationRequest.status` vocabulary:

| Status      | Meaning                                                            |
| ----------- | ------------------------------------------------------------------ |
| `active`    | Patient is currently taking this medication                        |
| `completed` | Course finished (end date in past, or explicit `completed` status) |
| `stopped`   | Explicitly stopped by a clinician                                  |
| `cancelled` | Order was cancelled before dispensing                              |
| `unknown`   | Not enough evidence to classify, or all data is too stale          |

See the [full triggers table](/resources/status-values) for the rules that
produce each status.

## `confidence` — how sure we are of the status

A float from `0.0` to `1.0`. **This is confidence in the status assignment, not
probability the patient is taking the drug.** It reflects data quality:

* **Multiple corroborating signals** raise it (e.g., an active order plus a recent dispense for the same drug)
* **Missing dates** lower it
* **Missing RxNorm codes** lower it
* **Staleness** is penalized — older signals carry less weight than recent ones

<Tip>
  Use `status AND confidence >= threshold` together. A common pattern: show
  confidently-active meds prominently (confidence ≥ 0.80), show low-confidence
  meds in a secondary list with a "verify with patient" label.
</Tip>

## `evidence` — which rules fired (full verbosity only)

When you request `verbosity="full"`, each medication's `provenance` entry
includes the list of rules that contributed to the status. Examples:

| Evidence tag           | What it means                                                      |
| ---------------------- | ------------------------------------------------------------------ |
| `recent_dispense`      | A dispense was recorded recently                                   |
| `active_order`         | A `MedicationRequest` is `status=active` and was authored recently |
| `self_reported_active` | Patient-reported `MedicationStatement` with `reported=true`        |
| `course_completed`     | Explicit `completed` status or `effectivePeriod.end` in the past   |
| `prescription_expired` | An old order with no recent fill activity to corroborate it        |
| `order_stopped`        | `MedicationRequest` has `status=stopped`                           |
| `order_cancelled`      | `MedicationRequest` has `status=cancelled`                         |
| `stale_data`           | All input data is too old to support a confident classification    |
| `insufficient_signal`  | No classifying rule fired (paired with `unknown` status)           |

The evidence list is the audit trail. If a clinician or user asks "why is this
marked active?", the answer is in `provenance[med_id].evidence`.

## A worked example

Request:

```json theme={null}
{
  "verbosity": "full",
  "resources": [
    {
      "resourceType": "MedicationRequest",
      "id": "mr-1",
      "status": "active",
      "intent": "order",
      "authoredOn": "2026-03-05",
      "medicationCodeableConcept": { "coding": [{ "system": "http://www.nlm.nih.gov/research/umls/rxnorm", "code": "617312" }] }
    },
    {
      "resourceType": "MedicationDispense",
      "id": "md-1",
      "status": "completed",
      "whenHandedOver": "2026-04-09",
      "medicationCodeableConcept": { "coding": [{ "system": "http://www.nlm.nih.gov/research/umls/rxnorm", "code": "617312" }] }
    }
  ]
}
```

Response (trimmed):

```json theme={null}
{
  "medications": [
    {
      "id": "med_abc123",
      "display_name": "Atorvastatin 40 MG Oral Tablet",
      "status": "active",
      "confidence": 0.95,
      ...
    }
  ],
  "provenance": {
    "med_abc123": {
      "sources": ["MedicationRequest/mr-1", "MedicationDispense/md-1"],
      "evidence": ["active_order", "recent_dispense"],
      "enrichments": []
    }
  }
}
```

Two separate FHIR resources were deduplicated to one medication via RxNorm
grouping. Two rules fired: `active_order` (the order is recent and active) and
`recent_dispense` (a recent fill). The corroborating signals drive confidence
high.

## Acting on low-confidence results

Low confidence (\< 0.7) usually means:

* Only one signal fired (no corroboration)
* The data is old
* Key fields were missing (dates, RxNorm codes)

<Warning>
  Don't ignore low-confidence medications — they're often the most interesting
  cases for clinical review. Surface them in a "needs verification" bucket
  rather than hiding them.
</Warning>