Skip to main content
POST
cURL
Updated:You can now provide EMR context and medication details in the ambient session context API.
Use this endpoint to provide or update the for an . Providing detailed context helps Suki generate a more accurate and relevant .
For ambient notes that open in Web SDK, seed patient details in this context call: patient_id, name, dob, and sex. Web SDK needs these fields to show the patient profile. Refer to Use ambient across modalities for more details.
For example, you can provide:
  • details (e.g., specialty and role).
  • Patient and visit information.
  • A list of codes for the clinical sections you want to generate.
  • Existing with their associated medical codes.
  • EMR context, including target EMR, when you need EMR-specific behavior (for example order submission rules).
  • Orders context (medication orders), including structured medication orders for active medications and related metadata.
For more information about the context, refer to the PBC and Specialty section. For more information about medication orders, refer to the Medication orders guide.
Use the Codes section to provide additional context for a session, such as medical codes for a diagnosis.
To ensure your requests succeed, follow these validation rules when sending data to the API:

​
Field validation and constraints

  • Character Limits: Ensure the chief_complaint and reason_for_visit fields do not exceed 255 characters.
  • Enumerated Values: Use only the predefined string values for visit_type, encounter_type, and provider_role.
  • EMR Selection: You must set emr.target_emr to one of the following: ATHENA, EPIC, or CERNER.

​
Medication order requirements

When you send orders.medication_orders.values, include the following required properties for each object:
  • Drug Information: Provide both the drug_name and a medication_code.
  • Coding Systems: For medication_code, specify the code and set the type to RXCUI or NDC.
  • Order Status: Set the status to ACTIVE, DISCONTINUED, or REFILLED.
  • Metadata: Include the metadata object with a required origin of EMR or SUKI_AMBIENT.
If you set origin to EMR, you must also set metadata.encounter_relation to either CURRENT_ENCOUNTER or PRIOR_ENCOUNTER.
Diagnosis links:To link a diagnosis to an order, ensure the codes in linked_diagnosis_codes match a diagnosis already provided in the diagnoses section. Use the same coding system for both to allow the service to validate the link.

​
Code examples

Authorizations

​
sdp_suki_token
string
header
required

Suki access token (suki_token) from Login or Register. Expires after one hour.

Headers

​
sdp_provider_id
string

Optional for standard partners.

Required for:

  • Bearer authentication. Use the same provider_id returned by the Login or Register API.
  • Single Auth Token authentication. Include the same provider_id on every request as sdp_provider_id.
Example:

"provider-123"

Path Parameters

​
ambient_session_id
string
required

UUID for the ambient session. Use the ambient_session_id returned from Create Ambient Session, or the UUID you supplied in that request.

Body

application/json

Clinical context for the ambient session, including provider, patient, visit, sections, diagnoses, EMR, and medication orders.

​
diagnoses
object

Optional - Existing diagnoses and coded values to include in note generation.

​
emr
object

Optional - EMR context, including the target EMR system.

​
orders
object

Optional - Medication orders and related order context.

​
patient
object

Optional - Patient demographics such as date of birth and sex.

​
provider
object

Optional - Provider role and specialty for the session.

​
sections
object[]

Optional - Information about the sections to be generated. If not provided, all supported note-sections will be generated.

​
visit
object

Optional - Visit details such as chief complaint and encounter type.

Response

Last modified on July 23, 2026