Create an Ambient Clinical Note

Quick summary

Call create when the clinician starts Ambient. Store ambient_session_id for this recording and note_id from the response. Pass emr_encounter_id for cross-modality notes. For re-ambient, reuse encounter_id when you sent it, or use the returned note_id. Do not send patient, sections, or note style on create.

Last updated:September 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.
note_id identifies the note linked to that session. Use it with 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. Pass emr_encounter_id when the note must work across modalities. For re-ambient, reuse encounter_id when you sent it. If the first create omitted encounter_id, pass the returned note_id as the encounter_id field value. For Mobile SDK and Web SDK field names, see Interoperable identifiers.

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, note_id, or other Suki identifier manually.

Create the session

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

ambient_session_id
note_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 note_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 or non-UUID value, at most 36 characters, 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

If the first create sent encounter_id, reuse that same encounter_id on later creates (up to 255 characters).
If the first create did not send encounter_id, pass the returned note_id as the encounter_id field value for re-ambient. Create has no separate note_id request field.
Store encounter_id yourself when you send it. Create does not return encounter_id.
Keep the same note_id for note-level APIs. 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 encounter_id when you sent it. If the first create omitted encounter_id, pass the returned note_id as the encounter_id field value. Keep the shared note_id for note-level APIs:

Diagram: one encounter visit branches into ambient session 1 and ambient session 2, which both connect to one shared note with 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 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 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 when you sent it, or pass the returned `note_id` as the `encounter_id` field value if the first create omitted `encounter_id`. Keep the existing `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 id (UUID or non-UUID, at most 36 characters). 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`	Use for re-ambient when you stored it on the first create. The Web SDK does not need `encounter_id` to open the shared note

Store note_id from the create response. Use it 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
`note_id`	Create response	Use with note content, note context, and note structured data, and store it for re-ambient.
`emr_encounter_id`	Your EHR visit id (UUID or non-UUID, at most 36 characters; you send on create)	Required for cross-modality interoperable notes
`encounter_id`	You send on create for re-ambient	Reuse it on later creates when you sent it

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 or non-UUID, at most 36 characters, when interoperable
      encounter_id: encounterId, // optional; reuse later for re-ambient
    }),
  }
);

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

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

// Keep these in your visit state for context, stream, end, and note APIs.
storeAmbientIds({
  ambientSessionId: ambient_session_id,
  noteId: 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 or non-UUID, at most 36 characters, when interoperable
        "encounter_id": encounter_id,  # optional; reuse later for re-ambient
    },
)
response.raise_for_status()
body = response.json()

ambient_session_id = body["ambient_session_id"]
note_id = body["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 note_id with the active visit. Use 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

References

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