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:July 2026
This guide covers the practices and edge cases that matter when you build interoperable ambient workflows in production: concurrent session conflicts, offline handoffs, diagnosis and order reconciliation, current limitations, and frequently asked questions.

​
Best practices

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, the Session Group ID (encounter_id), ambient_session_id, and composition_id together in your application.
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.

​
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.
  • If you only have note_id or composition_id, you cannot re-ambient yet. You must already have the Session Group ID (encounter_id).
  • Create ambient session returns composition_id. Use that value as note_id with note-level Ambient APIs.

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

​
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 pass the existing Session Group ID as encounter_id.
Not yet. You need the Session Group ID. Store it when you create the first session. 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.
Headless sessions can start with only emr_encounter_id. Web SDK needs patient profile fields. Seed patient_id, name, dob, and sex through the session Context API before opening the Web SDK.
Seed ambient session Context
Yes today. The platform validates emr_encounter_id as a UUID. Support for shorter non-UUID client strings is planned for a future phase.

​
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 July 23, 2026