> ## 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 & Dictation - Integration Decision Guide

> Compare Direct APIs, Web SDK, Headless Web SDK, and Mobile SDK to select the right integration method for your healthcare application

Suki for Partners provides different integration paths for adding Ambient clinical documentation and Dictation capabilities to your application.
Each integration path is designed for different product requirements, implementation approaches, and levels of UI ownership.

This guide explains the available integration options for Ambient and Dictation workflows and helps you select the approach that best fits your application architecture, technology stack, and user experience goals.
Use this guide to understand the tradeoffs between each integration path, including how much workflow logic, audio handling, and UI customization your team manages.

For Form filling workflows, refer to the [Form filling integration decision guide](/documentation/get-started/form-filling-integration-decision-guide).

## Integration options

### Ambient APIs

Ambient APIs are the most flexible integration option and allow you to build your own user interface and authentication flow for your application.

<CardGroup cols={2}>
  <Card title="Recommended For:" icon="server">
    * Backend systems and server integrations
    * Custom user interfaces on any stack
    * Multi-platform applications
  </Card>

  <Card title="What You Build:" icon="gear">
    * Complete user interface
    * Authentication flow
    * Audio handling and API/WebSocket usage
  </Card>
</CardGroup>

### Web SDK

The Web SDK delivers pre-built clinical UI components and handles authentication and audio processing for browser-based healthcare applications.

<CardGroup cols={2}>
  <Card title="Recommended For:" icon="cube">
    * Web-based healthcare applications
    * Browser-based EHR integrations
    * Teams that want pre-built clinical UI
  </Card>

  <Card title="What's Provided:" icon="gear">
    * Pre-built UI components
    * Authentication handling
    * Audio processing
  </Card>
</CardGroup>

### Headless Web SDK

The Headless Web SDK provides React hooks for authentication and ambient sessions while you build a fully custom interface.

<CardGroup cols={2}>
  <Card title="Recommended For:" icon="react">
    * React web applications (React 18+)
    * Custom UI that matches your design system
    * Full control over recording controls, status, and layout
  </Card>

  <Card title="What's Provided:" icon="gear">
    * React hooks for auth and ambient sessions
    * Core ambient, streaming, and session behavior
    * No pre-built clinical UI (you build the interface)
  </Card>
</CardGroup>

### Mobile SDK

The Mobile SDK offers native iOS integration for ambient workflows on mobile devices.

<CardGroup cols={2}>
  <Card title="Recommended For:" icon="mobile">
    * Native iOS applications
    * Mobile healthcare apps
    * Apps requiring native device features
  </Card>

  <Card title="Platform Support:" icon="gear">
    * iOS (available now)
    * Android (in development)
  </Card>
</CardGroup>

### Dictation APIs

Dictation APIs give you full control over speech-to-text. You create transcription sessions, stream audio on `/ws/transcribe`, and handle intermediate and final transcripts in your own application.

Use Dictation APIs when you own the clinician experience end to end: where Dictation starts, which chart field receives text, how the provider reviews and edits transcripts, and how final documentation is approved.

<CardGroup cols={2}>
  <Card title="Recommended For:" icon="server">
    * Backend systems and server-side audio pipelines
    * Custom Dictation UI on web, mobile, or both
    * Multi-platform apps that share one API surface
  </Card>

  <Card title="What You Build:" icon="gear">
    * Dictation start, stop, and status controls
    * Where transcript text lands in the chart
    * Review, correction, and approval flows
  </Card>
</CardGroup>

### Dictation SDK

The Dictation SDK embeds hosted Dictation in your web application through an iframe and JavaScript or React packages. It supports **in-field** Dictation into a specific input and **scratchpad** Dictation for free-form capture.

Use the Dictation SDK when you want Suki to manage Dictation mechanics in the browser, and you connect transcript callbacks into your chart fields or note workflow.

<CardGroup cols={2}>
  <Card title="Recommended For:" icon="microphone">
    * React or JavaScript web applications
    * Teams that want hosted in-field or scratchpad UI
    * Faster browser Dictation without building REST and WebSocket yourself
  </Card>

  <Card title="What's Provided:" icon="gear">
    * Hosted iframe for Dictation
    * In-field and scratchpad modes
    * JavaScript and React packages
  </Card>
