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

# Ambient Clinical Documentation

> Learn how Suki generates structured clinical notes from patient-provider conversations. Align on workflow decisions, choose capture and note strategy, pick an Ambient product, then design review and EHR handoff

<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">
    Ambient documentation automatically creates clinical notes from patient-provider conversations. Instead of typing notes during or after a visit, providers can focus entirely on the patient while Suki listens, transcribes, and organizes the conversation into structured clinical documentation.
  </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>

Ambient documentation turns a patient-provider conversation into a <Tooltip tip="The structured medical documentation produced for a patient encounter. In Suki, ambient note generation organizes content into LOINC-coded sections so partners can review, edit, and submit notes into an EHR-ready workflow." cta="View in Glossary" href="/Glossary/c">clinical note</Tooltip>. Your integration creates a session, sends encounter audio and context, retrieves the generated output, and places the note in a review and EHR handoff workflow.

You control where capture starts, how recording state appears, where the provider reviews the result, and when approved documentation reaches the EHR. Choose an integration product based on how much of that experience you want Suki to provide.

When you use Ambient documentation, it helps clinicians to:

* Focus entirely on the patient while Suki listens, transcribes, and organizes the conversation into structured clinical documentation.
* Review the generated note while the visit context is still fresh.
* Edit the note, or re-ambient and merge the changes.
* Approve or submit the note to the EHR.

**What you build for Ambient documentation to work**

* Create an ambient session for the patient encounter.
* Stream the patient-provider conversation audio to Suki to be transcribed and organized into a clinical note.
* Retrieve the generated note (and optionally the transcript or structured data).
* Let the provider review, edit, and submit the note into the EHR workflow.

## Choose your path to build Ambient documentation

Pick one or more of the following products that matches how much UI and session control you want Suki to own, then open the matching quickstart for each product.

<CardGroup cols={2}>
  <Card title="Ambient APIs" icon="code">
    **If you need:** backend-owned session, stream, and note retrieval.

    Your application owns session controls, audio streaming, status handling, note review, and EHR handoff.

    <div style={{marginTop: '1rem'}}>
      <a href="/api-reference/quickstart" className="learning-path-button">Ambient API Quickstart</a>
    </div>
  </Card>

  <Card title="Web SDK" icon="browser">
    **If you need:** browser capture and review UI from Suki.

    Suki provides the capture and review UI. Your application supplies encounter context and handles submitted notes.

    <div style={{marginTop: '1rem'}}>
      <a href="/web-sdk/quickstart" className="learning-path-button">Web SDK Quickstart</a>
    </div>
  </Card>

  <Card title="Mobile SDK" icon="mobile">
    **If you need:** native iOS capture.

    Capture ambient sessions in an iOS application, then continue or retrieve the note through another ambient product when needed.

    <div style={{marginTop: '1rem'}}>
      <a href="/mobile-sdk/installation" className="learning-path-button">Mobile SDK Installation</a>
    </div>
  </Card>

  <Card title="Headless Web SDK" icon="react">
    **If you need:** custom React UI with ambient hooks.

    Your React application owns the interface and uses SDK hooks for authentication, session creation, and recording controls.

    <div style={{marginTop: '1rem'}}>
      <a href="/headless-web-sdk/quickstart" className="learning-path-button">Headless Web SDK Quickstart</a>
    </div>
  </Card>
</CardGroup>

<Callout title="Updates" color="orange" icon="info-circle">
  Ambient workflows are interoperable. You can start, continue, or review the same clinical note across Ambient APIs, Web SDK, and Mobile SDK. Refer to [Ambient interoperability](/documentation/concepts/ambient-clinical-notes/ambient-interoperability) for more information.
</Callout>

<Tip>
  Do not have credentials yet? Complete the following steps:

  * Complete [Partner onboarding](/documentation/get-started/partner-onboarding)
  * Then [Partner authentication](/documentation/how-to/partner-authentication) to get an `sdp_suki_token`
  * Staging base URL for API examples: `https://sdp.suki-stage.com` or ask your Suki representative for the staging base URL.
</Tip>

### Verify your first Ambient workflow

Before you design the full production workflow, confirm that your staging integration can complete the core ambient path:

