Skip to main content
Quick summary
Ambient interoperability uses a few identifiers to keep multiple ambient sessions on the same clinical note. Pass emr_encounter_id for the patient visit, pass encounter_id to continue or re-ambient the same note, and use composition_id as note_id to retrieve note content, context, and structured data.
Last updated:July 2026
Suki uses a small set of identifiers to associate multiple ambient sessions with the same clinical note. If a clinician starts an ambient session on one Suki product and later continues or re-ambients it on another, your application must pass the correct identifiers so that every ambient session is linked to the same patient encounter and clinical note. You provide these identifiers when calling the Create ambient session API or other note-level Ambient APIs.

​
Identifiers you provide

  • emr_encounter_id: Your EMR or EHR encounter identifier for the patient visit. Suki uses this identifier to create or locate the shared clinical note for that encounter.
  • encounter_id: Also called the Session Group ID. This identifier groups related ambient sessions so they all contribute to the same clinical note.

​
Identifiers returned by Suki

  • ambient_session_id: Uniquely identifies an individual ambient recording session.
  • composition_id: Uniquely identifies the shared clinical note created for the patient encounter. Use this value as the note_id when calling note-level Ambient APIs to retrieve or manage the note.

​
Identifier hierarchy

Use this hierarchy when you design interoperable ambient workflows:

​
EMR Encounter ID

emr_encounter_id is required when you want ambient sessions to share one clinical note across Ambient APIs, Mobile SDK, Headless Web SDK, and Web SDK. Use it when:
  • You want Mobile SDK and Web SDK to work on the same visit note
  • You want Ambient APIs and an SDK to share the same note
  • You want to list all notes for that EMR encounter later
You must remember these rules:
  • Always pass a valid UUID for emr_encounter_id
  • Without emr_encounter_id, the ambient session is created, but the note is not interoperable across Suki products
  • In the Web SDK, the encounter identifier you supply maps to this same EMR Encounter ID value
  • In the Mobile SDK, pass SukiAmbientConstant.kEmrEncounterId. Refer to Mobile SDK interoperability for more details.

​
Encounter ID (Session Group ID)

When you create an ambient session, the request field name is encounter_id. For interoperability, treat that value as the Session Group ID. Use the same Session Group ID when you want to:
  • Group more than one ambient session under the same clinical note
  • Re-ambient from another supported ambient product
You must remember these rules:
  • Session Group IDs can be up to 255 characters
  • Create ambient session does not return a separate encounter_id field
  • If you pass encounter_id, store the value you sent
  • If you omit encounter_id on the first session, the generated Session Group ID is the same as the returned composition_id
To re-ambient across ambient products, create a new ambient session with the same emr_encounter_id, and pass the existing Session Group ID as encounter_id.

​
Composition ID and Note ID

When you create an ambient session, Suki returns composition_id. Use that value as note_id with the note-level Ambient APIs:

​
Best practices and naming conventions

The Ambient APIs, Mobile SDK, and Web SDK support the same interoperability workflow, but they use different names for some identifiers. When your application uses more than one product, map these identifiers correctly. Using the wrong identifier can create a new clinical note instead of continuing an existing one.

​
Identifier mapping for all Ambient products

Refer to the following table for the identifier mapping for all ambient products:

​
Understand the two encounter identifiers

The names emr_encounter_id and encounter_id represent different concepts.
Do not use these values interchangeably. Although their names are similar, they serve different purposes. Using the wrong identifier prevents ambient sessions from being associated with the same clinical note.
For every interoperable ambient workflow, store the following identifiers in your application.
Store both the Session Group ID and the composition_id.The composition_id identifies the shared clinical note, while the Session Group ID is required to create additional ambient sessions for that note. If you only store the composition_id, you cannot determine the Session Group ID later for re-ambient workflows.

​
Next steps

Refer to How to use interoperability across Suki products to create, continue, and retrieve interoperable ambient notes. Refer to Best practices and FAQs for implementation guidance, conflict handling, and common questions. Refer to Create ambient session for the request and response fields used by interoperable ambient sessions. Refer to Ambient interoperability for an overview of how ambient products share the same clinical note.
Last modified on July 23, 2026