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

# Interoperability - Best Practices & FAQs

> Learn best practices, conflict handling, offline behavior, and FAQs for Ambient interoperability

<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">
    Follow these best practices when you use interoperable ambient clinical notes across modalities: always pass an `emr_encounter_id`, space create requests for the same EMR encounter, prefer online handoffs, store the right identifiers, and use note-level APIs after Web SDK edits.
  </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 covers the practices and edge cases that matter when you build interoperable ambient workflows in production: concurrent session conflicts, offline handoffs, diagnosis and order reconciliation, current limitations, and frequently asked questions.

## Best practices

Use these practices when you design and run interoperable ambient integrations.

<AccordionGroup>
  <Accordion title="Pass an EMR Encounter ID">
    Always pass `emr_encounter_id` when the clinical note must work across ambient modalities.
  </Accordion>

  <Accordion title="Store All Key Identifiers">
    Store `emr_encounter_id`, the Session Group ID (`encounter_id`), `ambient_session_id`, and `composition_id` together in your application.
  </Accordion>

  <Accordion title="Seed Patient Context for Web SDK">
    If the note started on a headless product, seed patient context before you open the note in the Web SDK.
  </Accordion>

  <Accordion title="Choose the Right Retrieval API">
    Use note-level APIs for partner-facing retrieval after edits. Use session-level APIs when you need content from one recording only.
  </Accordion>

  <Accordion title="Space Concurrent Creates">
    Do not create sessions for the same EMR encounter at the same time. Wait at least **1 second** between create requests for that `emr_encounter_id`.
  </Accordion>

  <Accordion title="Prefer Online Handoffs">
    Prefer ending sessions online before you switch modalities so Suki receives the full audio upload.
  </Accordion>

  <Accordion title="Handle Empty Sections">
    If you pass a LOINC code and no recommendation is generated, the section can still appear with empty data.
  </Accordion>
</AccordionGroup>

## Concurrent Ambient sessions

Only one ambient session can be active for an **`emr_encounter_id`** at a time.

If your application attempts to create another ambient session for the same patient encounter while an existing session is still in progress, Suki rejects the request and returns a conflict response. This prevents multiple active sessions from writing to the same clinical note simultaneously.

The conflict response can include:

* The active **`ambient_session_id`**
* The modality that owns the active session
* How long the active session has been running

<Warning>
  - Do not create multiple ambient sessions for the same **`emr_encounter_id`** at nearly the same time. For Ambient API create calls, wait at least **1 second** before sending another **Create ambient session** request for the same encounter. Requests sent too quickly can result in a conflict response.

  - On the **Mobile SDK**, create fails with **`SukiAmbientCoreError.remoteSessionConflict(blockingSessionId:)`**. Pass **`blockingSessionId`** to **`cancelRemoteAmbientSession`** or **`endSessionRemotely`**, then retry create. Mobile SDK does not require an extra delay after the remote call succeeds. Refer to [Mobile SDK interoperability](/mobile-sdk/ambient-guides/ambient-interoperability) for more details.
</Warning>

## Offline and connectivity

Ambient interoperability works best when each ambient session can upload its audio and metadata to Suki before the next session begins.

When a clinician switches from one Suki product to another, Suki can only process the audio that has already been uploaded. If the first device loses connectivity before its recording is uploaded, any audio that did not reach Suki cannot be recovered and will not be included in the clinical note.

To minimize data loss follow these best practices:

* End the current ambient session while the **device is online**.
* Allow the session to upload successfully **before starting another ambient session** for the same patient encounter.
* Avoid switching products **while a session is still uploading** whenever possible.

<Note>
  Offline handoffs are supported, but they are a best-effort experience. Depending on when connectivity is lost, the resulting clinical note may be incomplete.
</Note>

The tabs below describe common **connectivity scenarios**, including:

* An ambient session that never uploads to Suki.
* Ending an ambient session from a different Suki product.
* Switching between products while an ambient session is still active.

