Create an Ambient Clinical Note

Quick summary

Call create when the clinician starts Ambient. Store ambient_session_id for this recording and composition_id as note_id. Pass emr_encounter_id for cross-modality notes and reuse encounter_id for re-ambient. Do not send patient, sections, or note style on create.

Last updated:August 2026

Ambient sessions are recordings of patient-provider conversations that produce a clinical note. Clinicians use ambient sessions to automatically document patient history, physical exams, and clinical observations. Use the Create ambient session API to start an ambient session recording for a patient visit. Call this API when the clinician chooses Start Ambient in your application. Suki creates the ambient session and returns the identifiers you need for the rest of the workflow:

ambient_session_id identifies the recording session.
composition_id identifies the note linked to that session. Pass it as note_id to note-level Ambient APIs.

Your application should keep these identifiers with the current visit so it can use them when it streams audio, ends the session, checks processing status, and retrieves the note.

These patterns apply when you build your own ambient experience with the Ambient APIs or the Headless Web SDK. The headed Web SDK already provides the Ambient UI, so you do not need to build this Start Ambient experience yourself.

Session vs visit

An ambient session is a recording. A patient encounter is the visit. One encounter can have multiple ambient sessions. For example, a clinician might start recording, end the session, and then start another session later during the same visit.

Ending an ambient session only ends that recording. It does not end the patient encounter.

This distinction matters if your product supports restarting workflow, recording additional parts of a visit, or continuing the workflow on another supported device or modality.

Build the Start Ambient flow

Your Start ambient flow should connect the clinician’s action to the correct patient encounter and then continue into the rest of the Ambient workflow.

Start from the patient encounter

Place your Start Ambient control in the encounter or chart where the clinician is already working.

When the clinician taps Start Ambient, they should not need to enter an ambient_session_id, composition_id, or other Suki identifier manually.

Create the session

When the clinician starts recording, call Create ambient session. The response provides the identifiers your application needs for the session:

ambient_session_id
composition_id

Store these identifiers with the active visit state. Your application can then use them throughout the rest of the Ambient workflow.

Continue the recording flow

After create, continue the Start ambient path: seed context, stream audio, end the session, then poll status and retrieve the note. The create call is the start of the recording workflow, not the entire ambient integration. See What to do right after create for the full sequence after a successful create response.

Decide which create fields to send

You do not need to send every field on create. Send only what your product needs.

If You Only Use Ambient APIs on One Client

Call create with an empty body. Suki returns ambient_session_id and composition_id. Store both, then continue with context, streaming, and End.
You do not need emr_encounter_id or encounter_id for this path.

If the Note Must Work Across Web, Mobile, and APIs

Pass emr_encounter_id on create. Use a UUID for your EHR visit.
Without emr_encounter_id, Suki still creates the ambient session, but the note cannot move across modalities.
See Use interoperable ambient notes across modalities.

If the Clinician May Record Again on the Same Note

Pass the same encounter_id every time you create for that note (up to 255 characters). Store it yourself. Create does not return encounter_id.
Keep the same composition_id as note_id. Each new recording gets a new ambient_session_id, but it stays on the same note.

What Not to Send on Create

Do not send patient details, note sections, diagnoses, or note style on create.
Send visit context after create with Seed ambient session context.
Send note style (Concise / Balanced / Detailed) with Note Personalization.
Multilingual is on by default for Ambient APIs and Web SDK. Do not send the deprecated multilingual field.

Supporting multiple sessions

If your product allows a clinician to record more than once during a visit, treat each recording as a separate ambient session while keeping it associated with the same encounter. Do not treat ambient_session_id as the identifier for the patient visit. It identifies the individual ambient session recording. When those recordings continue the same clinical note (re-ambient), reuse the same encounter_id and keep the shared composition_id / note_id:

Diagram: one encounter visit branches into ambient session 1 and ambient session 2, which both connect to one shared note with composition_id / note_id.

Multiple notes on the same EHR visit

An EHR visit can have multiple clinical notes. In this case, each note has its own composition_id / note_id, while the notes are associated with the same EHR visit through emr_encounter_id. emr_encounter_id is the ID of the EHR visit. Your application provides this value when you create the ambient session. Suki does not generate it. When you use the same emr_encounter_id for interoperable Ambient workflows:

Suki associates the ambient session work with that EHR visit.
The visit can have multiple ambient notes over time.
Each note has its own composition_id / note_id.

To retrieve all notes associated with an EHR visit, call List encounter notes with the same emr_encounter_id you used when creating the session. The response returns the notes associated with that visit. Use a returned note id as the note_id for note-level APIs.

Use case	ID to use	Result
Record another ambient session for the same note	Same `encounter_id` on create. Keep the existing `composition_id` as `note_id` for note-level APIs	Adds another ambient session to the same note
Work with the same EHR visit and retrieve its notes	`emr_encounter_id`	Accesses the EHR visit and its associated notes

For how to retrieve by session, note, or EMR encounter, see Work with shared notes.

Cross-modality workflows

Cross-modality ambient session means clinicians can work on the same clinical note across more than one Suki ambient session product. For example:

Start ambient session on the Mobile SDK or Ambient APIs during the visit.
Open the same note later in the Web SDK to review and edit.
Retrieve the latest note text through the Note-level APIs.

To enable this, pass emr_encounter_id when you create the ambient session. That value is your EHR visit UUID. Your application provides it. Suki does not generate it.

