Create an Ambient Clinical Note

Learn how to create an ambient session from your product UI, store session and note IDs, and choose interoperable create fields

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.

Prerequisites

• A valid Suki Token for Ambient API requests. See Partner authentication.
• For cross-modality notes, an emr_encounter_id you can send on create. See Interoperable identifiers.

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:

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

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,
});

Python

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 successfully creating a session

Creating a session starts the ambient session and returns the identifiers you need for the rest of the workflow. 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.

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

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

3. Open the WebSocket and Stream Audio

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

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

Troubleshooting

Create usually fails when the request carries visit fields that belong on context, hits a concurrent session conflict, or your app stores the wrong ID for later calls.

Create Returns a Conflict for the Same Encounter

Only one ambient session can be active for an emr_encounter_id at a time. Wait at least 1 second before creating again for that encounter. On Mobile SDK, resolve the remote session conflict, then retry. See Resolve session conflict.

Patient, Sections, or Note Style Rejected on Create

Create starts the recording only. Do not send patient demographics, LOINC sections, diagnoses, verbosity, or section_format on create. Seed those with context after create, and set note style through personalization. Do not send the deprecated multilingual field either.

Note Does Not Work Across Products

Pass emr_encounter_id on create when the note must be interoperable. Without it, Suki still creates the session, but the note is not shared across modalities.

Wrong ID Stored for Later Calls

Store ambient_session_id for session APIs (stream, end, status, session content) and note_id for note-level APIs. Do not treat ambient_session_id as the patient visit ID.

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.