Skip to main content
Quick summary
Ambient interoperability allows multiple Suki ambient products to work on the same clinical note for a patient visit. To enable interoperability, provide an emr_encounter_id when you create the first ambient session. Suki creates a shared clinical note and associates all ambient sessions for that patient visit with that note.

If you create additional ambient sessions for the same note, use the same encounter_id. This lets clinicians start recording in one Suki product, continue or re-ambient in another, and review or edit the same note across supported products instead of creating separate notes. To retrieve the latest version of the shared clinical note through the Ambient APIs, use the note’s note_id.
Last updated:August 2026
Supported interoperable modalities: Ambient APIs, Mobile SDK, Headless Web SDK, and Web SDK.
Interoperability applies only to Ambient workflows. It is not supported for other workflows.
Interoperability brings different products together to share data and work together. In Suki, ambient interoperability lets you start, continue, and review clinical documentation across multiple Suki products for the same patient encounter, while every ambient session stays linked to the same clinical note. You can use ambient interoperability across the Mobile SDK, Headless Web SDK, Web SDK, and Ambient APIs.

​
How it works

A patient encounter can contain multiple clinical notes. Suki uses identifiers to determine which encounter and note an ambient session belongs to:
  • emr_encounter_id identifies the patient encounter in your EMR or EHR. One emr_encounter_id can contain multiple notes.
  • encounter_id connects ambient sessions to one note within that patient encounter. Use the same encounter_id for every ambient session that belongs to the same note.
  • note_id identifies the clinical note. Use the note_id with the Ambient APIs to retrieve the latest version of the note.
The important distinction is that emr_encounter_id identifies the overall patient encounter, while encounter_id connects ambient sessions to a specific note within that encounter. Product-specific field names for those values are on Interoperable identifiers.

​
Why interoperability matters

Without ambient interoperability, an ambient session is tied to the Suki modality where it was created. For example, a session created through the Mobile SDK can only be continued or retrieved through the Mobile SDK. A session created through the Ambient APIs can only be managed through the APIs. With , supported Suki modalities can work with ambient sessions for the same note. This lets a clinician move between modalities without losing the connection to the note. For example, a clinician can:
  • Start an ambient session using the Mobile SDK.
  • Start another ambient session using the Web SDK for the same note.
  • Open the note in the Mobile SDK to review, edit, and submit it.
  • Retrieve the latest version of the note through the Ambient APIs using the note_id.
For sessions to belong to the same note, use the same emr_encounter_id and encounter_id. This allows you to build workflows that use different Suki modalities while keeping ambient sessions for the same clinical note connected.

​
Shared clinical note

The core of ambient interoperability is a shared clinical note. When you create the first ambient session, provide emr_encounter_id. That value identifies the patient visit and makes the note interoperable. Suki creates a shared clinical note and associates ambient sessions for that visit with that note. When you create additional ambient sessions for the same note, reuse the same encounter_id. That keeps re-ambient sessions on the same note, whether the clinician continues in the Mobile SDK, Web SDK, or Ambient APIs. Each product uses that shared value through its own fields. The products do not share audio recordings. Each ambient session adds content to the shared clinical note. To retrieve the latest version of that note through the Ambient APIs, use the note’s note_id.

​
Headless and Headed ambient integrations

Ambient interoperability works across all Suki products that support ambient workflows, including headless and headed integrations. Because every Suki ambient integration references the same note, you can combine headless and headed ambient integrations within the same patient encounter.

​
How to implement interoperable ambient sessions

To create an interoperable ambient session, provide emr_encounter_id. Provide encounter_id when the session will be part of a re-ambient workflow, then reuse the same value for each re-ambient session. During the ambient workflow for the same patient visit, you need to:
1

Create an Ambient Session

Create an ambient session with emr_encounter_id and encounter_id for a re-ambient workflow.
2

Receive the Shared Note Identifiers

