Use Interoperable Ambient Notes Across Modalities

Quick summary

Create an interoperable ambient session with emr_encounter_id to make the note interoperable. Use the same encounter_id for every re-ambient session on that note. Pass composition_id as note_id to retrieve the latest note content.

Last updated:August 2026

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.

Create an Ambient Session

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

Seed Patient Context

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

Capture Audio

Capture audio on one ambient modality.

Continue or Re-Ambient

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

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.

Example flow

To retrieve the latest note text, pass the returned composition_id as note_id to 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 UUID for the patient visit.
encounter_id: groups re-ambient sessions for the same note. Reuse the same value for every re-ambient session on that note.
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>",
  "composition_id": "<composition_id>" // you will use this as note_id in the 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.
`composition_id`	Call note-level Ambient APIs. Use this value as `note_id`.
`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.

Store emr_encounter_id, encounter_id, and composition_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:

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:

Pass the same emr_encounter_id (used as encounter.identifier in the Web SDK).
Pass the same encounter_id (for Mobile SDK and Ambient APIs only).

The encounter_id is required for every re-ambient session on that note when using the Mobile SDK or Ambient APIs. 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

Mobile SDK starts ambient with kEmrEncounterId = A (maps to emr_encounter_id) and kSessionId = G (maps to encounter_id).
Create returns sessionId and, for online creates, compositionId = N. Store compositionId as the note id and store G for re-ambient.
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 Ambient APIs create another session with emr_encounter_id = A and encounter_id = G.
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, pass the returned composition_id as note_id to 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

AmbientAPI

Share one note with emr_encounter_id.

5 min

AmbientAPI

Fetch Note Content with composition_id

Retrieve the note with composition_id.

5 min

Next steps

Refer to Best practices and FAQs for conflict handling, offline behavior, and common questions. Refer to Interoperable identifiers for identifier rules and Web SDK naming. 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.

Get Started

Concepts & Feature Guides

Tutorials

Resources

FAQs & Support

Use Interoperable Ambient Notes Across Modalities

Example flow

Step 1: Create an interoperable ambient session

Example request

Example response

Step 2: Store identifiers returned by the API

Step 3: Seed patient context

Example request

Step 4: Capture audio on the first modality

Step 5: Continue or re-Ambient on another modality

Scenario example

Step 6: Retrieve the shared clinical note

Choose the right content API

Available cookbooks

Fetch Note Content with composition_id

Next steps

​Example flow

​Step 1: Create an interoperable ambient session

​Example request

​Example response

​Step 2: Store identifiers returned by the API

​Step 3: Seed patient context

​Example request

​Step 4: Capture audio on the first modality

​Step 5: Continue or re-Ambient on another modality

​Scenario example

​Step 6: Retrieve the shared clinical note

​Choose the right content API

​Available cookbooks

​Share One Note Across Products

​Fetch Note Content with composition_id

​Next steps

Example flow

Step 1: Create an interoperable ambient session

Example request

Example response

Step 2: Store identifiers returned by the API

Step 3: Seed patient context

Example request

Step 4: Capture audio on the first modality

Step 5: Continue or re-Ambient on another modality

Scenario example

Step 6: Retrieve the shared clinical note

Choose the right content API

Available cookbooks

Share One Note Across Products

Fetch Note Content with composition_id

Next steps