</CardGroup>

<Note>
  Web SDK also supports Audio Dictation in the browser with Suki Web SDK packages. Use it when you already integrate Web SDK for ambient and want Dictation in the same browser stack. Refer to [Web SDK for Audio Dictation](/web-sdk/dictation-overview).
</Note>

## How to choose

Before you pick an ambient path, decide whether the clinician also needs Audio Dictation in the same product. Ambient listens and helps generate documentation from the encounter. Audio Dictation lets the provider control exact wording and pace. Most products need both. Refer to [Ambient vs Audio Dictation](/documentation/concepts/dictation/dictation#ambient-vs-audio-dictation).

<Tabs>
  <Tab title="By Project Type">
    <AccordionGroup>
      <Accordion title="Web-Based Healthcare Application">
        **Choose Web SDK if:**

        * You want pre-built clinical UI components
        * You prefer the fastest path to a browser-based integration with Suki-provided UI
        * You also need Audio Dictation in the same Web SDK browser stack

        **Choose Headless Web SDK if:**

        * You use React 18 or higher and want hooks for auth, sessions, and recording
        * You need a custom interface, branding, or workflows that pre-built components do not cover
        * You want SDK-managed session and audio behavior while owning all presentation

        **Choose Dictation SDK if:**

        * Your primary need is browser Dictation into fields or a scratchpad
        * You want a hosted iframe for start, stop, and transcript capture
        * You will map transcript callbacks into your own chart or note UI

        **Choose Direct APIs (Ambient APIs and/or Dictation APIs) if:**

        * Your client is not React, or you integrate from multiple client types against the same API surface
        * You want full control at the REST/WebSocket level without an SDK on the web client
        * You need custom Dictation UX for chart navigation, review, and approval
      </Accordion>

      <Accordion title="Mobile Healthcare Application">
        **For ambient on iOS:**

        * **Choose Mobile SDK** for native ambient capture and device integration

        **For Dictation on iOS or Android:**

        * **Choose Dictation APIs** and implement REST plus `/ws/transcribe` in your native app or through your backend
        * Dictation SDK is browser-only and does not cover native mobile clients

        **For Android ambient:**

        * **Choose Ambient APIs** - Mobile SDK for Android is currently in development
      </Accordion>

      <Accordion title="Backend System or Server Integration">
        **Choose Direct APIs (Ambient APIs and/or Dictation APIs)**

        * This is your primary option for server-to-server integrations
        * Provides complete control over session lifecycle, audio handling, and system integration
      </Accordion>
    </AccordionGroup>
  </Tab>

  <Tab title="By Team Skills">
    <CardGroup cols={2}>
      <Card title="Frontend/React Experience">
        **Recommended: Web SDK, Headless Web SDK, or Dictation SDK**

        Use **Web SDK** for pre-built ambient UI and speed. Use **Headless Web SDK** when you build custom ambient UI in React with hooks. Use **Dictation SDK** when you need hosted in-field or scratchpad Dictation in the browser.
      </Card>

      <Card title="Backend/API Experience">
        **Recommended: Direct APIs**

        Full control for Ambient APIs and Dictation APIs, and leverages existing API development skills
      </Card>

      <Card title="iOS/Swift Experience">
        **Recommended: Mobile SDK for Ambient, Dictation APIs for Dictation**

        Native ambient with Mobile SDK. Custom Dictation UX against Dictation APIs with your own controls and chart fields.
      </Card>

      <Card title="Limited Development Resources">
        **Recommended: Web SDK and/or Dictation SDK**

        Minimal custom UI work with ready-to-use ambient components or hosted Dictation in the browser
      </Card>
    </CardGroup>
  </Tab>

  <Tab title="By Requirements">
    | Your Need                                            | Recommended Choice | Why                                                        |
    | ---------------------------------------------------- | ------------------ | ---------------------------------------------------------- |
    | **Quick ambient integration in the browser**         | Web SDK            | Ready-to-use components, minimal setup                     |
    | **Custom ambient web UI in React**                   | Headless Web SDK   | Hooks for platform behavior; you own layout and components |
    | **Browser Dictation into a field or scratchpad**     | Dictation SDK      | Hosted iframe, in-field and scratchpad modes               |
    | **Custom Dictation UX on web or mobile**             | Dictation APIs     | You own start/stop, chart target, review, and approval     |
    | **Custom UI/UX without React on the web**            | Direct APIs        | Use your stack and patterns against the API                |
    | **Native mobile features (iOS ambient)**             | Mobile SDK         | Native device integration and performance                  |
    | **Multi-platform support**                           | Direct APIs        | Same API surface across web, mobile, and backend           |
    | **Complete UX control (any client)**                 | Direct APIs        | Build exactly what you need at the protocol level          |
    | **Proven clinical ambient workflows in the browser** | Web SDK            | Pre-built healthcare interface patterns                    |
  </Tab>
</Tabs>

<Note>
  **HIPAA Compliance**: All integration methods can be implemented in a HIPAA-compliant manner. Compliance depends on your implementation practices and security measures.
</Note>

## Designing Audio Dictation into your clinical UX

Audio Dictation is speech-to-text. Your product decides where the text goes, how the clinician navigates the chart while speaking, and how they review and approve documentation. Answer these questions before you choose Dictation APIs or Dictation SDK.

### Where will the clinician use Dictation

| Client                 | Typical fit                                                                               | Why                                                                       |
| ---------------------- | ----------------------------------------------------------------------------------------- | ------------------------------------------------------------------------- |
| **Desktop web**        | Dictation SDK, Web SDK, or Dictation APIs                                                 | Browser Dictation into chart fields, notes, or a scratchpad               |
| **Mobile web**         | Dictation SDK or Dictation APIs                                                           | Same browser paths; validate mic permissions and layout on small screens  |
| **Native mobile**      | Dictation APIs                                                                            | Dictation SDK is browser-only; native apps call REST and `/ws/transcribe` |
| **Desktop and mobile** | Dictation APIs for shared behavior, or Dictation SDK on web plus Dictation APIs on native | One API surface across clients when UX must stay consistent               |

### What is the clinician dictating into

| Documentation target    | What to design                                                                                                              | Typical fit                                                                                                   |
| ----------------------- | --------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- |
| **Free-text editor**    | Continuous transcript into a note body or comment field                                                                     | Dictation SDK scratchpad, Web SDK, or Dictation APIs into your editor                                         |
| **Sectioned note**      | Map transcripts to HPI, Assessment, Plan, or other sections as the clinician moves through the note                         | Dictation APIs or Web SDK with your section focus logic                                                       |
| **Template-based form** | Bind speech to specific fields. For Suki medical forms from visit conversation, use Form filling instead of Audio Dictation | [Form filling integration decision guide](/documentation/get-started/form-filling-integration-decision-guide) |

### How should providers navigate the chart while dictating

Decide whether Dictation follows the focused field, a floating control, or a dedicated panel:

* **In-field**: Provider focuses a chart field and Dictation writes into that field. Best when documentation is field-driven. Dictation SDK **in-field** mode is built for this pattern.
* **Scratchpad**: Provider dictates into a temporary panel, then copies or inserts text into the chart. Best when they compose free text before placing it. Dictation SDK **scratchpad** mode is built for this pattern.
* **Custom chart navigation**: Provider moves across sections while you keep one session or start a new session per field. Best when your EHR owns focus and insertion. Use **Dictation APIs** so you control session lifecycle and where each transcript lands.

### How should providers run the documentation loop

Design clear actions for each step:

| Action                          | What you need to decide                                | Dictation SDK                                                       | Dictation APIs                                       |
| ------------------------------- | ------------------------------------------------------ | ------------------------------------------------------------------- | ---------------------------------------------------- |
| **Start and stop**              | Mic control, keyboard shortcut, or in-chart button     | Hosted controls in the iframe                                       | You build start, stop, pause, and status             |
| **Review dictated text**        | Inline in the field, side panel, or after each segment | Transcript appears in field or scratchpad                           | You render intermediate and final transcripts        |
| **Correct errors quickly**      | Edit in place, re-dictate, or undo last segment        | Provider edits in your field after insert; you handle re-dictate UX | You own edit, replace, and re-stream behavior        |
| **Approve final documentation** | Save to EHR, sign, or send to review queue             | Your app owns approval after callbacks                              | Your app owns approval after you persist transcripts |

<Tip>
  If ambient generates a note and the provider must fix wording, use Audio Dictation as a supplement. Keep Ambient and Dictation as separate modes in the UI so providers know when the system is listening to the encounter versus when they are controlling exact text.
</Tip>

## Prerequisites for all integration methods

Before integrating with any Suki Platform method, you must complete the partner onboarding process:

### Required for all integration methods

**Partner Registration:**

* Complete the [Partner onboarding process](/documentation/get-started/partner-onboarding)
* Receive your unique `partner_id` from Suki
* Provide your JWKS endpoint URL to Suki for token validation

**Authentication System:**

* OAuth 2.0 compliant authentication system
* JWT token generation with consistent user identifier
* Publicly accessible JWKS endpoint for token verification

### Additional requirements by method

**Web SDK:**

* ES6+ compatible browsers
* Host URLs whitelisted with Suki for SDK embedding

**Headless Web SDK:**

* React 18.0 or higher
* ES6+ compatible browsers
* Host URLs for your test and production apps provided to Suki for allowlisting (see [Headless Web SDK prerequisites](/headless-web-sdk/prerequisites))

**Mobile SDK (iOS):**

* iOS 14.0 or later
* Xcode development environment
* Audio recording permissions in your app

**Ambient APIs:**

* WebSocket client implementation capability
* HTTPS/TLS support for secure API communication

**Dictation APIs:**

* WebSocket client implementation capability for `/ws/transcribe`
* HTTPS/TLS support for secure API communication
* Your own UI for Dictation controls and transcript insertion

**Dictation SDK:**

* ES6+ compatible browsers
* Host URLs for your test and production apps provided to Suki for allowlisting (see [Dictation SDK prerequisites](/dictation-sdk/prerequisites))

## Integration scenarios

<Tabs>
  <Tab title="Web Applications">
    <AccordionGroup>
      <Accordion title="EHR Integration">
        **Scenario:** Existing web-based Electronic Health Record system needing Ambient clinical documentation

        **Recommended: Web SDK**

        * Integrates directly into your existing web application
        * Provides pre-built clinical note interface
        * Handles audio streaming and note generation automatically
      </Accordion>

      <Accordion title="Patient Portal">
        **Scenario:** Healthcare patient portal where providers can document encounters during telehealth visits

        **Recommended: Web SDK**

        * Ready-to-use telehealth documentation interface
        * Built-in audio processing for web browsers
        * Seamless integration with existing patient management systems
      </Accordion>

      <Accordion title="Custom-Branded Web Documentation Experience">
        **Scenario:** Web EHR or clinician workflow where ambient capture must match your design system, layout, and interaction patterns

        **Recommended: Headless Web SDK** (React 18+)

        * React hooks for authentication, session lifecycle, and recording control
        * You implement controls, status, and note presentation
        * Same core ambient capabilities as the Web SDK without pre-built clinical UI

        If you are not on React, use **Direct APIs** for an equivalent level of UI ownership.
      </Accordion>

      <Accordion title="Dictation into Chart Fields in the Browser">
        **Scenario:** Clinician focuses an HPI, Assessment, or free-text field and speaks. Text must appear in that field with quick start, stop, and edit.

        **Recommended: Dictation SDK** (in-field mode)

        * Hosted iframe over the focused input
        * Transcript callbacks map into your chart field
        * Faster than building REST and WebSocket yourself

        Use **Web SDK for Audio Dictation** if you already use Web SDK packages for ambient in the same browser app.
      </Accordion>

      <Accordion title="Dictation Scratchpad Before Inserting into the Note">
        **Scenario:** Clinician composes free text in a panel, then pastes or inserts into a sectioned note.

        **Recommended: Dictation SDK** (scratchpad mode)

        * Hosted scratchpad UI for capture
        * Your app owns insert, section targeting, and approval
      </Accordion>

      <Accordion title="Custom Dictation UX Across a Sectioned Chart">
        **Scenario:** Clinician moves through Assessment and Plan while you control focus, session lifecycle, review, and sign-off.

        **Recommended: Dictation APIs**

        * Full control over start, stop, and where each transcript lands
        * Intermediate and final transcripts for your own review UI
        * Same pattern if you later add native mobile clients
      </Accordion>
    </AccordionGroup>
  </Tab>

  <Tab title="Mobile Applications">
    <AccordionGroup>
      <Accordion title="iOS Telehealth App">
        **Scenario:** Native iOS application for remote patient consultations with clinical note capture during video calls

        **Recommended: Mobile SDK**

        * Native iOS performance and device integration
        * Works with your existing iOS app architecture
        * Provides offline functionality for unreliable network conditions
      </Accordion>

      <Accordion title="Android Healthcare App">
        **Scenario:** Native Android application for clinical documentation

        **Recommended: Direct APIs**

        * Custom implementation using Direct APIs
        * Full control over Android user experience
        * Mobile SDK for Android currently in development
      </Accordion>

      <Accordion title="Native Mobile Dictation into the Chart">
        **Scenario:** Clinician dictates on phone or tablet into a free-text note or sectioned chart, then reviews and saves.

        **Recommended: Dictation APIs**

        * Dictation SDK does not run in native mobile apps
        * You build mic controls, chart insertion, correction, and approval
        * Same Dictation APIs work if you also support desktop web with a custom UI
      </Accordion>
    </AccordionGroup>
  </Tab>

  <Tab title="Backend Systems">
    <AccordionGroup>
      <Accordion title="Data Processing System">
        **Scenario:** Batch processing of clinical audio files or integration with existing backend workflow systems

        **Recommended: Direct APIs**

        * Server-to-server integration capability
        * Complete control over data processing workflows
        * Integration with existing backend systems and databases
      </Accordion>

      <Accordion title="Multi-Platform Healthcare Suite">
        **Scenario:** Healthcare applications spanning web browsers, mobile devices, and backend systems

        **Recommended: Direct APIs**

        * Single integration approach works across all platforms
        * Complete control over user experience on each platform
        * Consistent API interface regardless of client type
      </Accordion>

      <Accordion title="Server-Owned Dictation Pipeline">
        **Scenario:** Your backend creates transcription sessions, receives audio from clients, and returns transcripts to your EHR services.

        **Recommended: Dictation APIs**

        * Create session, stream on `/ws/transcribe`, and handle transcripts on the server
        * Clients stay thin while your backend owns persistence and approval rules
      </Accordion>
    </AccordionGroup>
  </Tab>
</Tabs>

## Start your integration journey with Suki

To begin your integration, review the documentation for your chosen approach:

<Icon icon="file-lines" iconType="solid" /> **[Web SDK Quickstart](/web-sdk/quickstart)** - Get started with pre-built components and fast integration.

<Icon icon="file-lines" iconType="solid" /> **[Headless Web SDK Quickstart](/headless-web-sdk/quickstart)** - React hooks, custom UI, and ambient sessions in your application.

<Icon icon="file-lines" iconType="solid" /> **[API Overview](/api-reference/overview)** - Build custom integrations with maximum flexibility.

<Icon icon="file-lines" iconType="solid" /> **[Mobile SDK Overview](/mobile-sdk/overview)** - Native iOS integration for mobile applications.

<Icon icon="file-lines" iconType="solid" /> **[Dictation APIs](/api-reference/audio-transcription/create-session)** - Create sessions, stream on `/ws/transcribe`, and own transcript UX.

<Icon icon="file-lines" iconType="solid" /> **[Dictation SDK Overview](/dictation-sdk/introduction)** - Hosted in-field and scratchpad Dictation in your web application.

<Icon icon="file-lines" iconType="solid" /> **[Partner Onboarding](/documentation/get-started/partner-onboarding)** - Start your integration journey with Suki.

## Get personalized integration guidance

If your use case doesn't clearly match the scenarios above, or you need specific technical advice for your healthcare application, our customer success team provides personalized consultation.

**Before contacting support or sales, prepare:**

* Description of your healthcare application and clinical workflows
* Target platform (web with React or not, iOS, Android, backend system)
* Whether clinicians need ambient, Audio Dictation, or both
* Where dictated text lands (free-text editor, sectioned note, or form fields)
* Development timeline and resource constraints
* Specific technical requirements or compliance needs

**Contact options:**

* **Technical consultation**: [Schedule a call with our integration team](https://www.suki.ai/suki-partners/)
* **Development support**: [support@suki.ai](mailto:support@suki.ai)
* **Community discussions**: [Contact us for community access](https://www.suki.ai/contact-us/)