Suki creates a shared clinical note and returns identifiers, including the composition_id.
3

Create Additional Sessions for the Same Visit

Create re-ambient sessions with the same emr_encounter_id and encounter_id.
4

Continue Across Products

Continue recording, re-ambient, review, or edit from any supported Suki product that supports ambient workflows.
5

Retrieve the Latest Note

Use the returned composition_id as the note_id to retrieve the latest note content through the Ambient APIs.
Without emr_encounter_id, Suki still creates an ambient session, but the note is not interoperable across products.For re-ambient workflows, store and reuse the same encounter_id for every ambient session on that note.

​
Common integration patterns and use cases

Design your application interoperability around the clinician’s journey, not around a specific Suki product. A clinician may begin documentation on one device and finish it somewhere else during the same patient encounter. The following patterns show common ways to build interoperable ambient workflows using a shared emr_encounter_id.

Capture on Mobile, Review on Web

In the Mobile SDK, use the returned emr_encounter_id as SukiAmbientConstant.kEmrEncounterId. In the Web SDK, use that value as encounter.identifier so the clinician can review, edit, and submit the note.

Capture on Web, Continue on Mobile

Start ambient in the Web SDK with encounter.identifier, then continue or re-ambient in the Mobile SDK with the same value as SukiAmbientConstant.kEmrEncounterId.

Capture with APIs, Review in Web SDK

Use the Ambient APIs to create the session and stream audio from your backend. Open the resulting note in the Web SDK for clinician review and submission.

Resume Later on Another Product

If a clinician starts ambient on one product and returns later on another, pass the same emr_encounter_id (and encounter_id for re-ambient on Mobile SDK or Ambient APIs) so they pick up the same clinical note.

Continue Documentation Across Products

Use the returned emr_encounter_id through each product’s corresponding field when clinicians continue documentation across products.

Keep Your Application in Sync

After clinicians edit the note in the Web SDK, use the note_id to retrieve the latest note content through the Ambient APIs.

Headless Capture, Headed Review

Capture audio in your own React experience using the Headless Web SDK, then transition to the Web SDK when the clinician is ready to review and submit the note.

One Visit Identifier, Shared Notes

Use emr_encounter_id to make notes interoperable for the patient visit. Reuse encounter_id for re-ambient on the same note.

​
Design principles for interoperable ambient sessions

Interoperable ambient sessions let multiple Suki products participate in the same clinical documentation workflow. Instead of treating each Suki product as an isolated system, design your application around the patient encounter and the shared clinical note. Keep the following principles in mind when building your integration:
  • Store the identifiers you provide. The emr_encounter_id makes the note interoperable. Store and reuse encounter_id for every re-ambient session on that note.
  • Choose products based on workflow, not data ownership. Mobile SDK, Headless Web SDK, Web SDK, and the Ambient APIs all provide different user experiences, but they can contribute to the same clinical note.
  • Build for handoffs between products. Clinicians can begin recording on one device, continue from another, or review later in a different interface without creating separate notes.
  • Always retrieve the latest composition. After additional recordings or clinician edits, use the returned composition_id as the note_id to retrieve the latest version of the shared note before writing back to your EHR or downstream systems.
Designing around these principles keeps every ambient product synchronized throughout the patient encounter while eliminating the need to merge notes or reconcile multiple versions yourself.

Identifiers

Map emr_encounter_id, encounter_id, composition_id, and note_id across Ambient APIs, Mobile SDK, and Web SDK.

Use Ambient Across Modalities

Follow a complete workflow that creates, continues, and retrieves interoperable ambient notes.

Best Practices and FAQs

Review implementation guidance, conflict handling, offline behavior, and frequently asked questions.

Create Ambient Session API

See the request and response fields required for interoperable ambient sessions.

Mobile SDK Interoperability

Pass kEmrEncounterId, handle remote conflict and peer terminate, and read shared notes on iOS.
Last modified on August 26, 2026