* Authenticate successfully and use the returned `sdp_suki_token` in follow-up requests.
* Create an ambient session and store the returned session identifier.
* Capture or stream encounter audio through your chosen product: Ambient APIs, Web SDK, Mobile SDK, or Headless Web SDK.
* End the session and confirm that Suki starts processing the encounter.
* Retrieve generated note content, or confirm that the note appears in the SDK review experience.

After this path works end to end, continue with workflow design, note quality settings, and rollout measurement.

## How Ambient documentation works

```mermaid actions={false} theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
flowchart LR
    A[Start Ambient<br/>for the visit] --> B[Stream encounter<br/>audio to Suki]
    B --> C[End session and<br/>generate note]
    C --> D[Retrieve structured<br/>clinical note]
    D --> E[Provider reviews<br/>and edits]
    E --> F[Approve or submit<br/>to EHR]

    style A fill:#FFF394,stroke:#333,color:#000
    style B fill:#FFF394,stroke:#333,color:#000
    style C fill:#FFF394,stroke:#333,color:#000
    style D fill:#FFF394,stroke:#333,color:#000
    style E fill:#FFF394,stroke:#333,color:#000
    style F fill:#FFF394,stroke:#333,color:#000
```

<Steps>
  <Step title="Create Session">
    Start an <Tooltip tip="A single, time-bound instance of an ambient recording for a specific patient encounter that captures clinical conversations." cta="View in Glossary" href="/Glossary/a">ambient session</Tooltip> for the visit. Provide patient details, note sections, and <Tooltip tip="A healthcare professional such as a physician, APP, or nurse who documents care. In Suki integrations, provider identity ties sessions, preferences, and generated notes to the correct clinician." cta="View in Glossary" href="/Glossary/p">provider</Tooltip> information. Suki returns a session ID.

    <Warning>
      Sessions should be at least 1 minute long. Very short sessions may be skipped.
    </Warning>
  </Step>

  <Step title="Record Conversation">
    Stream audio while the visit runs. Suki converts speech to text in real time.
  </Step>

  <Step title="AI Processing">
    After the session ends, Suki analyzes the <Tooltip tip="The text version of recorded audio from clinical conversations, generated by automatic speech recognition." cta="View in Glossary" href="/Glossary/t">transcript</Tooltip>, extracts clinical content, and organizes it into the sections you requested.
  </Step>

  <Step title="Get Generated Clinical Note">
    Retrieve the note with LOINC-coded sections, optional <Tooltip tip="Organized medical information extracted from clinical conversations, formatted for integration with EHR systems." cta="View in Glossary" href="/Glossary/s">structured data</Tooltip>, and the full transcript when you need it. Place it in your review and EHR handoff flow.
  </Step>
</Steps>

## Decide before you build your workflow

Before you pick an Ambient API or SDK path for production, align on a few product decisions. Agree on the clinical use case, when the note is generated, whether you also need Dictation, where encounter context comes from, where notes are written back, and how clinicians review the result. Those choices shape UX, timeline, and which Suki products you combine.

Use the following sections to align your team.

