> ## 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">July 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="One patient visit or appointment with a healthcare provider. In Suki, an encounter can group one or more ambient sessions so related recordings and notes stay tied to the same clinical visit." 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="One patient visit or appointment with a healthcare provider. In Suki, an encounter can group one or more ambient sessions so related recordings and notes stay tied to the same clinical visit." 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.

## How Medication orders improves clinical documentation

Medication orders turn spoken medication plans into structured artifacts that sit alongside the clinical note, so documentation and ordering stay connected.

| What you configure                          | How documentation gets better                                                  |
| ------------------------------------------- | ------------------------------------------------------------------------------ |
| Medication orders enabled for the encounter | Verbal medication instructions become structured, reviewable order suggestions |
| Diagnosis-linked orders (PBC context)       | Each order traces to a problem in the visit instead of floating free-text      |
| EHR validation rules                        | Orders are shaped for what your EHR can accept before submission               |
| Multi-session reconciliation                | New, continued, or discontinued therapy stays consistent across the encounter  |

Without structured medication orders, clinicians often re-enter medication details manually after reviewing the note. With this capability, the conversation produces EHR-ready order payloads, which reduces rework and keeps the plan of care aligned with the documentation.

## Medication order capabilities

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

## 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>
  <Tab title="Ambient APIs">
    Send medication context through the Context API, run the ambient session, then retrieve structured orders from the structured data endpoints.

    ```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="Send Medication Context" icon="database">
        Use the [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, separate **`encounter_context`** from **`previous_session_orders`**.

        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       |

        On the same request, set **`emr.target_emr`** to **`ATHENA`**, **`EPIC`**, or **`CERNER`** so medication validation matches your configured EHR.
      </Step>

      <Step title="Run the Ambient Session" icon="waveform-lines">
        Stream audio and end the session. The Medical Orders Service reconciles active medications, prior session orders, and the current transcript.
      </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**

        ```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>
  </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: "51848-0", isPBNSection: true },
              { 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 shows them in the built-in Medication orders section. The provider can review orders, link them to problems, and complete missing fields inline before submit.
      </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 orders to the EHR. Your application validates the returned payload and persists orders the same way you handle note `contents`.
      </Step>
    </Steps>
  </Tab>

  <Tab title="Mobile SDK">
    Pass optional medication context with `kOrdersInfo` after you create the session, then retrieve generated orders from structured data when processing completes. 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>
  On Ambient APIs and Mobile SDK, send existing medication context through session context so Suki can reconcile against generated output. On Web SDK, enable the Medication orders section with LOINC `52471-0` and read `orders` from the note submission payload.
</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.