Without emr_encounter_id, Suki still creates an ambient session, but the note is not interoperable across modalities.

What to send on create

Field	When to send it
`emr_encounter_id`	Required for interoperable notes across Ambient APIs, Mobile SDK, and Web SDK
`encounter_id`	Required when Mobile SDK or Ambient APIs re-ambient the same note. Reuse the same value every time. The Web SDK does not need `encounter_id` to open the shared note

Store composition_id from the create response. Pass it as note_id when you call note-level APIs such as get note content.

Interoperability does not mean the products share the same audio file. Each product captures its own ambient session. Suki uses that session to update the shared clinical note. So when a clinician starts on Mobile and later opens Web SDK, they see the same note content, not a copy of the Mobile audio stream. The shared note is what moves across modalities. For the full interoperable flow, see Use interoperable ambient notes across modalities.

Which IDs to store

Your UI does not need to show these IDs. Your backend and visit state do.

ID	Where it comes from	How you use it
`ambient_session_id`	Create response (or you pass one on create)	Context, `/ws/stream`, End, status, session content
`composition_id`	Create response	Pass as `note_id` to note content, note context, and note structured data
`emr_encounter_id`	Your EHR visit UUID (you send on create)	Required for cross-modality interoperable notes
`encounter_id`	You send on create for re-ambient	Reuse the same value for every re-ambient on that note

Do not create sessions for the same emr_encounter_id at the same time. Wait at least 1 second between create requests for that encounter. Faster back-to-back creates can return a conflict. See Resolve session conflict.

Plan for recordings of about one minute or longer. Short or empty audio often finishes as skipped after End. Design Start so clinicians understand they are beginning a real visit capture, not a one-second tap. See Check note status.

Example: create, then store IDs for the visit

Create Ambient Session API

TypeScript
Python

const response = await fetch(
  "https://sdp.suki.ai/api/v1/ambient/session/create",
  {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      sdp_suki_token: sdpSukiToken,
      sdp_provider_id: sdpProviderId,
    },
    body: JSON.stringify({
      // Optional: ambient_session_id
      emr_encounter_id: emrEncounterId, // UUID when interoperable
      encounter_id: encounterId, // required for re-ambient; reuse later
    }),
  }
);

if (!response.ok) {
  throw new Error(`Create ambient session failed: ${response.status}`);
}

const { ambient_session_id, composition_id } = await response.json();

// Keep these in your visit state for context, stream, end, and note APIs.
storeAmbientIds({
  ambientSessionId: ambient_session_id,
  noteId: composition_id, // use as note_id
});

import requests

response = requests.post(
    "https://sdp.suki.ai/api/v1/ambient/session/create",
    headers={
        "Content-Type": "application/json",
        "sdp_suki_token": sdp_suki_token,
        "sdp_provider_id": sdp_provider_id,
    },
    json={
        # Optional: "ambient_session_id"
        "emr_encounter_id": emr_encounter_id,  # UUID when interoperable
        "encounter_id": encounter_id,  # required for re-ambient; reuse later
    },
)
response.raise_for_status()
body = response.json()

ambient_session_id = body["ambient_session_id"]
composition_id = body["composition_id"]  # use as note_id

What to do right after create

Create starts the ambient session. It does not finish the entire workflow. After a successful create response, keep the clinician on the Start ambient path. Store the IDs, set context, stream audio, then end the session and retrieve the note when it is ready.

Store the IDs from the Response

Save ambient_session_id and composition_id with the active visit. Pass composition_id as note_id for note-level APIs later. You need these IDs for context, streaming, End, status, and note retrieval.

Seed Session Context

Send patient, sections, and other visit fields before End. See Seed ambient session context.If more fields arrive during the visit, use Add information during a visit.

Open the WebSocket and Stream Audio

Open /ws/stream and capture audio while the clinician is recording. See Stream ambient audio in your product.

End, Poll Status, Then Retrieve the Note

When the clinician stops, send RU9G, call End, and poll status. Open the note only when status is completed.See Complete an ambient visit, Check note status, and Get the generated clinical note.

Next steps

Create ambient session API - Request and response fields. Seed ambient session context - Set visit context after create. Stream ambient audio in your product - Open /ws/stream after create. Use interoperable ambient notes across modalities - Shared notes across products.

Get Started

Concepts & Feature Guides

Resources

FAQs & Support

Create an Ambient Clinical Note

Session vs visit

Build the Start Ambient flow

Start from the patient encounter

Create the session

Continue the recording flow

Decide which create fields to send

Supporting multiple sessions

Multiple notes on the same EHR visit

Cross-modality workflows

What to send on create

Which IDs to store

Example: create, then store IDs for the visit

What to do right after create

Next steps

​Session vs visit

​Build the Start Ambient flow

​Start from the patient encounter

​Create the session

​Continue the recording flow

​Decide which create fields to send

​Supporting multiple sessions

​Multiple notes on the same EHR visit

​Cross-modality workflows

​What to send on create

​Which IDs to store

​Example: create, then store IDs for the visit

​What to do right after create

​Next steps

Session vs visit

Build the Start Ambient flow

Start from the patient encounter

Create the session

Continue the recording flow

Decide which create fields to send

Supporting multiple sessions

Multiple notes on the same EHR visit

Cross-modality workflows

What to send on create

Which IDs to store

Example: create, then store IDs for the visit

What to do right after create

Next steps