Skip to main content
Quick summary
Follow these best practices when you use interoperable ambient clinical notes across modalities: always pass an emr_encounter_id, space create requests for the same EMR encounter, prefer online handoffs, store the right identifiers, and use note-level APIs after Web SDK edits.
Last updated:August 2026
This guide covers the best practices and edge cases that matter when you build interoperable ambient workflows in production: concurrent session conflicts, offline handoffs, diagnosis and order reconciliation. Check out the current limitations and frequently asked questions below to clear up any doubts.

​
Concurrent ambient sessions

Only one ambient session can be active for an emr_encounter_id at a time. If your application attempts to create another ambient session for the same patient encounter while an existing session is still in progress, Suki rejects the request and returns a conflict response. This prevents multiple active sessions from writing to the same clinical note simultaneously. The conflict response can include:
  • The active ambient_session_id.
  • The modality that owns the active session.
  • How long the active session has been running.
  • Do not create multiple ambient sessions for the same emr_encounter_id at nearly the same time. For Ambient API create calls, wait at least 1 second before sending another Create ambient session request for the same encounter. Requests sent too quickly can result in a conflict response.
  • On the Mobile SDK, create fails with SukiAmbientCoreError.remoteSessionConflict(blockingSessionId:). Pass blockingSessionId to cancelRemoteAmbientSession or endSessionRemotely, then retry create. Mobile SDK does not require an extra delay after the remote call succeeds. Refer to Mobile SDK interoperability for more details.

​
Offline and connectivity

Ambient interoperability works best when each ambient session can upload its audio and metadata to Suki before the next session begins. When a clinician switches from one Suki product to another, Suki can only process the audio that has already been uploaded. If the first device loses connectivity before its recording is uploaded, any audio that did not reach Suki cannot be recovered and will not be included in the clinical note. To minimize data loss, follow these best practices:
  • End the current ambient session while the device is online.
  • Allow the session to upload successfully before starting another ambient session for the same patient encounter.
  • Avoid switching products while a session is still uploading whenever possible.
Offline handoffs are supported, but they are a best-effort experience. Depending on when connectivity is lost, the resulting clinical note may be incomplete.
The tabs below describe common connectivity scenarios, including:
  • An ambient session that never uploads to Suki.
  • Ending an ambient session from a different Suki product.
  • Switching between products while an ambient session is still active.

​
Scenario 1: The first session never uploads to Suki

If the first ambient session is created while the device is completely offline and no audio or metadata is uploaded, Suki is unaware that the session exists.Because no active session is registered, another Suki product can create a new ambient session for the same emr_encounter_id without receiving a conflict.

​
Diagnosis and order reconciliation behavior

When you re-ambient an interoperable clinical note, Suki reconciles diagnoses and orders differently depending on whether the new session starts on a headless or headed modality. The tabs below describe how each modality handles prior recommendations when you add another ambient session to the same clinical note.

​
Scenario 1: Headless modality re-Ambient

Headless modalities do not use prior diagnoses as ML input when you start a new ambient session for an existing clinical note.If the new session generates a diagnosis that already exists on the note, reconciliation keeps a single unique diagnosis by replacing the previous entry with the new one.

​
Interoperability limitations

Keep these current limitations in mind while you design your interoperable ambient workflows:
  • Interoperability is ambient-only. Dictation and Form filling are currently out of scope.
  • emr_encounter_id must be a UUID today.
  • Without emr_encounter_id, the clinical note is not interoperable across modalities.
  • Use the same encounter_id for every re-ambient session on the same note.
  • Use composition_id as note_id to retrieve note content, context, and structured data. Do not use note_id or composition_id in place of encounter_id when you create a re-ambient session.

​
Partner type compatibility

Suki no longer uses partner_type to determine request origin or ambient job type for new partners. Existing partners do not need to pass suki_user_agent. Backward compatibility through partner_type remains supported.
No action is required form your side for current integrations.

​
Best practices for interoperable ambient workflows

Use these practices when you design and run interoperable ambient integrations.
Always pass emr_encounter_id when the clinical note must work across ambient modalities.
Store emr_encounter_id, encounter_id, ambient_session_id, and composition_id. Reuse encounter_id for every re-ambient session on the same note.
If the note started on a headless product, seed patient context before you open the note in the Web SDK.
Use note-level APIs for partner-facing retrieval after edits. Use session-level APIs when you need content from one recording only.
Do not create sessions for the same EMR encounter at the same time. Wait at least 1 second between create requests for that emr_encounter_id.
Prefer ending sessions online before you switch modalities so Suki receives the full audio upload.
If you pass a LOINC code and no recommendation is generated, the section can still appear with empty data.

​
FAQs

No. Cross-modality interoperability is ambient-only in this release.
The session and clinical note are still created, but the note is not interoperable across modalities. You cannot reliably continue or retrieve that note outside the originating modality using the EMR encounter workflow.
Create a new ambient session with the same emr_encounter_id and encounter_id
No. Use note_id to retrieve note content. For re-ambient, pass the same emr_encounter_id and encounter_id. An encounter lookup API for this flow is not available in this release.
Create ambient session returns composition_id. Use that value as note_id when you call note-level Ambient APIs:
Yes. Get Note Content returns accumulated note content and, for edited sections, the latest edited section content.
Mobile SDK and Ambient API sessions can start without patient profile fields. The Web SDK needs those fields to show the patient profile page. Seed patient_id, name, dob, and sex through the Seed ambient session context API before you open the Web SDK, or pass the same details on encounter.patient when you mount the Web SDK.
Seed ambient session Context
Yes today. The platform validates emr_encounter_id as a UUID.

​
Next steps

Refer to Use ambient across modalities to create, continue, and retrieve interoperable ambient notes. Refer to Interoperable identifiers for identifier rules and Web SDK naming. Refer to Ambient interoperability for an overview of how ambient products share the same clinical note. Refer to Create ambient session for the request and response fields used by interoperable ambient sessions.
Last modified on August 13, 2026