Use Interoperable Ambient Notes Across Modalities

Quick summary

Create an ambient session with an emr_encounter_id so Suki can share one clinical note across ambient products. Store the returned identifiers, seed patient context before opening the Web SDK, reuse the Session Group ID to continue or re-ambient on another product, and use note-level Ambient APIs to retrieve the latest note content.

Last updated:July 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 an emr_encounter_id.

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

Retrieve the shared clinical note content and structured data.

Example flow

To retrieve the latest note text, use the following API:

Get Note Content API

Step 1: Create an interoperable Ambient session

Create a new session with the Create ambient session API to create a new interoperable ambient session. For the new session to be interoperable, pass:

emr_encounter_id: your EMR or EHR encounter UUID for the patient visit
encounter_id: the Session Group ID when you continue an existing note. Omit this on the first session if you want Suki to generate one
ambient_session_id: optional UUID for this recording session

Example request

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.
`encounter_id`	Continue or re-ambient the same clinical note on another ambient product. If you omitted `encounter_id` on the first session, store the returned `composition_id`, which becomes the Session Group ID.
`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`.

Store both the encounter_id and the composition_id.The composition_id identifies the shared clinical note. The encounter_id is required to create additional ambient sessions for that note.

Step 3: Seed patient context for Web SDK

Headless ambient products can start a session with only an emr_encounter_id. The Web SDK needs patient profile fields to show the patient profile page. After you create the session, use the Seed ambient session context API to include patient details:

Example request

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"
    }
  }'

Following are the required patient fields for a complete profile:

patient_id
name
dob
sex

If a headless ambient session starts with only emr_encounter_id and later opens in the Web SDK without patient details, the Web SDK may launch without a patient profile.

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 following identifiers:

The same emr_encounter_id
The same encounter_id as the previous session

That tells Suki the new ambient session belongs to the same 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, the Session Group ID).
Create returns sessionId and, for online creates, compositionId = N. Store Session Group ID G from the kSessionId you passed. compositionId is the note id. It is not the Session Group ID.
Later, the Web SDK or 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, use 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, call Get Note Content so your integration reads the latest edited text, not only the last session snapshot.

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 for Web SDK

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

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 for Web SDK

​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

​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 for Web SDK

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

Next steps