Ambient & Dictation - Integration Decision Guide

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.

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.

Recommended For:

Backend systems and server integrations
Custom user interfaces on any stack
Multi-platform applications

What You Build:

Complete user interface
Authentication flow
Audio handling and API/WebSocket usage

Web SDK

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

Recommended For:

Web-based healthcare applications
Browser-based EHR integrations
Teams that want pre-built clinical UI

What's Provided:

Pre-built UI components
Authentication handling
Audio processing

Headless Web SDK

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

Recommended For:

React web applications (React 18+)
Custom UI that matches your design system
Full control over recording controls, status, and layout

What's Provided:

React hooks for auth and ambient sessions
Core ambient, streaming, and session behavior
No pre-built clinical UI (you build the interface)

Mobile SDK

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

Recommended For:

Native iOS applications
Mobile healthcare apps
Apps requiring native device features

Platform Support:

iOS (available now)
Android (in development)

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.

Recommended For:

Backend systems and server-side audio pipelines
Custom Dictation UI on web, mobile, or both
Multi-platform apps that share one API surface

What You Build:

Dictation start, stop, and status controls
Where transcript text lands in the chart
Review, correction, and approval flows

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.

Recommended For:

React or JavaScript web applications
Teams that want hosted in-field or scratchpad UI
Faster browser Dictation without building REST and WebSocket yourself

What's Provided:

Hosted iframe for Dictation
In-field and scratchpad modes
JavaScript and React packages

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.

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.

By Project Type
By Team Skills
By Requirements

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

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

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

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

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

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

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

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.

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
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)

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)

Integration scenarios

Web Applications
Mobile Applications
Backend Systems

EHR Integration

Scenario: Existing web-based Electronic Health Record system needing Ambient clinical documentationRecommended: Web SDK

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

Patient Portal

Scenario: Healthcare patient portal where providers can document encounters during telehealth visitsRecommended: Web SDK

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

Custom-Branded Web Documentation Experience

Scenario: Web EHR or clinician workflow where ambient capture must match your design system, layout, and interaction patternsRecommended: 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.

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.

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

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

Data Processing System

Scenario: Batch processing of clinical audio files or integration with existing backend workflow systemsRecommended: Direct APIs

Server-to-server integration capability
Complete control over data processing workflows
Integration with existing backend systems and databases

Multi-Platform Healthcare Suite

Scenario: Healthcare applications spanning web browsers, mobile devices, and backend systemsRecommended: Direct APIs

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

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

Start your integration journey with Suki

To begin your integration, review the documentation for your chosen approach: Web SDK Quickstart - Get started with pre-built components and fast integration. Headless Web SDK Quickstart - React hooks, custom UI, and ambient sessions in your application. API Overview - Build custom integrations with maximum flexibility. Mobile SDK Overview - Native iOS integration for mobile applications. Dictation APIs - Create sessions, stream on /ws/transcribe, and own transcript UX. Dictation SDK Overview - Hosted in-field and scratchpad Dictation in your web application. 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
Development support: support@suki.ai
Community discussions: Contact us for community access

​Integration options

​Ambient APIs

Recommended For:

What You Build:

​Web SDK

Recommended For:

What's Provided:

​Headless Web SDK

Recommended For:

What's Provided:

​Mobile SDK

Recommended For:

Platform Support:

​Dictation APIs

Recommended For:

What You Build:

​Dictation SDK

Recommended For:

What's Provided:

​How to choose

Frontend/React Experience

Backend/API Experience

iOS/Swift Experience

Limited Development Resources

​Designing Audio Dictation into your clinical UX

​Where will the clinician use Dictation

​What is the clinician dictating into

​How should providers navigate the chart while dictating

​How should providers run the documentation loop

​Prerequisites for all integration methods

​Required for all integration methods

​Additional requirements by method

​Integration scenarios

​Start your integration journey with Suki

​Get personalized integration guidance

Integration options

Ambient APIs

Web SDK

Headless Web SDK

Mobile SDK

Dictation APIs

Dictation SDK

How to choose

Designing Audio Dictation into your clinical UX

Where will the clinician use Dictation

What is the clinician dictating into

How should providers navigate the chart while dictating

How should providers run the documentation loop

Prerequisites for all integration methods

Required for all integration methods

Additional requirements by method

Integration scenarios

Start your integration journey with Suki

Get personalized integration guidance