> ## Documentation Index
> Fetch the complete documentation index at: https://developer.suki.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Use Interoperable Ambient Notes Across Modalities

> Learn how to create, continue, and retrieve interoperable Ambient notes across Suki products

<div className="quick-summary-wrapper">
  <div className="quick-summary-header">
    <span className="quick-summary-icon" aria-hidden="true" />

    <span className="quick-summary-title">Quick summary</span>
  </div>

  <div className="quick-summary-content">
    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.
  </div>

  <div className="quick-summary-footer">
    <span className="quick-summary-footer-icon" aria-hidden="true" />

    <span className="quick-summary-footer-text">Last updated:</span>
    <span className="quick-summary-footer-date">July 2026</span>
  </div>
</div>

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.

<Steps>
  <Step title="Create an Ambient Session">
    Create an ambient session with an `emr_encounter_id`.
  </Step>

  <Step title="Seed Patient Context">
    Seed patient context when the Web SDK may open the note later.
  </Step>

  <Step title="Capture Audio">
    Capture audio on one ambient modality.
  </Step>

  <Step title="Continue or Re-Ambient">
    Continue or re-ambient on another ambient product using the same `emr_encounter_id` and `encounter_id`.
  </Step>

  <Step title="Retrieve the Shared Clinical Note">
    Retrieve the shared clinical note content and structured data.
  </Step>
</Steps>

## Example flow

```mermaid actions={false} theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
%%{init: {'theme':'base', 'themeVariables': { 'primaryColor':'#FFF394','primaryTextColor':'#111827','primaryBorderColor':'#FFE148','lineColor':'#FFE148','secondaryColor':'#FFF394','tertiaryColor':'#FFFADE','mainBkg':'#FFF394','secondBkg':'#FFFADE','tertiaryBorderColor':'#FFE148','border1':'#FFE148','border2':'#FFE148','arrowheadColor':'#FFE148','fontFamily':'Inter, system-ui, sans-serif','fontSize':'14px','nodeBorder':'#FFE148','edgeLabelBackground':'#FFE148','clusterBkg':'#FFFADE','clusterBorder':'#FFE148','defaultLinkColor':'#FFE148','titleColor':'#111827','nodeTextColor':'#111827'}}}%%
flowchart LR
    A[Start Ambient on Mobile SDK<br/>or Ambient APIs during the visit] --> B[Open the same clinical note<br/>in the Web SDK to review and edit]
    B --> C[Call Get Note Content from<br/>your backend for the latest note text]

    style A fill:#FFF394,stroke:#FFE148,stroke-width:2px,color:#111827
    style B fill:#FFF394,stroke:#FFE148,stroke-width:2px,color:#111827
    style C fill:#FFF394,stroke:#FFE148,stroke-width:2px,color:#111827
```

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

<div className="doc-guide-btn-row">
  <a href="/api-reference/ambient-content/note-content" className="doc-guide-btn">
    Get Note Content API
  </a>
</div>

## Step 1: Create an interoperable Ambient session

Create a new session with the [Create ambient session API](/api-reference/ambient-sessions/create) 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

```bash theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
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 JSON theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
{
  "ambient_session_id": "<ambient_session_id>",
  "composition_id": "<composition_id>" // you will use this as note_id in the note-level Ambient APIs
}
```

<Warning>
  If you omit **`emr_encounter_id`**, Suki still creates an ambient session, but the note is **not interoperable** across Suki products.
</Warning>

## 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`.                                                                                                                                             |

<Note>
  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.
</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](/api-reference/ambient-sessions/context) to include patient details:

### Example request

```bash theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
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`

<Note>
  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.
</Note>

You can update context later with the [Update ambient session context API](/api-reference/ambient-sessions/update-context).

## Step 4: Capture audio on the first modality

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

* [Ambient APIs](/api-reference/ambient-sessions/audio-stream)
* [Mobile SDK](/mobile-sdk/ambient-guides/ambient-interoperability)
* [Headless Web SDK](/headless-web-sdk/guides/hooks/ambient-hook)
* [Web SDK](/web-sdk/guides/ambient-implementation)

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:

1. The same `emr_encounter_id`
2. The same `encounter_id` as the previous session

That tells Suki the new ambient session belongs to the same clinical note.

<Tip>
  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.
</Tip>

### Scenario example

1. Mobile SDK starts ambient with `kEmrEncounterId = A` (maps to `emr_encounter_id`) and `kSessionId = G` (maps to `encounter_id`, the Session Group ID).
2. 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.
3. Later, the Web SDK or Ambient APIs create another session with `emr_encounter_id = A` and `encounter_id = G`.
4. Both ambient sessions belong to clinical note `N`.