<AccordionGroup>
  <Accordion title="Define Your Clinical Use Case" icon="laptop-medical">
    Be clear about **who** ambient is for and **what** problem it solves. Examples include primary care notes, specialty consult documentation, or a high-throughput urgent care workflow.

    The note shape depends on that use case. Choose the [LOINC note sections](/documentation/concepts/ambient-clinical-notes/note-sections) you need, pass the right [specialty](/documentation/concepts/ambient-clinical-notes/specialties), and enable [Problem-Based Charting](/api-reference/capabilities/problem-based-charting), [personalization](/api-reference/capabilities/personalization), or [medication orders](/documentation/concepts/ambient-clinical-notes/medication-orders) only when the pilot needs them.

    Start with one narrow use case. A focused first workflow is easier to pilot, easier to measure, and builds provider trust faster than a broad launch.
  </Accordion>

  <Accordion title="Decide When the Note Is Generated" icon="timer">
    With Suki Ambient, you **capture audio during the visit** and **generate the clinical note after the session ends**. The flow is create session, stream audio, end session, then retrieve the structured note for review.

    Providers review the finished note when processing completes. They do not edit a live note that updates continuously during the visit.

    Show clear recording start and stop state. Handle short or silent sessions that may return `skipped`. Decide how you show processing status in your UI. If the network drops during capture, use offline guidance for [Web SDK](/web-sdk/guides/ambient-offline-mode), [Headless Web SDK](/headless-web-sdk/guides/offline-mode), and [Mobile SDK](/mobile-sdk/ambient-guides/offline-mode).
  </Accordion>

  <Accordion title="Decide If You Also Need Dictation" icon="microphone">
    Ambient turns the visit conversation into a structured clinical note. Some specialties still need classic speech-to-text into a single chart field when the provider wants exact wording.

    Suki offers Ambient products and separate [Dictation](/documentation/concepts/dictation/dictation) products (Dictation APIs and Dictation SDK). Decide early whether your app supports Ambient only, or Ambient plus Dictation.

    Make the choice obvious in the UI. Providers should know when to run an ambient session for the visit and when to dictate into a field.
  </Accordion>

  <Accordion title="Identify Your Integration Surface" icon="display">
    Ambient works best inside the workflows clinicians already use. Support those workflows. Do not invent a separate charting process.

    Decide what you **pull in** as session context, such as patient and provider details, visit type, or appointment reason. Decide where you **write back** results, such as an EHR note, structured diagnoses and orders, or a [partner webhook](/documentation/webhook/overview) on your server.

    Also choose integration depth:

    * **Deep embedding:** Capture and review inside the browser with Web SDK, or build a custom UI with Headless Web SDK or Ambient APIs.
    * **API write-back:** Your backend retrieves note content, structured data, or webhook payloads and writes them into the EHR.
    * **Lightweight handoff:** Provider-assisted copy or export while you pilot, then deepen write-back later.

    Broader scope means more build time. For shared notes across clients, plan [Ambient interoperability](/documentation/concepts/ambient-clinical-notes/ambient-interoperability). For remote visits in the browser, see [Web SDK telehealth](/web-sdk/guides/telehealth).
  </Accordion>

  <Accordion title="Plan Review and Edit Controls" icon="user-edit">
    Clinicians remain the final authority on documentation. Define how providers review the generated note, edit sections, and approve or submit the final chart entry.

    Decide:

    * Whether review happens in the **Web SDK** hosted note UI, or in **your EHR or custom UI** after Ambient APIs, Headless Web SDK, or Mobile SDK return content.
    * How providers correct output: edit the note, re-ambient and merge, or use [Dictation](/documentation/concepts/dictation/dictation) for exact wording.
    * Whether you need session [recordings](/api-reference/ambient-content/recording) so providers can listen back in a partner-built review flow.
    * Whether you collect [user feedback](/api-reference/user-feedback) on generated content.

    Clear review and approval steps build trust and make edit-rate measurement useful.
  </Accordion>
</AccordionGroup>

## Design the clinician workflow

After those decisions are clear, turn them into a visit workflow your team can build. One visit can use different Suki products for capture and review. Use this table to lock the answers.

| Question                                          | Example answer                                        | Why it matters                                                                                                                                                                                     |
| :------------------------------------------------ | :---------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Is this in-person, virtual, or both?              | Both                                                  | In-person visits use the device microphone. Virtual visits may need browser tab or system audio. See [Web SDK telehealth](/web-sdk/guides/telehealth).                                             |
| Is this desktop, mobile, or both?                 | Both                                                  | Providers may capture on mobile and review on desktop. Plan for [interoperability](/documentation/concepts/ambient-clinical-notes/ambient-interoperability) when the same encounter spans clients. |
| When does ambient start and stop?                 | Start at visit begin, end when the encounter finishes | Providers need clear recording state so they trust what was captured.                                                                                                                              |
| How should providers review the note?             | In your EHR or Web SDK UI after generation            | Providers should edit and approve before documentation is final.                                                                                                                                   |
| How should providers correct output?              | Edit the note, or re-ambient and merge                | Decide whether corrections happen in the note UI, another ambient session, or [Dictation](/documentation/concepts/dictation/dictation) for exact wording.                                          |
| How should providers approve final documentation? | Sign or submit after review                           | Your application should make the final documentation state explicit.                                                                                                                               |

