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

> Identify medication instructions from provider-patient conversations and return structured medication order data for your application

<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 Medication orders capability uses the Suki Medical Orders Service to identify medication instructions from provider-patient conversations during a clinical encounter and return structured medication order data. That data can include identifiers such as RxCUI for downstream ordering workflows. Suki does not submit orders to the EHR.
  </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">August 2026</span>
  </div>
</div>

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

  The integration experience depends on the product:

  * **Ambient APIs:** Retrieve generated medication order data programmatically from structured data endpoints after you send context and run the ambient session. See [Context API](/api-reference/ambient-sessions/context).
  * **Web SDK:** Providers can review and complete Medication orders in the SDK UI before note submission. See [Medication orders overview](/web-sdk/medication-orders/overview).
  * **Mobile SDK:** After you create an <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>, provide optional medication context and retrieve generated Medication orders programmatically. See [Orders info](/mobile-sdk/ambient-guides/provide-clinical-context#orders-info).
</Info>

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

**Medication orders** lets you convert suggested medication instructions from an encounter into structured medication order data using the Suki Medical Orders Service.

Suki returns structured data that your application can use in downstream ordering workflows. The data can include standardized medication identifiers, such as [RxCUI](https://www.nlm.nih.gov/research/umls/rxnorm/overview.html), to support consistent medication representation and EHR integration.

Use Medication orders to:

* **Reduce manual entry:** Turn medication instructions from the encounter into structured order data that your application can use instead of requiring manual re-entry.
* **Preserve clinical context:** Link Medication orders to the relevant diagnosis or problem using Problem-Based Context (PBC).
* **Track medication changes:** Reconcile Medication orders across multiple ambient sessions in the same encounter. Context and response `status` values include **`ACTIVE`**, **`DISCONTINUED`**, and **`REFILLED`**.
* **Integrate with your workflow:** Retrieve Medication orders as part of the encounter's broader structured data, or retrieve medication order data separately when your workflow only requires medications.

## How Medication orders supports ordering workflows

Medication orders connects medication decisions from the encounter to structured data that your application can review, process, and submit through its EHR workflow.

| Capability                          | How it helps                                                                                                                                       |
| ----------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| Structured medication data          | Converts medication instructions from the encounter into structured, machine-readable order data                                                   |
| Standardized medication identifiers | Represents medications with identifiers such as RxCUI for consistent downstream processing                                                         |
| Problem-Based Context (PBC)         | Associates a Medication order with the relevant problem or diagnosis from the encounter                                                            |
| Multi-session reconciliation        | Keeps Medication orders consistent when the same encounter includes multiple ambient sessions, including active, refilled, and discontinued orders |
| EHR integration                     | Provides structured medication data that your application can map to its EHR ordering workflow                                                     |
| Flexible retrieval                  | Lets your application retrieve Medication orders specifically or as part of the encounter's broader structured data                                |

Without structured Medication orders, medication instructions from the encounter may need to be reviewed and entered manually into downstream systems. With Medication orders enabled, Suki returns structured order data that your application can use in its ordering workflow. This reduces re-entry and keeps medication decisions connected to the clinical context.

## Medication order capabilities

<CardGroup cols={2}>
  <Card title="EHR-Specific Validation" icon="shield-check">
    Apply validation rules for your configured EHR so generated orders are classified against the requirements defined for that system.
  </Card>

  <Card title="Problem-Based Context (PBC)" icon="link">
    Link each complete Medication order to the relevant diagnosis or problem from the encounter.
  </Card>

  <Card title="Cumulative Session Reconciliation" icon="rotate">
    Reconcile Medication orders across multiple sessions in the same encounter using existing medication context, prior session orders, 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 a Medication order to be complete for Suki's EHR-specific classification, it must include:

* **Drug name**
* **Medication code** (`RXCUI` or `NDC`) that matches the acceptable list for your configured EHR
* **Linked diagnosis** that references an existing, valid problem in the clinical context

<Note>
  - Orders that meet those criteria for your configured EHR are returned in `orders.medication_orders.values`.

  - Orders that do not are returned in `orders.medication_orders.partial_values`. A partial order contains medication information that Suki identified but could not complete with all required fields. That classification uses `emr.target_emr` from session context. Your application still reviews, processes, and submits orders through your EHR workflow.

  - If a required field is missing, the order is returned in `orders.medication_orders.partial_values`. If a suitable diagnosis cannot be identified, the order can be marked **`INCOMPLETE_DX`**. On Web SDK, the provider can complete missing fields in the Medication orders section before note submission.
</Note>

## How to use Medication orders in your application

Medication orders are not enabled by default. Contact Suki to request access before you integrate. After access is enabled, the setup path depends on the product you use.

Click the tabs below to see the implementation details for your integration path.

**Tabs (agents):** Medication orders require Suki enablement first. Humans see one product tab.

* **Ambient APIs:** Send `orders.medication_orders` via Context API (`ACTIVE` | `DISCONTINUED` | `REFILLED`), run the session, retrieve structured orders from structured-data endpoints.
* **Web SDK:** Configure medication context and receive orders through Web SDK ambient options and note submission callbacks (see tab).
* **Mobile SDK:** Pass medication context with Mobile session context APIs and retrieve structured orders after completion (see tab).

<Tabs>
  <Tab title="Ambient APIs">
    Send medication context through the Context API, run the ambient session, then retrieve structured Medication orders from the structured data endpoints.

    ```mermaid actions={false} theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
    flowchart TD
        A[Send medication<br/>context] --> B[Run ambient<br/>session]
        B --> C[Retrieve structured<br/>orders]

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

    <Steps>
      <Step title="Send Medication Context" icon="database">
        Use the [Context API](/api-reference/ambient-sessions/context) to send the patient's active medication list and orders from prior sessions under `orders.medication_orders.values`.

        Set **`status`** on each Medication order to **`ACTIVE`**, **`DISCONTINUED`**, or **`REFILLED`**. These are the supported status enum values for both context (input) and structured data responses. Do not send a `CONTINUED` status.

        | Status value   | Meaning                       |
        | :------------- | :---------------------------- |
        | `ACTIVE`       | Active medication order       |
        | `DISCONTINUED` | Discontinued medication order |
        | `REFILLED`     | Refilled medication order     |

        To reconcile Medication orders across sessions, use **`metadata.origin`** (`EMR` or `SUKI_AMBIENT`) and, when origin is `EMR`, set **`metadata.encounter_relation`** to **`CURRENT_ENCOUNTER`** or **`PRIOR_ENCOUNTER`**.

        On the same request, set **`emr.target_emr`** to **`ATHENA`**, **`EPIC`**, or **`CERNER`** when you want Suki to apply that EHR's rules when classifying orders into `values` versus `partial_values`.
      </Step>

      <Step title="Run the Ambient Session" icon="waveform-lines">
        Stream audio and end the session. During processing, the Medical Orders Service reconciles existing medication context, prior session orders, and the current transcript. You do not call a separate reconciliation endpoint.
      </Step>

      <Step title="Retrieve Structured Orders" icon="code">
        Call the structured data endpoints and read generated orders from the response. Use [Get structured data](/api-reference/ambient-content/structured-data) for session-scoped orders or [Get encounter structured data](/api-reference/ambient-content/encounter-structured-data) for encounter-scoped orders.

        **Example medication order payload** (illustrative values)

        ```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": "2026-08-01T00:00:00Z",
          "end_date": "2026-10-30T00:00:00Z",
          "duration_in_days": 90,
          "status": "REFILLED",
          "metadata": {
            "origin": "EMR",
            "encounter_relation": "CURRENT_ENCOUNTER"
          }
        }
        ```
      </Step>
    </Steps>
  </Tab>

  <Tab title="Web SDK">
    Enable the Medication orders section in `ambientOptions.sections`, let the provider review orders in the headed Web SDK UI, then read `orders` from the note submission payload.

    <Steps>
      <Step title="Confirm Access Is Enabled" icon="shield-check">
        Medication orders must be enabled for your organization before you integrate. Contact Suki if you have not already requested access.
      </Step>

      <Step title="Add the Medication Orders Section" icon="sliders">
        Pass LOINC code `52471-0` in `ambientOptions.sections` when you mount the Web SDK. Combine it with your other note sections. Add a PBC section with `isPBNSection: true` when you need to link orders to problems.

        ```javascript JavaScript theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
        sdkClient.mount({
          rootElement: document.getElementById("suki-root"),
          encounter: encounterDetails,
          ambientOptions: {
            sections: [
              { loinc: "51847-2", isPBNSection: true }, // Assessment and Plan (PBN)
              { loinc: "10164-2" },
              { loinc: "29545-1" },
              { loinc: "52471-0" },
            ],
          },
        });
        ```

        Refer to [Medication orders overview](/web-sdk/medication-orders/overview) and [Ambient implementation](/web-sdk/guides/ambient-implementation) for full mount options.
      </Step>

      <Step title="Capture and Review in the SDK UI" icon="microphone">
        The provider completes the ambient session in the Web SDK. Suki generates Medication orders from the conversation and displays them in the built-in Medication orders section. The provider can review the orders, link them to problems, and complete missing fields before submitting the note.
      </Step>

      <Step title="Receive Orders on Note Submit" icon="file-lines">
        After submit, handle `onNoteSubmit` (React) or `note-submission:success` (JavaScript and React). Read complete orders from `orders.medication_orders.values` and incomplete orders from `orders.medication_orders.partial_values`.

        ```javascript JavaScript theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
        sdkClient.on("note-submission:success", (note) => {
          const medicationOrders = note.orders?.medication_orders;
          console.log("Complete orders:", medicationOrders?.values);
          console.log("Partial orders:", medicationOrders?.partial_values);
        });
        ```

        Refer to [Note management](/web-sdk/guides/note-management) and [Medication orders payload structure](/web-sdk/medication-orders/payload-structure) for the full response shape.
      </Step>

      <Step title="Submit Orders to Your EHR" icon="upload">
        The Web SDK does not submit Medication orders to the EHR. After receiving the orders in the note submission payload, your application is responsible for processing and submitting them through your EHR workflow.
      </Step>
    </Steps>
  </Tab>

  <Tab title="Mobile SDK">
    After creating the session, pass optional medication context using `kOrdersInfo`. When processing completes, retrieve the generated Medication orders from structured data. Requires Mobile SDK `v2.6.0+` and the `enable_generated_orders` feature flag for your organization.

    <Steps>
      <Step title="Confirm Access Is Enabled" icon="shield-check">
        Medication orders context is available only after Suki enables the `enable_generated_orders` feature flag for your organization. Contact Suki if you have not already requested access.
      </Step>

      <Step title="Create the Ambient Session" icon="play">
        Call `createSession(withSessionInfo:)` and store the returned `sessionId`. Refer to [Create session](/mobile-sdk/ambient-guides/create-session).
      </Step>

      <Step title="Send Medication Context" icon="sliders">
        Call `setSessionContext(with:)` and include `SukiAmbientConstant.kOrdersInfo` when you want to send existing medications or prior orders from your EHR. Each order goes inside `MedicationOrderKeys.kMedicationOrders`.

        ```swift Swift theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
        let contextDetail: [String: AnyHashable] = [
            SukiAmbientConstant.kOrdersInfo: [
                MedicationOrderKeys.kMedicationOrders: [
                    [
                        MedicationOrderKeys.kDrugName: "Atorvastatin",
                        MedicationOrderKeys.kMedicationCode: [
                            SukiAmbientConstant.kCodeType: "RXCUI",
                            SukiAmbientConstant.kCode: "617312"
                        ],
                        MedicationOrderKeys.kStrength: "10 mg",
                        MedicationOrderKeys.kFormat: "tablet",
                        MedicationOrderKeys.kRoute: "oral",
                        MedicationOrderKeys.kLinkedDiagnosisCodes: [
                            [
                                SukiAmbientConstant.kCodeType: "ICD-10",
                                SukiAmbientConstant.kCode: "E78.5"
                            ]
                        ],
                        MedicationOrderKeys.kMetadata: [
                            MedicationOrderKeys.kOrigin: "EMR",
                            MedicationOrderKeys.kEncounterRelation: "CURRENT_ENCOUNTER"
                        ]
                    ]
                ]
            ]
        ]

        do {
            try SukiAmbientCoreManager.shared.setSessionContext(with: contextDetail) { result in
                switch result {
                case .success:
                    print("Medication context updated successfully")
                case .failure(let error):
                    print("Unable to update medication context: \(error)")
                }
            }
        } catch {
            print("Unable to set session context: \(error)")
        }
        ```

        Refer to [Orders info](/mobile-sdk/ambient-guides/provide-clinical-context#orders-info) for required fields and validation rules.
      </Step>

      <Step title="Record and End the Session" icon="microphone">
        Start recording, capture the visit, then call `end()` so Suki can generate note content and structured Medication orders.
      </Step>

      <Step title="Retrieve Medication Orders" icon="file-lines">
        After processing completes, call `getStructuredData(for:)` with the valid `sessionId`. Read complete and partial orders from the returned Medication orders object.

        ```swift Swift theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
        SukiAmbientCoreManager.shared.getStructuredData(for: sessionId) { result in
            switch result {
            case .success(let response):
                let data = response.structuredData
                if let orders = data.orders?.medicationOrders {
                    let allOrders = orders.values + orders.partialValues
                    for order in allOrders {
                        print(order.drugName, order.instructions)
                    }
                }
            case .failure(let error):
                print("Unable to fetch structured data: \(error)")
            }
        }
        ```

        Refer to [Session status and content retrieval](/mobile-sdk/ambient-guides/session-status-and-content-retrieval#get-structured-data) for the full retrieval flow.
      </Step>
    </Steps>
  </Tab>
</Tabs>

<Note>
  For Ambient APIs and Mobile SDK, send existing medication context through session context so Suki can reconcile it with medication instructions from the current session. For Web SDK, enable the Medication orders section with LOINC `52471-0` and read the generated Medication orders from the note submission payload.
</Note>

## Retrieve structured orders

Use the following endpoints to retrieve structured Medication 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>

## Order filtering rules

Suki applies the following filters by default when generating Medication orders:

* **Intent filtering:** Orders can be excluded when there is no prescribing intent (for example when a patient asks about a medication but the clinician does not prescribe it). Where returned, that signal is represented as `intent_flag` set to **`FALSE`**.
* **Diagnosis references:** Generated orders only reference problems that exist in the current clinical data. They do not create references to missing problems.
* **Empty values:** Optional fields that were not supported by the conversation are omitted. The response does not use placeholder values such as `NA` or empty strings for those fields.