```mermaid actions={false} theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
%%{init: {'theme':'base', 'themeVariables': { 'primaryColor':'#FFF394','primaryTextColor':'#111827','primaryBorderColor':'#FFE148','lineColor':'#FFE148','secondaryColor':'#FFF394','tertiaryColor':'#FFFADE','mainBkg':'#FFF394','secondBkg':'#FFFADE','tertiaryBorderColor':'#FFE148','border1':'#FFE148','border2':'#FFE148','arrowheadColor':'#FFE148','fontFamily':'Inter, system-ui, sans-serif','fontSize':'14px','nodeBorder':'#FFE148','edgeLabelBackground':'#FFE148','clusterBkg':'#FFFADE','clusterBorder':'#FFE148','defaultLinkColor':'#FFE148','titleColor':'#111827','nodeTextColor':'#111827'}}}%%
flowchart TB
    IDs["Shared identifiers<br/>emr_encounter_id = A<br/>encounter_id = G"]
    IDs --> M[Mobile SDK<br/>Ambient session 1]
    IDs --> W[Web SDK or Ambient APIs<br/>Ambient session 2]
    M --> N["Shared clinical note<br/>composition_id = N"]
    W --> N

    style IDs fill:#FFFADE,stroke:#FFE148,stroke-width:2px,color:#111827
    style M fill:#FFF394,stroke:#FFE148,stroke-width:2px,color:#111827
    style W fill:#FFF394,stroke:#FFE148,stroke-width:2px,color:#111827
    style N fill:#FFF394,stroke:#FFE148,stroke-width:2px,color:#111827
```

## 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                                     | <a href="/api-reference/ambient-content/list-encounter-notes" className="doc-guide-btn">List Encounter Notes</a>     |
| Get the latest note section content, including Web SDK edits             | <a href="/api-reference/ambient-content/note-content" className="doc-guide-btn">Get Note Content</a>                 |
| Get visit context aggregated across ambient sessions in the note         | <a href="/api-reference/ambient-content/note-context" className="doc-guide-btn">Get Note Context</a>                 |
| Get diagnoses and orders accumulated across ambient sessions in the note | <a href="/api-reference/ambient-content/note-structured-data" className="doc-guide-btn">Get Note Structured Data</a> |

### 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                             | <a href="/api-reference/ambient-content/content" className="doc-guide-btn">Session Content</a>                             | Clinical note sections generated for the specified `ambient_session_id` only.                                   |
| The complete shared clinical note, including clinician edits                | <a href="/api-reference/ambient-content/note-content" className="doc-guide-btn">Get Note Content</a>                       | 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                     | <a href="/api-reference/ambient-content/structured-data" className="doc-guide-btn">Session Structured Data</a>             | Diagnoses, orders, and other structured data for the specified `ambient_session_id` only.                       |
| Structured data accumulated across all sessions in the shared clinical note | <a href="/api-reference/ambient-content/note-structured-data" className="doc-guide-btn">Get Note Structured Data</a>       | Combined diagnoses, orders, and other structured data for the entire clinical note.                             |
| The latest structured data for an encounter                                 | <a href="/api-reference/ambient-content/encounter-structured-data" className="doc-guide-btn">Encounter Structured Data</a> | 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                         | <a href="/api-reference/ambient-content/list-encounter-notes" className="doc-guide-btn">List Encounter Notes</a>           | The note IDs and current status of every clinical note associated with the specified `emr_encounter_id`.        |

<Tip>
  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.
</Tip>

## Next steps

<Icon icon="file-lines" iconType="solid" /> Refer to [Best practices and FAQs](/documentation/how-to/ambient-clinical-notes/ambient-interoperability-faqs) for conflict handling, offline behavior, and common questions.

<Icon icon="file-lines" iconType="solid" /> Refer to [Interoperable identifiers](/documentation/concepts/ambient-clinical-notes/interoperable-identifiers) for identifier rules and Web SDK naming.

<Icon icon="file-lines" iconType="solid" /> Refer to [Create ambient session](/api-reference/ambient-sessions/create) for the request and response fields used by interoperable ambient sessions.

<Icon icon="file-lines" iconType="solid" /> Refer to [Ambient interoperability](/documentation/concepts/ambient-clinical-notes/ambient-interoperability) for an overview of how ambient products share the same clinical note.