Across products, the path stays the same: start ambient for the visit, stream encounter audio, end the session, retrieve the structured note, then review and submit to the EHR. See [How Ambient documentation works](#how-ambient-documentation-works).

## How to implement Ambient documentation

Next, lock four implementation choices. They decide which Ambient product you use, what context you send, and how notes reach the EHR.

### 1. Map the end-to-end visit workflow

Walk the visit from open chart to signed note. For each step, name who owns it: your app, Suki hosted UI, or your backend.

Typical stages:

1. Open the encounter and load patient and visit context.
2. Start ambient recording and show clear recording state.
3. End the session when the conversation finishes.
4. Wait for processing, then open the generated note.
5. Let the provider edit, re-ambient if needed, and approve.
6. Write the approved note and any structured data into the EHR.

If capture and review happen on different devices, pass a shared `emr_encounter_id`. Refer to [Ambient interoperability](/documentation/concepts/ambient-clinical-notes/ambient-interoperability) and [Use ambient across products](/documentation/how-to/ambient-clinical-notes/use-ambient-across-modalities).

### 2. Choose your audio capture strategy

Note quality depends on audio quality. Pick the capture path that matches where the visit runs, then follow that product guide.

| Capture path           | Best for                                                                        | What you own                                               | Where to start                                                                           |
| :--------------------- | :------------------------------------------------------------------------------ | :--------------------------------------------------------- | :--------------------------------------------------------------------------------------- |
| **Web SDK**            | Web EHR embeds, browser capture, hosted review                                  | Encounter context and note handoff after submit            | [Web SDK quickstart](/web-sdk/quickstart)                                                |
| **Web SDK telehealth** | Remote visits in the browser (tab or system audio)                              | Share-audio UX and visit routing                           | [Telehealth](/web-sdk/guides/telehealth)                                                 |
| **Headless Web SDK**   | Custom React capture UI                                                         | Recording controls, status, and review UI                  | [Headless Web SDK quickstart](/headless-web-sdk/quickstart)                              |
| **Mobile SDK**         | Native iOS capture, including recording while the app is minimized when enabled | iOS UX, offline upload, content retrieval                  | [Mobile SDK installation](/mobile-sdk/installation)                                      |
| **Ambient APIs**       | Backend-owned streaming from your capture stack                                 | Mic or media pipeline, WebSocket frames, session lifecycle | [Ambient audio streaming](/documentation/how-to/audio-streaming/ambient-audio-streaming) |

For Ambient APIs and custom streamers, use mono **LINEAR16 PCM** at **16 kHz**. Refer to [Audio capture best practices](/documentation/how-to/audio-streaming/audio-capture-best-practices).

#### Design for clean audio capture

Good audio drives note quality. Design the workflow so providers can:

* Confirm that recording has started and stopped
* Continue the visit without typing the note during capture
* Recover or re-ambient when a session is interrupted
* Review the generated note while visit context is still fresh

With **Ambient APIs**, **Headless Web SDK**, or **Mobile SDK**, your application owns more recording UX and status handling. With **Web SDK**, Suki owns more of the capture and review UI, and your application owns how the final note is saved in the EHR.

### 3. Choose your note and section strategy

Decide how much structure the first pilot note needs. Suki returns LOINC-coded note sections and optional structured clinical data. You configure those sections and Ambient capabilities in session context.

| Approach                     | What you configure                                                                                                                                                                                                                                                                                            | Best for                                                                                                                            |
| :--------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | :---------------------------------------------------------------------------------------------------------------------------------- |
| **Core note sections**       | A focused set of [LOINC note sections](/documentation/concepts/ambient-clinical-notes/note-sections) for the pilot specialty                                                                                                                                                                                  | Fast MVP and first staging success                                                                                                  |
| **Specialty-aligned notes**  | Specialty plus sections that match how that specialty charts                                                                                                                                                                                                                                                  | Better terminology and section fit. See [Supported medical specialties](/documentation/concepts/ambient-clinical-notes/specialties) |
| **Enhanced clinical output** | [Personalization](/api-reference/capabilities/personalization), [Problem-Based Charting](/api-reference/capabilities/problem-based-charting), [medication orders](/documentation/concepts/ambient-clinical-notes/medication-orders), and [multilingual](/api-reference/capabilities/multilingual) when needed | Deeper EHR write-back and provider preference match                                                                                 |

Start narrow. Add PBC, medication orders, or personalization after create, stream, retrieve, and review work in staging.

### 4. Pull context in and push results out

Send the right encounter context into Suki, then send approved results back into your clinical systems.

**Pull context into the session**

Seed session context before or during capture. Common inputs include:

* Patient demographics and identifiers
* Provider identity and specialty
* Visit type and encounter identifiers, including `emr_encounter_id` when you need interoperability
* Existing diagnoses or medication context when you use PBC or medication orders

**Push results after processing**

After the session completes and the provider approves the note, write results into the systems that own the chart:

* Clinical note content and LOINC sections
* Structured diagnoses and orders when enabled
* Completion and failure signals through [partner webhooks](/documentation/webhook/overview) when your backend should react without polling

Choose write-back depth for the pilot:

* **Deep embedding:** Web SDK or custom UI inside the EHR workflow
* **API write-back:** Your server retrieves content or webhook payloads and writes to the EHR
* **Lightweight handoff:** Provider-assisted copy or export while you validate note quality, then deepen write-back

## Capabilities that improve note quality

Configure these after your first successful session:

<CardGroup cols={2}>
  <Card title="Note Sections" icon="note" href="/documentation/concepts/ambient-clinical-notes/note-sections" arrow={true}>
    Choose LOINC sections so content lands in the right places and maps cleanly into your EHR.
  </Card>

  <Card title="Note Personalization" icon="sliders" href="/api-reference/capabilities/personalization" arrow={true}>
    Set verbosity and section format so notes match each provider's preferred style.
  </Card>

  <Card title="Supported Medical Specialties" icon="stethoscope" href="/documentation/concepts/ambient-clinical-notes/specialties" arrow={true}>
    Pass specialty context so terminology and note structure match how that specialty documents care.
  </Card>

  <Card title="Multilingual Support" icon="language" href="/api-reference/capabilities/multilingual" arrow={true}>
    Capture conversations in the patient's preferred language and still generate the clinical note in English.
  </Card>

  <Card title="Problem-Based Charting" icon="list-check" href="/api-reference/capabilities/problem-based-charting" arrow={true}>
    Organize notes by patient problems and return coded diagnoses for EHR workflows.
  </Card>

  <Card title="Medication Orders" icon="pills" href="/documentation/concepts/ambient-clinical-notes/medication-orders" arrow={true}>
    Turn medication discussion into structured, EHR-ready order artifacts.
  </Card>
</CardGroup>

## Measure success for Ambient

Treat measurement as something you own. Define what **better** and **worse** means for your ambient workflow, track it where the work happens (your app + EHR), and use the findings before and after you deploy the ambient workflow in production.

| Metric type           | Examples you can track                                                       | What it tells you                                                 |
| --------------------- | ---------------------------------------------------------------------------- | ----------------------------------------------------------------- |
| **Time**              | Time from visit end to signed note, documentation time per encounter         | Whether ambient reduces after-visit charting load                 |
| **Quality and trust** | Edit rate before sign, sections rewritten, provider acceptance rate          | Whether providers trust the generated note                        |
| **Rework**            | Notes rejected, returned for revision, or reopened after submit              | Whether ambient output needs too much cleanup                     |
| **Reliability**       | Session create failures, stream failures, empty or skipped sessions          | Whether the integration is stable in production                   |
| **Adoption**          | Active ambient users, sessions per provider, % of visits using ambient       | Whether clinicians are using ambient in real workflows            |
| **Business outcomes** | Throughput, coding completeness, or revenue impact your org already measures | Optional. Track only if your organization already owns those KPIs |

Start with a small set for the pilot workflow, for example time to signed note, edit rate before sign, and session failure rate.

## Next steps

<Icon icon="file-lines" iconType="solid" /> **[Ambient audio streaming](/documentation/how-to/audio-streaming/ambient-audio-streaming)** - Stream visit audio on `/ws/stream` for Ambient API integrations.

<Icon icon="file-lines" iconType="solid" /> **[Ambient API quickstart](/api-reference/quickstart)** - Authenticate, create a session, stream audio, and retrieve the note.

<Icon icon="file-lines" iconType="solid" /> **[Use ambient across products](/documentation/how-to/ambient-clinical-notes/use-ambient-across-modalities)** - Capture on one client and continue review on another.

<Icon icon="file-lines" iconType="solid" /> **[Partner authentication](/documentation/how-to/partner-authentication)** - Get an `sdp_suki_token` for API and SDK calls.

<Icon icon="file-lines" iconType="solid" /> **[Integration overview](/documentation/get-started/integration-overview)** - Compare Ambient, Form filling, and Dictation workflows.