Skip to main content
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:April 2026
Medication orders are supported by: APIs, Mobile SDK
Alpha access:Medication orders are available in early alpha and are gated behind a feature flag.To participate in the alpha rollout, contact Suki to enable the enable_medication_orders flag for your organization.
  • REST APIs: Send encounter configuration, context, and retrieve structured order payloads through our SDP 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.

​
Overview

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.

​
Key features

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.

​
Integration workflow

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)

Ingest context

Use the POST Context API to send the patient’s active medication list and any orders from prior sessions. For high-fidelity generation, explicitly separate encounter_context from previous_session_orders so the service can tell current encounter data from earlier session data.While sending the medication orders to the context API, set status on each medication order to ACTIVE, DISCONTINUED, or REFILLED.
Status valueMeaning
ACTIVEActive medication order
DISCONTINUEDDiscontinued medication order
REFILLEDRefill medication order

Run cumulative reconciliation ("Diff" logic)

The Medical Orders Service applies re-ambient reconciliation using:
  • Active medications shared from the EHR
  • Orders generated from previous sessions
  • The current session transcript
The API returns an updated cumulative list. Medications can be labeled NEW, DISCONTINUE, or REFILL.

Retrieve structured data

Call the structured data endpoints to read generated orders. Use the paths in Retrieve structured orders. For the full structured payload (not only orders), see Get structured data and Get encounter structured data.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"
  }
}
REST alignment: On the Context API, set emr.target_emr to ATHENA, EPIC, or CERNER so medication validation lines up with the same EHR you target at encounter configuration (see Step 1 above). That guide also lists required fields when you send orders.medication_orders.values on the same request.

​
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.
Last modified on April 20, 2026