Medication Orders

Quick summary

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.

Last updated:July 2026

Medication orders are supported by: APIs, Mobile SDK, Web SDK

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

REST APIs: Send encounter configuration, context, and retrieve structured order payloads through our Ambient APIs (including the Context API and structured data endpoints mentioned below).
Mobile SDK (iOS): Pass optional medication context on after you create a session. Refer to Orders info section in provide clinical context for more information.
Web SDK: Use the Medication orders integration guide to configure and generate medication orders in the Headed Web SDK.

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 , Suki surfaces medication recommendations. The service converts them into structured payloads (for example RxCUI codes) 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 spans more than one .
Integrate flexibly: Pull full 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

EHR-Centric Validation

Apply strict validation logic for your configured EHR so orders stay submittable under that system’s rules.

Problem-Based Context (PBC)

Every order links to a mandatory diagnosis so fidelity stays high and each order traces to a problem in the session.

Cumulative Session Reconciliation

Re-ambient logic reconciles orders across multiple sessions in one encounter, using active medications, prior session data, and the current transcript.

Flexible Retrieval

Pull all structured data at once, or target medication orders only when that fits your app.

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

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.

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.

Ambient APIs
Web SDK
Mobile SDK

Send medication context through the Context API, run the ambient session, then retrieve structured orders from the structured data endpoints.

Configure the Encounter

Set EHR context at the encounter level so validation applies for the whole session.

Field: submittable_ehr
Type: enum (for example athena, epic, cerner)

Send Medication Context

Use the Context API 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.

Run the Ambient Session

Stream audio and end the session. The Medical Orders Service reconciles active medications, prior session orders, and the current transcript.

Retrieve Structured Orders

Call the structured data endpoints and read generated orders from the response. Use Get structured data for session-scoped orders or Get encounter structured data for encounter-scoped orders.Example medication order payload

JSON

{
  "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"
  }
}

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.

Confirm Access Is Enabled

Medication orders must be enabled for your organization before you integrate. Contact Suki if you have not already requested access.

Add the Medication Orders Section

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

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 and Ambient implementation for full mount options.

Capture and Review in the SDK UI

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.

Receive Orders on Note Submit

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

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 and Medication orders payload structure for the full response shape.

Submit Orders to Your EHR

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.

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.

Confirm Access Is Enabled

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.

Create the Ambient Session

Call createSession(withSessionInfo:) and store the returned sessionId. Refer to Create session.

Send Medication Context

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

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 for required fields and validation rules.

Record and End the Session

Start recording, capture the visit, then call end() so Suki can generate note content and structured medication orders.

Retrieve Medication Orders

After processing completes, call getStructuredData(for:) with the valid sessionId. Read complete and partial orders from the returned medication orders object.

Swift

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 for the full retrieval flow.

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.

Retrieve structured orders

Use the following endpoints to retrieve structured orders:

Session-Scoped Medication Orders

Retrieve structured orders for a session

Encounter-Scoped Medication Orders

Retrieve structured orders for an encounter

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.

Get Started

Concepts & Feature Guides

Tutorials

Resources

FAQs & Support

Medication Orders

How Medication orders improves clinical documentation

Medication order capabilities

EHR-Centric Validation

Problem-Based Context (PBC)

Cumulative Session Reconciliation

Flexible Retrieval

Technical requirements

How to use Medication orders in your application

Retrieve structured orders

Session-Scoped Medication Orders

Encounter-Scoped Medication Orders

Global filtering rules

​How Medication orders improves clinical documentation

​Medication order capabilities

EHR-Centric Validation

Problem-Based Context (PBC)

Cumulative Session Reconciliation

Flexible Retrieval

​Technical requirements

​How to use Medication orders in your application

​Retrieve structured orders

Session-Scoped Medication Orders

Encounter-Scoped Medication Orders

​Global filtering rules

How Medication orders improves clinical documentation

Medication order capabilities

Technical requirements

How to use Medication orders in your application

Retrieve structured orders

Global filtering rules