Use Interoperable Ambient Notes Across Modalities

Create interoperable ambient sessions with emr_encounter_id, continue or re-ambient across products, seed patient context, and retrieve shared note content

This guide will demonstrate how to use an interoperable ambient clinical note workflow across ambient modalities.

You will follow the steps below to use an interoperable ambient clinical note workflow across ambient modalities.

1. Create an Ambient Session

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

2. Seed Patient Context

   Seed patient context when the Web SDK may open the note later.

3. Capture Audio

   Capture audio on one ambient modality.

4. Continue or Re-Ambient

   Continue or re-ambient on another ambient product using the same emr_encounter_id and encounter_id.

5. Retrieve the Shared Clinical Note

   Use the note_id to retrieve the shared clinical note content and structured data using the note-level Ambient APIs.

Prerequisites

• A valid Suki Token. See Partner authentication.
• An emr_encounter_id you can send on create so the note is interoperable across modalities.
• Familiarity with create, context, streaming, and retrieve flows for Ambient APIs or the SDK products you use.

Example flow

To retrieve the latest note text, use the returned note_id with the following API:

Get Note Content API

Step 1: Create an interoperable ambient session

Use the Create ambient session API to create a new interoperable ambient session.

For a session to be interoperable, pass:

• emr_encounter_id: required EMR or EHR encounter id for the patient visit (UUID or non-UUID, at most 36 characters).
• encounter_id: groups re-ambient sessions for the same note. Reuse the same value when you sent it on the first create. If the first create omitted it, pass the returned note_id as the encounter_id field value.
• ambient_session_id: optional UUID for this recording session.

Example request

cURL

curl --request POST \
  --url https://sdp.suki.ai/api/v1/ambient/session/create \
  --header 'Content-Type: application/json' \
  --header 'sdp_suki_token: <sdp_suki_token>' \
  --header 'sdp_provider_id: <sdp_provider_id>' \
  --data '{
    "ambient_session_id": "<ambient_session_id>",
    "emr_encounter_id": "<emr_encounter_id>",
    "encounter_id": "<encounter_id>"
  }'

Example response

JSON

{
  "ambient_session_id": "<ambient_session_id>",
  "note_id": "<note_id>" // use with note-level Ambient APIs
}

If you omit emr_encounter_id, Suki still creates an ambient session, but the note is not interoperable across Suki products.

Step 2: Store identifiers returned by the API

After you create the new ambient session using the REST API, store the identifiers in your application.

Identifier	Why you should store it
emr_encounter_id	Create more ambient sessions for the same patient encounter and list notes for that encounter later.
ambient_session_id	Call session-level APIs for context, streaming, status, and session content.
note_id	Call note-level Ambient APIs.
encounter_id	The create response does not return it, so store the value you provide and reuse it for every re-ambient session on that note. If the first create omitted it, pass the returned note_id as the encounter_id field value.

Store emr_encounter_id, encounter_id, and note_id as these are the identifiers you will use to create and continue interoperable ambient sessions on another modality.

Step 3: Seed patient context

The Web SDK requires patient information to display the patient profile. The Mobile SDK and Ambient APIs do not require these fields to create or continue an ambient session.

Before the clinician opens the shared note in the Web SDK, call the Seed ambient session context API to provide the patient details.

Example request

cURL

curl --request POST \
  --url https://sdp.suki.ai/api/v1/ambient/session/<ambient_session_id>/context \
  --header 'Content-Type: application/json' \
  --header 'sdp_suki_token: <sdp_suki_token>' \
  --header 'sdp_provider_id: <sdp_provider_id>' \
  --data '{
    "patient": {
      "patient_id": "<patient_id>",
      "name": {
        "given": ["Alex"],
        "family": "Patient"
      },
      "dob": "2000-01-01",
      "sex": "female"
    }
  }'

The following patient fields are required to open the shared note in the Web SDK:

• patient_id.
• name.
• dob.
• sex.

Seed the patient context before opening the Web SDK

• If you open the Web SDK before seeding the patient context, the shared note opens without a patient profile.
• If no patient context is provided for a new emr_encounter_id, the Web SDK cannot load or create a note for that encounter.
• If no patient context is provided for an existing emr_encounter_id, providers cannot resume (re-ambient) the existing note.

You can update context later with the Update ambient session context API.

Step 4: Capture audio on the first modality