<Tabs>
  <Tab title="First Session Never Uploads to Suki">
    ### Scenario 1: The first session never uploads to Suki

    If the first ambient session is created while the device is completely offline and no audio or metadata is uploaded, Suki is unaware that the session exists.

    Because no active session is registered, another Suki product can create a new ambient session for the same **`emr_encounter_id`** without receiving a conflict.

    | First session                           | Outcome                                                                              |
    | --------------------------------------- | ------------------------------------------------------------------------------------ |
    | Web SDK never connects to Suki          | Another supported ambient product can create a new session. No conflict is returned. |
    | Headless product never connects to Suki | Another supported ambient product can create a new session. No conflict is returned. |
  </Tab>

  <Tab title="Different Modality Ends Session">
    ### Scenario 2: A different modality ends the active session

    A modality can end an ambient session that was started by another modality.

    * If the original session is online, Suki processes the complete recording and generates the clinical note normally.

    * If the original session has lost connectivity, Suki can process only the audio that was uploaded before the connection was lost. Any audio that was never uploaded is not included in the clinical note.

    | Connectivity of the original session | Outcome                                                                              |
    | ------------------------------------ | ------------------------------------------------------------------------------------ |
    | Online                               | The complete recording is processed and the clinical note is generated successfully. |
    | Offline after partial upload         | Only the uploaded audio is processed. The resulting clinical note may be incomplete. |
  </Tab>

  <Tab title="Switching During Active Session">
    ### Scenario 3: Switching modalities during an active session

    Clinicians can switch from one supported ambient modality to another during the same patient encounter.
    For the best experience, end the current ambient session while it is still online before starting the next one.

    <Note>
      If connectivity is lost before the first session finishes uploading, Suki processes only the audio that has already been received.
    </Note>

    | Current session state                              | Outcome                                                                                                   |
    | -------------------------------------------------- | --------------------------------------------------------------------------------------------------------- |
    | Session ends while online                          | The full recording is processed before the next session begins. This is the recommended workflow.         |
    | Session loses connectivity before upload completes | Only uploaded audio is processed. The next session can continue, but the clinical note may be incomplete. |
  </Tab>
</Tabs>

## Diagnosis and order reconciliation behavior

When you re-ambient an interoperable clinical note, Suki reconciles diagnoses and orders differently depending on whether the new session starts on a headless or headed modality.

The tabs below describe how each modality handles prior recommendations when you add another ambient session to the same clinical note.

<Tabs>
  <Tab title="Headless Modality Re-Ambient">
    ### Scenario 1: Headless modality re-Ambient

    Headless modalities do not use prior diagnoses as ML input when you start a new ambient session for an existing clinical note.

    If the new session generates a diagnosis that already exists on the note, reconciliation keeps a single unique diagnosis by replacing the previous entry with the new one.

    | Headless re-ambient behavior             | Outcome                                                                                     |
    | ---------------------------------------- | ------------------------------------------------------------------------------------------- |
    | Prior diagnoses are not used as ML input | The new session generates diagnoses from the current recording only.                        |
    | A diagnosis already exists on the note   | Reconciliation keeps one unique diagnosis by replacing the previous entry with the new one. |
  </Tab>

  <Tab title="Headed (Web SDK) Re-Ambient">
    ### Scenario 2: Headed (Web SDK) re-Ambient

    The Web SDK includes prior recommendations when you re-ambient an existing clinical note.

    If a diagnosis is updated across ambient sessions, the latest recommendation takes priority in the shared clinical note.

    | Headed re-ambient behavior             | Outcome                                                             |
    | -------------------------------------- | ------------------------------------------------------------------- |
    | Prior recommendations are included     | The new session can build on diagnoses already present on the note. |
    | A diagnosis is updated across sessions | The latest recommendation takes priority.                           |
  </Tab>

  <Tab title="Medication Orders">
    ### Scenario 3: Medication orders

    Orders follow the same overall reconciliation process as diagnoses when you re-ambient an interoperable clinical note.

    In headed flows, order creation also depends on whether the medication code was present in the LOINC code set.

    | Order reconciliation         | Outcome                                                                                                                                                        |
    | ---------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
    | Headless modality re-ambient | Orders follow the same reconciliation approach as diagnoses for the new session output.                                                                        |
    | Headed (Web SDK) re-ambient  | Orders follow the same reconciliation approach as diagnoses, and order creation also depends on whether the medication code was present in the LOINC code set. |
  </Tab>
