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

> Learn how Web SDK Medication orders align with Ambient API structured data for shared ingestion and EHR mapping

<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">
    Web SDK Medication orders and Ambient API structured data use the same Medication order object shape. If you use both workflows, you can reuse parsers, validators, and EHR mapping logic for complete and incomplete Medication orders.
  </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>

The Headed Web SDK returns Medication orders when a provider submits a note. Ambient APIs return Medication orders through structured data responses. Both workflows use the same Medication order object shape, which helps you reuse ingestion, validation, and EHR mapping logic across Web SDK and API workflows.

This guide describes where Medication orders appear in each payload, how to use a shared ingestion pattern, which responsibilities belong to each workflow, and where to find related metadata references.

<Note>
  For the full payload structure of Medication orders in the Web SDK, refer to [Medication orders payload structure](/web-sdk/medication-orders/payload-structure).
</Note>

<Tip>
  This guide explains how the Web SDK and Ambient APIs return Medication orders. If your workflow uses both, contact Suki so we can help confirm the right setup for your integration.
</Tip>

## Payload alignment

The Web SDK and Ambient API place Medication orders in different parts of the response. The fields inside each Medication order are the same, so you can parse the order details the same way.

<CardGroup cols={2}>
  <Card title="Web SDK Note Submission Payload" icon="globe">
    Read complete orders from **`orders.medication_orders.values`** and incomplete orders from **`orders.medication_orders.partial_values`**.
  </Card>

  <Card title="Ambient API Structured Data" icon="code">
    Read complete orders from **`structured_data.orders.medication_orders.values`** and incomplete orders from **`structured_data.orders.medication_orders.partial_values`**.
  </Card>
</CardGroup>

You can retrieve Ambient API structured data from these endpoints:

<CardGroup cols={2}>
  <Card title="Get Ambient Session Structured Data" icon="code" href="/api-reference/ambient-content/structured-data" arrow={true}>
    Retrieve structured data for an ambient session.
  </Card>

  <Card title="Get Encounter Structured Data" icon="code" href="/api-reference/ambient-content/encounter-structured-data" arrow={true}>
    Retrieve structured data for an encounter.
  </Card>
</CardGroup>

## Shared ingestion pattern

If your application receives Medication orders from both the Headed Web SDK and Ambient APIs, you do not need two separate parsers for the order details. Read the order arrays from the correct response path, then pass each order object into the same parser, validator, or EHR mapping logic.

```mermaid actions={false} theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
flowchart LR
    A[Web SDK note submission] --> C[Shared medication order parser]
    B[Ambient API structured data] --> C
    C --> D[Your EHR or downstream system]

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

We recommend using the following approach for parsing Medication orders:

<Steps>
  <Step title="Read Orders from the Response">
    Use the Web SDK or Ambient API response path to read complete orders from **`values`** and incomplete orders from **`partial_values`**.
  </Step>

  <Step title="Parse Each Order the Same Way">
    After you read the order arrays, parse each order object using the same Medication order field definitions, such as `drug_name`, `medication_code`, `dosage`, and `linked_diagnosis_codes`.
  </Step>

  <Step title="Handle Complete and Incomplete Orders Separately">
    Send orders from **`values`** through your completed order workflow. Send orders from **`partial_values`** to manual review or additional handling.
  </Step>

  <Step title="Validate Metadata">
    Use [Orders Info API](/api-reference/info/orders) and related info endpoints to validate enums, such as status, frequency, and origin.
  </Step>
</Steps>

## Web SDK and Ambient API responsibilities

The Web SDK and Ambient APIs return aligned Medication order data, but each workflow has a different responsibility in your integration.

| Topic                           | Web SDK                                                                                              | Ambient API                                                                                                                                                           |
| :------------------------------ | :--------------------------------------------------------------------------------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Order generation trigger**    | LOINC **`52471-0`** in `ambientOptions.sections` and the **`enable_medication_orders`** feature flag | Session context, structured data retrieval, and API configuration documented in [Medication orders](/documentation/concepts/ambient-clinical-notes/medication-orders) |
| **Provider review**             | Built-in **Medication orders** section in the note UI                                                | Your application UI                                                                                                                                                   |
| **Payload delivery**            | `note-submission:success` / `onNoteSubmit`                                                           | GET structured data endpoints                                                                                                                                         |
| **EHR submission**              | Partner application                                                                                  | Partner application                                                                                                                                                   |
| **Existing medication context** | The Web SDK focuses on generating and returning orders from the ambient session                      | Send existing medication orders through the [Context API](/api-reference/ambient-sessions/context)                                                                    |

## Context ingest on the API

When you use the Ambient API, you can send existing medication orders through the [Context API](/api-reference/ambient-sessions/context). Suki uses that context to reconcile and deduplicate against generated output.

The Web SDK does not replace the Context API. In the Web SDK flow, Medication orders are generated from the ambient session and returned in the note submission payload.

<Note>
  **Important**

  If your integration uses both Web SDK and Ambient API workflows for the same encounter, keep the encounter identifiers and Web SDK LOINC configuration consistent.
</Note>

## Metadata and validation

Use the same metadata references when you validate or map Medication order fields:

<CardGroup cols={2}>
  <Card title="Orders Metadata API" icon="prescription" href="/api-reference/info/orders" arrow={true}>
    Reference coding systems, units, frequencies, and other order metadata.
  </Card>

  <Card title="Medication Orders API Guide" icon="book" href="/documentation/concepts/ambient-clinical-notes/medication-orders" arrow={true}>
    Review platform-level details for EHR validation, PBC linking, and API reconciliation.
  </Card>
</CardGroup>

## FAQs

<Accordion title="What Is the Difference Between the Web SDK and Ambient API Medication Orders?">
  Both the Web SDK and ambient REST APIs return Medication orders in the same object shape. The main difference is how the orders are generated and returned.

  * The Web SDK generates orders from the ambient session and returns them in the note submission payload.
  * The ambient REST APIs retrieve existing orders from the EHR and return them in the structured data response.
</Accordion>

<Accordion title="How Do I Validate Medication Orders Using REST APIs?">
  Use the [Orders Info API](/api-reference/info/orders) and related info endpoints to validate enums, such as status, frequency, and origin.
</Accordion>

<Accordion title="In Web SDK, How Do I Enable Medication Orders?">
  Pass the LOINC code **`52471-0`** in `ambientOptions.sections` and the **`enable_generated_orders`** preference to enable Medication orders in the Web SDK.
</Accordion>

## Best practices

<Tip>
  * Check for `orders` before you parse it. The object is returned only when Medication orders are enabled.
  * Treat `values` as ready for EHR workflows. Send `partial_values` for manual review or completion.
  * Store `noteId` and `encounterId` with each order batch for tracking and reconciliation.
  * Validate required fields before you submit orders to the EHR.
</Tip>

## Next steps

<Icon icon="file-lines" iconType="solid" /> Refer to [Medication orders overview](/web-sdk/medication-orders/overview) to enable Medication orders in your Web SDK integration.

<Icon icon="file-lines" iconType="solid" /> Refer to [Medication orders payload structure](/web-sdk/medication-orders/payload-structure) for the full field list.

<Icon icon="file-lines" iconType="solid" /> Refer to [Get ambient session structured data](/api-reference/ambient-content/structured-data) to retrieve structured data for a session.

<Icon icon="file-lines" iconType="solid" /> Refer to [Get encounter structured data](/api-reference/ambient-content/encounter-structured-data) to retrieve structured data for an encounter.