Interoperability - Best Practices & FAQs

Learn best practices, conflict handling, offline behavior, and FAQs for Ambient interoperability

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.

Prerequisites

• You create ambient sessions with emr_encounter_id when notes must work across modalities. See Use interoperable ambient notes across modalities.
• You store ambient_session_id, note_id, and related identifiers from create. See Interoperable identifiers.

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. The rejection 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.

First Session Never Uploads to Suki

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.

First session	Outcome
Web SDK never connects to Suki	Another supported ambient product can create a new session. No conflict is returned.
Headless product never connects to Suki	Another supported ambient product can create a new session. No conflict is returned.

Different Modality Ends Session

Scenario 2: A different modality ends the active session

A modality can end an ambient session that was started by another modality.

• If the original session is online, Suki processes the complete recording and generates the clinical note normally.

• If the original session has lost connectivity, Suki can process only the audio that was uploaded before the connection was lost. Any audio that was never uploaded is not included in the clinical note.

Connectivity of the original session	Outcome
Online	The complete recording is processed and the clinical note is generated successfully.
Offline after partial upload	Only the uploaded audio is processed. The resulting clinical note may be incomplete.

Switching During Active Session

Scenario 3: Switching modalities during an active session

Clinicians can switch from one supported ambient modality to another during the same patient encounter. For the best experience, end the current ambient session while it is still online before starting the next one.

If connectivity is lost before the first session finishes uploading, Suki processes only the audio that has already been received.

Current session state	Outcome
Session ends while online	The full recording is processed before the next session begins. This is the recommended workflow.
Session loses connectivity before upload completes	Only uploaded audio is processed. The next session can continue, but the clinical note may be incomplete.

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.

Headless Modality Re-Ambient

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.

Headless re-ambient behavior	Outcome
Prior diagnoses are not used as ML input	The new session generates diagnoses from the current recording only.
A diagnosis already exists on the note	Reconciliation keeps one unique diagnosis by replacing the previous entry with the new one.

Headed (Web SDK) Re-Ambient

Scenario 2: Headed (Web SDK) re-Ambient

The Web SDK includes prior recommendations when you re-ambient an existing clinical note.

If a diagnosis is updated across ambient sessions, the latest recommendation takes priority in the shared clinical note.

Headed re-ambient behavior	Outcome
Prior recommendations are included	The new session can build on diagnoses already present on the note.
A diagnosis is updated across sessions	The latest recommendation takes priority.

Medication Orders

Scenario 3: Medication orders

Orders follow the same overall reconciliation process as diagnoses when you re-ambient an interoperable clinical note.

In headed flows, order creation also depends on whether the medication code was present in the LOINC code set.

Order reconciliation	Outcome
Headless modality re-ambient	Orders follow the same reconciliation approach as diagnoses for the new session output.
Headed (Web SDK) re-ambient	Orders follow the same reconciliation approach as diagnoses, and order creation also depends on whether the medication code was present in the LOINC code set.

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 accepts a UUID or non-UUID value and must be at most 36 characters.
• 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 note_id to retrieve note content, context, and structured data.
• For re-ambient, reuse your stored encounter_id when you sent it. If the first create did not send encounter_id, pass the returned note_id as the encounter_id field value. Create has no separate note_id request field.

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.

Pass an EMR Encounter ID

Always pass emr_encounter_id when the clinical note must work across ambient modalities.

Store All Key Identifiers

Store emr_encounter_id, encounter_id, ambient_session_id, and note_id. For re-ambient, reuse encounter_id when you sent it. If the first create omitted encounter_id, pass the returned note_id as the encounter_id field value.

Seed Patient Context

If the note started on a headless product, seed patient context before you open the note in the Web SDK.

Choose the Right Retrieval API

Use note-level APIs for partner-facing retrieval after edits. Use session-level APIs when you need content from one recording only.

Space Concurrent Creates

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 Online Handoffs

Prefer ending sessions online before you switch modalities so Suki receives the full audio upload.

Handle Empty Sections

If you pass a LOINC code and no recommendation is generated, the section can still appear with empty data.

FAQs

Is Interoperability Available for Dictation or Form Filling?

No. Cross-modality interoperability is ambient-only in this release.

What Happens If I Omit emr_encounter_id?

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.

How Do I Re-Ambient from Another Modality?

Create a new ambient session with the same emr_encounter_id. For the note group, reuse your stored encounter_id when you sent it. If the first create omitted encounter_id, pass the previous note_id as the encounter_id field value.

Can I Re-Ambient If I Only Have note_id?

Yes. Pass the returned note_id as the value of the encounter_id field on create. Create has no separate note_id request parameter.

Does Get Note Content Include Web SDK Edits?

Yes. Get Note Content returns accumulated note content and, for edited sections, the latest edited section content.

Why Might Web SDK Show No Patient Profile After a Mobile or API Session?

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

Must emr_encounter_id Be a UUID?

No. emr_encounter_id accepts a UUID or non-UUID value. It must be at most 36 characters.

Troubleshooting

These are the issues teams hit most often when shipping interoperable ambient notes. The FAQs above cover the longer edge cases.

Create Conflict for the Same emr_encounter_id

Only one ambient session can be active for an emr_encounter_id at a time. Wait at least 1 second before another Create ambient session request for the same encounter. On Mobile SDK, create can fail with SukiAmbientCoreError.remoteSessionConflict. Pass blockingSessionId into cancel or end remotely, then retry.

Offline Handoff Leaves the Note Stuck

Prefer online handoffs when you can. If a modality goes offline with an active session, follow the offline guidance earlier on this page before creating again for the same encounter.

emr_encounter_id Format Rejected

emr_encounter_id accepts a UUID or non-UUID value and must be at most 36 characters. Longer EMR keys need a stable truncated or mapped value your products share.

Next steps

Use ambient across modalities - Create, continue, and retrieve interoperable ambient notes.

Interoperable identifiers - Identifier rules and Web SDK naming.

Ambient interoperability - An overview of how ambient products share the same clinical note.

Create ambient session API - request and response fields used by interoperable ambient sessions.