</Tabs>

## Interoperability limitations

Keep these current limitations in mind while you design your interoperable ambient workflows:

<Note>
  * Interoperability is **ambient-only**. Dictation and Form filling are currently out of scope.
  * **`emr_encounter_id`** must be a UUID today.
  * Without **`emr_encounter_id`**, the clinical note is **not interoperable** across modalities.
  * If you only have **`note_id`** or **`composition_id`**, you cannot re-ambient yet. You must already have the **Session Group ID** (**`encounter_id`**).
  * **Create ambient session** returns **`composition_id`**. Use that value as **`note_id`** with note-level Ambient APIs.
</Note>

## Partner type compatibility

Suki no longer uses `partner_type` to determine request origin or ambient job type for new partners.
Existing partners do not need to pass `suki_user_agent`. Backward compatibility through `partner_type` **remains supported**.

<Note>
  No action is required form your side for current integrations.
</Note>

## FAQs

<AccordionGroup>
  <Accordion title="Is Interoperability Available for Dictation or Form Filling?">
    No. Cross-modality interoperability is ambient-only in this release.
  </Accordion>

  <Accordion title="What Happens If I Omit emr_encounter_id?">
    The session and clinical note are still created, but the note is not interoperable across modalities. You cannot reliably continue or retrieve that note outside the originating modality using the EMR encounter workflow.
  </Accordion>

  <Accordion title="How Do I Re-Ambient from Another Modality?">
    Create a new ambient session with the same `emr_encounter_id`, and pass the existing Session Group ID as `encounter_id`.
  </Accordion>

  <Accordion title="Can I Re-Ambient If I Only Have note_id?">
    Not yet. You need the Session Group ID. Store it when you create the first session. An encounter lookup API for this flow is not available in this release.
  </Accordion>

  <Accordion title="Why Does Create Session Return composition_id Instead of note_id?">
    Create ambient session returns `composition_id`. Use that value as `note_id` when you call note-level Ambient APIs:

    <ul className="doc-guide-btn-list">
      <li>
        <a href="/api-reference/ambient-content/note-content" className="doc-guide-btn">
          Get Note Content
        </a>
      </li>

      <li>
        <a href="/api-reference/ambient-content/note-context" className="doc-guide-btn">
          Get Note Context
        </a>
      </li>

      <li>
        <a href="/api-reference/ambient-content/note-structured-data" className="doc-guide-btn">
          Get Note Structured Data
        </a>
      </li>
    </ul>
  </Accordion>

  <Accordion title="Does Get Note Content Include Web SDK Edits?">
    Yes. Get Note Content returns accumulated note content and, for edited sections, the latest edited section content.
  </Accordion>

  <Accordion title="Why Might Web SDK Show No Patient Profile After a Mobile or API Session?">
    Headless sessions can start with only `emr_encounter_id`. Web SDK needs patient profile fields. Seed `patient_id`, name, `dob`, and `sex` through the session Context API before opening the Web SDK.

    <div className="doc-guide-btn-row">
      <a href="/api-reference/ambient-sessions/context" className="doc-guide-btn">
        Seed ambient session Context
      </a>
    </div>
  </Accordion>

  <Accordion title="Must emr_encounter_id Be a UUID?">
    Yes today. The platform validates `emr_encounter_id` as a UUID. Support for shorter non-UUID client strings is planned for a future phase.
  </Accordion>
</AccordionGroup>

## Next steps

<Icon icon="file-lines" iconType="solid" /> Refer to [Use ambient across modalities](/documentation/how-to/ambient-clinical-notes/use-ambient-across-modalities) to create, continue, and retrieve interoperable ambient notes.

<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 [Ambient interoperability](/documentation/concepts/ambient-clinical-notes/ambient-interoperability) for an overview of how ambient products share the same clinical note.

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