Skip to main content
Quick summary
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.
Last updated:June 2026
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.
For the full payload structure of Medication orders in the Web SDK, refer to Medication orders payload structure.
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.

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

Web SDK Note Submission Payload

Read complete orders from orders.medication_orders.values and incomplete orders from orders.medication_orders.partial_values.

Ambient API Structured Data

Read complete orders from structured_data.orders.medication_orders.values and incomplete orders from structured_data.orders.medication_orders.partial_values.
You can retrieve Ambient API structured data from these endpoints:

Get Ambient Session Structured Data

Retrieve structured data for an ambient session.

Get Encounter Structured Data

Retrieve structured data for an encounter.

​
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. We recommend using the following approach for parsing Medication orders:
1

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

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

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

Validate metadata

Use Orders Info API and related info endpoints to validate enums, such as status, frequency, and origin.

​
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.
TopicWeb SDKAmbient API
Order generation triggerLOINC 52471-0 in ambientOptions.sections and the enable_medication_orders feature flagSession context, structured data retrieval, and API configuration documented in Medication orders
Provider reviewBuilt-in Medication orders section in the note UIYour application UI
Payload deliverynote-submission:success / onNoteSubmitGET structured data endpoints
EHR submissionPartner applicationPartner application
Existing medication contextThe Web SDK focuses on generating and returning orders from the ambient sessionSend existing medication orders through the Context API

​
Context ingest on the API

When you use the Ambient API, you can send existing medication orders through the Context API. 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.
ImportantIf your integration uses both Web SDK and Ambient API workflows for the same encounter, keep the encounter identifiers and Web SDK LOINC configuration consistent.

​
Metadata and validation

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

Orders Metadata API

Reference coding systems, units, frequencies, and other order metadata.

Medication Orders API Guide

Review platform-level details for EHR validation, PBC linking, and API reconciliation.

​
FAQs

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.
Use the Orders Info API and related info endpoints to validate enums, such as status, frequency, and origin.
Pass the LOINC code 52471-0 in ambientOptions.sections and the enable_generated_orders feature flag to enable Medication orders in the Web SDK.

​
Best practices

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

​
Next steps

Refer to Medication orders overview to enable Medication orders in your Web SDK integration. Refer to Medication orders payload structure for the full field list. Refer to Get Ambient Session Structured Data to retrieve structured data for a session. Refer to Get Encounter Structured Data to retrieve structured data for an encounter.
Last modified on June 12, 2026