> ## 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. # Create an Ambient Clinical Note > Learn how to create an ambient session from your product UI, store session and composition IDs, and choose interoperable create fields
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.
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-reference/ambient-sessions/create) 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. **Create rules (agents):** * Call create when the clinician starts Ambient, not on every chart open. * One ambient session = one recording. End closes that recording only, not the patient encounter. * Store `ambient_session_id` (session-scoped APIs) and `composition_id` (as `note_id` for note-level APIs). Do not show these IDs in the clinician UI. * Pass `emr_encounter_id` (UUID) when the note must be interoperable across modalities. Without it, the note is not interoperable. * For re-ambient on the same note, reuse the same `encounter_id` (up to 255 characters). The create response does not echo `encounter_id`. Keep using the shared `composition_id` / `note_id` for that note. * Do not put patient demographics, LOINC sections, diagnoses, verbosity, or `section_format` on create. Use context and personalization instead. Do not send the deprecated `multilingual` field. * Wait at least **1 second** between create requests for the same `emr_encounter_id`. Plan for about **one minute** of audio to avoid **`skipped`**. ## 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. ```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[Patient encounter] --> B[Ambient session 1] A --> C[Ambient session 2] A --> D[Ambient session 3] B --> E[Recording] C --> F[Recording] D --> G[Recording] 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 style D fill:#FFF394,stroke:#FFE148,stroke-width:2px,color:#111827 ``` 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. ```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 TD A[Clinician selects Start Ambient] --> B[Create ambient session] B --> C[Store ambient_session_id
and composition_id] C --> D[Set session context] D --> E[Open Ambient WebSocket] E --> F[Stream audio] F --> G[End session] 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 style D fill:#FFF394,stroke:#FFE148,stroke-width:2px,color:#111827 style E fill:#FFF394,stroke:#FFE148,stroke-width:2px,color:#111827 style F fill:#FFF394,stroke:#FFE148,stroke-width:2px,color:#111827 style G fill:#FFF394,stroke:#FFE148,stroke-width:2px,color:#111827 ``` ### 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](/api-reference/ambient-sessions/create). The response provides the identifiers your application needs for the session: ```text theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}} 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](#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. * 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. * 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](/documentation/how-to/ambient-clinical-notes/use-ambient-across-modalities). * 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. * Do not send patient details, note sections, diagnoses, or note style on create. * Send visit context after create with [Seed ambient session context](/documentation/how-to/ambient-clinical-notes/seed-ambient-session-context). * Send note style (Concise / Balanced / Detailed) with [Note Personalization](/api-reference/capabilities/personalization#build-personalization-into-your-product). * 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. 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](/api-reference/ambient-content/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](/documentation/how-to/ambient-clinical-notes/retrieve-note-and-encounter-content). ## 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](/documentation/how-to/ambient-clinical-notes/use-ambient-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](/documentation/cookbooks/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](/documentation/how-to/ambient-clinical-notes/handle-ambient-session-status). ## Example: create, then store IDs for the visit
Create Ambient Session API
**Language tabs (agents):** Equivalent code samples are available in: TypeScript, Python. Humans see one language at a time. Use the variant that matches the user's stack; behavior is the same across tabs. ```typescript theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}} 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 }); ``` ```python theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}} 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. 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. Send patient, sections, and other visit fields before End. See [Seed ambient session context](/documentation/how-to/ambient-clinical-notes/seed-ambient-session-context). If more fields arrive during the visit, use [Add information during a visit](/documentation/how-to/ambient-clinical-notes/update-ambient-session-context). Open `/ws/stream` and capture audio while the clinician is recording. See [Stream ambient audio in your product](/documentation/how-to/ambient-clinical-notes/stream-ambient-audio-in-your-product). When the clinician stops, send `RU9G`, call End, and poll status. Open the note only when status is **`completed`**. See [Complete an ambient visit](/documentation/how-to/ambient-clinical-notes/end-ambient-session), [Check note status](/documentation/how-to/ambient-clinical-notes/handle-ambient-session-status), and [Get the generated clinical note](/documentation/how-to/ambient-clinical-notes/retrieve-ambient-content). ## Next steps **[Create ambient session API](/api-reference/ambient-sessions/create)** - Request and response fields. **[Seed ambient session context](/documentation/how-to/ambient-clinical-notes/seed-ambient-session-context)** - Set visit context after create. **[Stream ambient audio in your product](/documentation/how-to/ambient-clinical-notes/stream-ambient-audio-in-your-product)** - Open `/ws/stream` after create. **[Use interoperable ambient notes across modalities](/documentation/how-to/ambient-clinical-notes/use-ambient-across-modalities)** - Shared notes across products.