Use the ambient modality that fits the first part of the visit:

• Ambient APIs.
• Mobile SDK.
• Headless Web SDK.
• Web SDK.

Record and complete that ambient session the same way you normally would for that product.

Step 5: Continue or re-Ambient on another modality

To continue the same clinical note from a different ambient modality, create a new ambient session and:

1. Pass the same emr_encounter_id (used as encounter.identifier in the Web SDK, emrEncounterId in the Headless Web SDK, and kEmrEncounterId in the Mobile SDK).
2. Pass the same encounter_id when you sent it (for Mobile SDK, Headless Web SDK, and Ambient APIs). If the first create omitted encounter_id, pass the returned note_id as the encounter_id / encounterId / kSessionId value.

The encounter_id field is required for every re-ambient session on that note when using the Mobile SDK, Headless Web SDK, or Ambient APIs. Pass either your stored encounter_id or, when the first create omitted it, the note_id value in that field. The Web SDK does not pass or require an encounter_id to continue or re-ambient the clinical note.

Re-ambient means starting an additional ambient session for an existing clinical note. It is not limited to the ambient product that started the first session.

Scenario example

1. Mobile SDK starts ambient with kEmrEncounterId = A (maps to emr_encounter_id) and kSessionId = G (maps to encounter_id).
2. Create returns sessionId and, for online creates, noteId = N. Store noteId and store G for re-ambient. On Ambient APIs, the same value is note_id.
3. Later, another product continues or re-ambients:.
   • The Web SDK starts a session using encounter.identifier = A (maps to emr_encounter_id). It does not need or pass encounter_id to continue note N.
   • Or, the Headless Web SDK creates another session with emrEncounterId = A and encounterId = G.
   • Or, the Ambient APIs create another session with emr_encounter_id = A and encounter_id = G.
4. Both ambient sessions belong to clinical note N.

Step 6: Retrieve the shared clinical note

After ambient sessions complete, or after a clinician edits the note in the Web SDK, use the returned note_id with the note-level Ambient APIs.

Goal	API to use
List all notes for the EMR encounter	List Encounter Notes
Get the latest note section content, including Web SDK edits	Get Note Content
Get visit context aggregated across ambient sessions in the note	Get Note Context
Get diagnoses and orders accumulated across ambient sessions in the note	Get Note Structured Data

Choose the right content API

Choose the API based on whether you need data from a single ambient session or from the entire shared clinical note.

If you need	API to use	What it returns
Content from a single ambient recording session	Session Content	Clinical note sections generated for the specified ambient_session_id only.
The complete shared clinical note, including clinician edits	Get Note Content	The latest version of the entire clinical note. If sections have been edited, the API returns the updated text.
Structured data from a single ambient recording session	Session Structured Data	Diagnoses, orders, and other structured data for the specified ambient_session_id only.
Structured data accumulated across all sessions in the shared clinical note	Get Note Structured Data	Combined diagnoses, orders, and other structured data for the entire clinical note.
The latest structured data for an encounter	Encounter Structured Data	Diagnoses and orders from the most recent ambient session for the encounter. This response is not cumulative.
All clinical notes associated with an EMR encounter	List Encounter Notes	The note IDs and current status of every clinical note associated with the specified emr_encounter_id.

If clinicians edit the note in the Web SDK, use the Get Note Content API API to read the latest edited text.

Available cookbooks

Troubleshooting

Interoperability breaks when create omits emr_encounter_id, re-ambient reuses the wrong ID, or you fetch session content after headed edits.

Note Does Not Appear Across Products

Pass emr_encounter_id on create. If you omit it, Suki still creates an ambient session, but the note is not interoperable across Suki products.

Re-Ambient Opens a New Note Instead of the Same One

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

Create Conflicts on the Same EMR Encounter

Only one ambient session can be active for an emr_encounter_id at a time. Wait at least 1 second before another create for that encounter, or resolve the remote conflict on Mobile SDK first. See Interoperability best practices and FAQs.

Web SDK Edits Missing from Your Retrieve

After clinicians edit in the Web SDK, call Get note content with note_id. Session content alone will not include those headed edits.

Next steps

Interoperability best practices and FAQs - Conflict handling, offline behavior, and common questions.

Interoperable identifiers - Identifier rules and product field mapping.

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 - shared note starts or continues in a custom React UI.