Interoperable Identifiers

Understand EMR Encounter ID, Encounter ID, note ID, and naming conventions for Ambient interoperability

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.

Provide emr_encounter_id when calling the Create ambient session API for an interoperable session. For re-ambient, reuse your stored encounter_id when you sent it. If you create the first session without it, pass the returned note_id as the encounter_id field value. Create has no separate note_id request field.

Store and use emr_encounter_id, encounter_id, note_id, and ambient_session_id for interoperable re-ambient workflows.

Identifiers you provide

• emr_encounter_id: Required for interoperability. Your EMR or EHR encounter identifier for the patient visit. One EMR encounter can contain multiple clinical notes.
• encounter_id: Provided to group ambient sessions for one note. Reuse the same value for every re-ambient session on that note. If create did not send it, pass the returned note_id as this field’s value.

Identifiers returned by Suki

• ambient_session_id: Uniquely identifies an individual ambient recording session.
• note_id: Uniquely identifies the shared clinical note created for the patient encounter. Use it with note-level Ambient APIs.

Identifier hierarchy

Use this hierarchy when you design interoperable ambient workflows:

1. emr_encounter_id: the patient visit. One visit can contain multiple notes.
2. note_id: the clinical note for that visit.
3. encounter_id: the value that groups re-ambient sessions for one note. Reuse it for every re-ambient session on that note.
4. ambient_session_id: each recording session that contributes to that note.

Identifier	Purpose	Where it’s used
EMR Encounter ID	Identifies the patient encounter in your EMR or EHR. One EMR encounter can contain multiple notes.	Provide it as emr_encounter_id when calling Create ambient session API.
Note ID	Identifies the shared clinical note.	Returned as note_id. Use it with note-level Ambient APIs. If the first create omitted encounter_id, pass this value as the encounter_id field on later creates to re-ambient.
encounter_id	Groups re-ambient sessions for one note.	Provide it on the first session and reuse it. If the first create omitted it, pass the returned note_id as this field’s value.
ambient session ID	Identifies a single ambient recording session. Each recording has its own unique session ID, even when multiple sessions belong to the same clinical note.	Returned as ambient_session_id. Use it with session-level APIs for streaming, status, context, and session content.

Field mapping across products

Use this table when you pass the same visit or note across Ambient APIs, Mobile SDK, Headless Web SDK, and Web SDK. The platform value is the same. Each product uses a different field name.

Platform value	Ambient APIs	Mobile SDK	Headless Web SDK	Web SDK
Patient visit (interop)	emr_encounter_id	SukiAmbientConstant.kEmrEncounterId	emrEncounterId on session.create()	encounter.identifier
Re-ambient note group	encounter_id	SukiAmbientConstant.kSessionId	encounterId on session.create()	Not passed. Web SDK continues the note with encounter.identifier only.
One recording	ambient_session_id	Session ID from create	ambientSessionId from create / useAmbient	Session ID from SDK events / APIs as documented
Shared clinical note	note_id	noteId from create (online)	noteId from create / useAmbient	Retrieve through note APIs using the stored note id

EMR Encounter ID

emr_encounter_id is required to make a note interoperable across Ambient APIs, Mobile SDK, Headless Web SDK, and Web SDK. It identifies the patient visit, but it does not identify a single note because one EMR encounter can contain multiple notes.

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 UUID or non-UUID value for emr_encounter_id, at most 36 characters.
• 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.
• In the Headless Web SDK, pass emrEncounterId on session.create(). Refer to Headless Web SDK interoperability for more details.

Encounter ID

When you create an ambient session, pass encounter_id to group ambient sessions for one note when you re-ambient.

Use encounter_id to:

• Pass a grouping value on the first session.
• Reuse that same value on later re-ambient sessions for the same note.
• Or, when 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.

You must remember these rules:

• encounter_id can be up to 255 characters.
• Create ambient session API does not return a separate encounter_id field.
• If you sent encounter_id on the first create, store and reuse it for every re-ambient session on the note.
• If you did not send encounter_id on the first create, pass the returned note_id as the encounter_id value on later creates.

To re-ambient across ambient products, create a new ambient session with the same emr_encounter_id. 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.

Note ID

When you create an ambient session, Suki returns note_id. Use it with the note-level Ambient APIs. If the first create omitted encounter_id, also pass this value as the encounter_id field on later creates to re-ambient the same note. Create has no separate note_id request field.

• Note Content to retrieve the note content.
• Note Context to retrieve the note context.
• Note Structured Data to retrieve the note structured data.

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

Use Field mapping across products as the canonical Ambient API, Mobile SDK, Headless Web SDK, and Web SDK field map. Keep these details in mind:

• Pass SukiAmbientConstant.kEmrEncounterId ("emrEncounterId") for the patient visit in the Mobile SDK.
• Pass SukiAmbientConstant.kSessionId ("sessionId") for re-ambient grouping in the Mobile SDK. That value matches Ambient API encounter_id. Reuse it when you set it on the first create. If the first create omitted encounter_id, pass the returned noteId as kSessionId. Create response sessionId is the ambient session ID, not encounter_id.
• In the Headless Web SDK, pass emrEncounterId for the patient visit and encounterId for re-ambient grouping. If the first Ambient create omitted encounter_id, pass the returned noteId as encounterId. Create returns ambientSessionId and noteId. Conflict responses expose blockingSessionId on error.additionalProperties.
• When you call Mobile encounterContent, pass the same re-ambient grouping value as encounterId.
• Store create response note_id (or SDK noteId) and use it on note APIs. When re-ambienting without a stored encounter_id, pass that same value in the encounter_id / encounterId / kSessionId field.

Understand the two encounter identifiers

The names emr_encounter_id and encounter_id represent different concepts.

Identifier	Purpose
emr_encounter_id	Identifies the patient encounter in your EMR or EHR. One encounter can contain multiple notes. In the Web SDK, this is referred to as the Encounter ID.
encounter_id	Ambient API field used to group re-ambient sessions for one note.

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 identifiers your integration uses:

Identifier	Why you should store it
emr_encounter_id	Create additional ambient sessions for the same patient encounter.
ambient_session_id	Identify and manage an individual ambient recording session.
note_id	Retrieve and manage the shared clinical note using note-level Ambient APIs.
encounter_id	Create ambient session does not return it, so store the value you provide and reuse it. If the first create omitted it, pass the returned note_id as the encounter_id field value on later creates.

Store emr_encounter_id, encounter_id, and note_id.

Next steps

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

Interoperability best practices and FAQs - Implementation guidance, conflict handling, and common questions.

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

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

Headless Web SDK interoperability