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

# Medication Orders

> Learn how the Medical Orders API and Suki Medical Orders Service turn clinician conversations into structured, EHR-ready medication orders

<div className="quick-summary-wrapper">
  <div className="quick-summary-header">
    <span className="quick-summary-icon" aria-hidden="true" />

    <span className="quick-summary-title">Quick summary</span>
  </div>

  <div className="quick-summary-content">
    The Medical Orders API uses the Suki Medical Orders Service to identify and suggest clinical orders from doctor-patient conversations. Verbal instructions become structured, EHR-compatible artifacts (for example RxCUI codes) so you can streamline workflows and reduce manual work.
  </div>

  <div className="quick-summary-footer">
    <span className="quick-summary-footer-icon" aria-hidden="true" />

    <span className="quick-summary-footer-text">Last updated:</span>
    <span className="quick-summary-footer-date">June 2026</span>
  </div>
</div>

<Info>
  **Medication orders are supported by:** APIs, Mobile SDK, Web SDK
</Info>

<Warning>
  This feature is not enabled by default. To enable it, contact Suki to request access (if not already enabled).
</Warning>

<Note>
  * **REST APIs:** Send encounter configuration, context, and retrieve structured order payloads through our ambient APIs (including the [Context API](/api-reference/ambient-sessions/context) and structured data endpoints mentioned below).
  * **Mobile SDK (iOS):** Pass optional medication context on <Tooltip tip="A single, time-bound instance of an ambient recording for a specific patient encounter that captures clinical conversations." cta="View in Glossary" href="/Glossary/a">ambient sessions</Tooltip>
    after you create a session. Refer to [Orders info](/mobile-sdk/ambient-guides/provide-clinical-context#orders-info) section in provide clinical context for more information.
  * **Web SDK:** Use the [Medication orders integration](/web-sdk/medication-orders/overview) guide to configure and generate medication orders in the Headed Web SDK.
</Note>

**Medication orders** uses the Suki Medical Orders Service to identify and suggest clinical orders from doctor-patient conversations. Those instructions are translated into structured, EHR-compatible artifacts so you can streamline workflows and reduce manual effort.

During a <Tooltip tip="A single interaction between a patient and healthcare provider, typically corresponding to one visit or appointment." cta="View in Glossary" href="/Glossary/e">clinical encounter</Tooltip>, Suki surfaces medication recommendations. The service converts them into structured payloads
(for example [RxCUI codes](https://www.nlm.nih.gov/research/umls/rxnorm/overview.html)) for accuracy and reliability downstream.

Use medication orders when you need to:

* **Align with your EHR:** Apply validation that matches how your EHR expects orders to look before submission.
* **Keep clinical context tight:** Tie every order to a diagnosis through problem-based context (PBC).
* **Track orders across sessions:** Reconcile new, continued, or discontinued therapy when the same <Tooltip tip="A single interaction between a patient and healthcare provider, typically corresponding to one visit or appointment." cta="View in Glossary" href="/Glossary/e">encounter</Tooltip> spans more than one <Tooltip tip="A single, time-bound instance of an ambient recording for a specific patient encounter that captures clinical conversations." cta="View in Glossary" href="/Glossary/a">ambient session</Tooltip>.
* **Integrate flexibly:** Pull full <Tooltip tip="Organized medical information extracted from clinical conversations, formatted for integration with EHR systems." cta="View in Glossary" href="/Glossary/s">structured data</Tooltip> or focus on medication orders only.

## Key features

<CardGroup cols={2}>
  <Card title="EHR-centric validation" icon="shield-check">
    Apply strict validation logic for your configured EHR so orders stay submittable under that system's rules.
  </Card>

  <Card title="Problem-based context (PBC)" icon="link">
    Every order links to a mandatory diagnosis so fidelity stays high and each order traces to a problem in the session.
  </Card>

  <Card title="Cumulative session reconciliation" icon="rotate">
    Re-ambient logic reconciles orders across multiple sessions in one encounter, using active medications, prior session data, and the current transcript.
  </Card>

  <Card title="Flexible retrieval" icon="download">
    Pull all structured data at once, or target medication orders only when that fits your app.
  </Card>
</CardGroup>

## Technical requirements

For an order to be valid and submittable, the following fields must be present:

* **Drug name**
* **Medication code (RxCUI)** that matches the acceptable list for your configured EHR
* **Linked diagnosis** that references an existing, valid problem in the session

<Note>
  If mandatory fields are missing, the API returns the order in the `partial_medication_orders` list. If a suitable diagnosis cannot be identified, the order is marked **`INCOMPLETE_DX`**.
</Note>

## Integration workflow for Ambient APIs

```mermaid actions={false} theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
flowchart TD
    A[Configure encounter] --> B[Ingest context<br/>via API call]
    B --> C[Cumulative reconciliation<br/>NEW, <br/>DISCONTINUE, <br/>REFILL]
    C --> D[Retrieve structured<br/>data via API call]

    style A fill:#FFF394,stroke:#333,color:#000
    style B fill:#FFF394,stroke:#333,color:#000
    style C fill:#FFF394,stroke:#333,color:#000
    style D fill:#FFF394,stroke:#333,color:#000
```

<Steps>
  <Step title="Configure the encounter" icon="gear">
    Set EHR context at the encounter level so validation applies for the whole session.

    * **Field:** `submittable_ehr`
    * **Type:** enum (for example `athena`, `epic`, `cerner`)
  </Step>

  <Step title="Ingest context" icon="database">
    Use the <Badge color="blue" size="sm">POST</Badge> [Context API](/api-reference/ambient-sessions/context) to send the patient's active medication list and any orders from prior sessions. For high-fidelity generation, explicitly separate **`encounter_context`** from **`previous_session_orders`** so the service can tell current encounter data from earlier session data.

    While sending the medication orders to the context API, set **`status`** on each medication order to **`ACTIVE`**, **`DISCONTINUED`**, or **`REFILLED`**.

    | Status value   | Meaning                       |
    | :------------- | :---------------------------- |
    | `ACTIVE`       | Active medication order       |
    | `DISCONTINUED` | Discontinued medication order |
    | `REFILLED`     | Refill medication order       |
  </Step>

  <Step title="Run cumulative reconciliation (&#x22;Diff&#x22; logic)" icon="rotate">
    The Medical Orders Service applies re-ambient reconciliation using:

    * Active medications shared from the EHR
    * Orders generated from previous sessions
    * The current session transcript

    The API returns an updated cumulative list. Medications can be labeled **NEW**, **DISCONTINUE**, or **REFILL**.
  </Step>

  <Step title="Retrieve structured data" icon="code">
    Call the structured data endpoints to read generated orders. Use the paths in [Retrieve structured orders](#retrieve-structured-orders). For the full structured payload (not only orders), see [Get structured data](/api-reference/ambient-content/structured-data) and [Get encounter structured data](/api-reference/ambient-content/encounter-structured-data).

    **Example medication order payload**

    ```json JSON theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
    {
      "drug_name": "Lisinopril",
      "medication_code": {
        "type": "RXCUI",
        "code": "314076"
      },
      "dosage": {
        "raw_value": "1 tablet",
        "quantity": 1,
        "unit": "TAB"
      },
      "frequency": {
        "raw_value": "Once daily",
        "structured_value": "ONE_A_DAY"
      },
      "instructions": "Take one tablet by mouth once daily",
      "medication_timing": {
        "raw_value": "In the morning",
        "structured_value": "IN_THE_MORNING"
      },
      "strength": {
        "raw_value": "10mg"
      },
      "format": {
        "raw_value": "Tablet"
      },
      "route": {
        "raw_value": "By mouth"
      },
      "linked_diagnosis_codes": [
        {
          "type": "ICD10",
          "code": "I10"
        }
      ],
      "number_of_refills": 3,
      "start_date": "2024-01-15T00:00:00Z",
      "end_date": "2024-04-15T00:00:00Z",
      "duration_in_days": 90,
      "status": "REFILLED",
      "metadata": {
        "origin": "EMR",
        "encounter_relation": "CURRENT_ENCOUNTER"
      }
    }
    ```
  </Step>
</Steps>

<Note>
  **REST alignment:** On the [Context API](/api-reference/ambient-sessions/context), set **`emr.target_emr`** to **`ATHENA`**, **`EPIC`**, or **`CERNER`** so medication validation lines up with the same EHR you target at encounter configuration (see Step 1 above). That guide also lists required fields when you send **`orders.medication_orders.values`** on the same request.
</Note>

## Retrieve structured orders

Use the following endpoints to retrieve structured orders:

<CardGroup cols={2}>
  <Card title="Session-Scoped Medication Orders" icon="code" href="/api-reference/ambient-content/structured-data" arrow={true}>
    Retrieve structured orders for a session
  </Card>

  <Card title="Encounter-Scoped Medication Orders" icon="code" href="/api-reference/ambient-content/encounter-structured-data" arrow={true}>
    Retrieve structured orders for an encounter
  </Card>
</CardGroup>

## Global filtering rules

The Medication Orders API applies these filters by default:

* **Intent filtering:** Orders where `intent_flag` is **FALSE** are dropped (for example when a patient asks about a drug but the clinician does not prescribe it).
* **Referential integrity:** Generated orders only link to problems that appear in the current artifacts. They never reference missing data.
* **Empty values:** The Medication Orders API does not return string placeholders such as `NA` or empty strings for optional fields that were not verbalized.