Suki Glossary

New to Suki and not sure what a term means? Browse definitions below, or open the letter pages in the sidebar for dedicated glossary pages. Use the category and letter filters to narrow the list.

# H Source: https://developer.suki.ai/Glossary/h Glossary terms starting with H

H

| Term | Definition | | :--------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Headed SDK** | An SDK that includes pre-built User Interface (UI) components. Our Web SDK is headed. | | **Headless SDK** | An SDK that does not include pre-built UI components, allowing developers to create their own UI. Our Mobile SDK is headless. | | **HIPAA** | Health Insurance Portability and Accountability Act. U.S. legislation that provides data privacy and security provisions for safeguarding medical information. | | **HL7** | Health Level Seven International. A set of international standards for the transfer of clinical and administrative data between healthcare applications. | | **HMAC** | Hash-based Message Authentication Code. A cryptographic method used to verify the integrity and authenticity of webhook payloads sent from Suki to partner endpoints. | | **Hospital** | A healthcare institution that provides patient treatment with specialized health science and auxiliary healthcare staff and medical equipment. | | **HPI** | History of Present Illness. A clinical note section (LOINC: 10164-2) describing the chronological development of the patient's current health issue. | | **HTTPS** | HyperText Transfer Protocol Secure. An extension of HTTP that uses encryption for secure communication over a network. |

# I Source: https://developer.suki.ai/Glossary/i Glossary terms starting with I

I

| Term | Definition | | :-------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **ICD10** | International Classification of Diseases, 10th Revision. A standardized coding system maintained by the WHO for classifying diagnoses, symptoms, and medical procedures. | | **Idempotency** | A property ensuring that performing the same API operation multiple times produces the same result, preventing duplicate processing of requests. | | **IDP** | Identity Provider. An acronym for a system that manages user identities and authenticates users. Examples include Okta, Auth0, Azure AD, and custom authentication systems. | | **IMO** | Intelligent Medical Objects. A clinical terminology and mapping platform that standardizes medical concepts across healthcare systems and coding vocabularies. |

# J Source: https://developer.suki.ai/Glossary/j Glossary terms starting with J

J

| Term | Definition | | :---------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **JWT** | JSON Web Token. A compact, URL-safe means of representing claims to be transferred between two parties, commonly used for authentication and information exchange. | | **JWKS** | JSON Web Key Set. A set of keys containing the public keys used to verify any JWT issued by the authorization server. | | **JWKS Endpoint** | A publicly accessible HTTPS endpoint that hosts cryptographic public keys for JWT token verification. |

# K Source: https://developer.suki.ai/Glossary/k Glossary terms starting with K

K

| Term | Definition | | :------------- | :------------------------------------------------------------------------------------------------------------------------------ | | **Keep Alive** | A WebSocket streaming event sent every 5 seconds during paused states to maintain connection and prevent timeout disconnection. |

# L Source: https://developer.suki.ai/Glossary/l Glossary terms starting with L

L

| Term | Definition | | :----------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Latency** | The delay between sending audio data and receiving a response. Suki requires unloaded latency under 50ms and loaded latency under 150ms for optimal performance. | | **LINEAR16** | An uncompressed audio format with 16-bit depth, used for high-quality audio streaming to Suki's platform at 16KHz sampling rate. | | **LLM** | Large Language Model. Advanced AI models trained on vast amounts of text data to understand and generate human-like text, used by Suki for clinical note generation. | | **LOINC** | Logical Observation Identifiers Names and Codes. A standardized vocabulary for identifying clinical sections and medical concepts. |

# M Source: https://developer.suki.ai/Glossary/m Glossary terms starting with M

M

| Term | Definition | | :---------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | **MCP** | Model Context Protocol. An open standard that enables AI assistants and LLMs to securely connect with external data sources and tools, used by Suki for AI-powered documentation workflows. | | **Medically-tuned Dictation** | Speech recognition technology specifically optimized for medical terminology and clinical language patterns. | | **Medications** | A clinical note section (LOINC: 10160-0) listing the patient's current medications, dosages, and any prescription changes made during the encounter. | | **Mental Status Exam** | A clinical note section (LOINC: 10190-7) documenting the assessment of a patient's cognitive and emotional functioning during an encounter. | | **Model Training** | The process of using de-identified and anonymized data to improve AI model performance. Suki uses this data to enhance clinical note generation capabilities. | | **Mono Channel** | Single-channel audio format required for Suki's platform, as opposed to stereo (dual-channel) audio. | | **Monologue** | A single-person speech recording, such as when a clinician dictates notes alone, as opposed to a conversation between clinician and patient. | | **Multilingual Support** | The capability to process clinical conversations in over 80 languages while generating the final clinical note in English. |

# N Source: https://developer.suki.ai/Glossary/n Glossary terms starting with N

N

| Term | Definition | | :------------------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Natural Language Voice Interaction** | Technology that allows users to interact with systems using spoken natural language commands and queries. | | **NLP** | Natural Language Processing. AI technology that helps computers understand, interpret, and generate human language. | | **Note Archive** | A Web SDK component that allows users to view and manage both current and historical clinical notes associated with a patient. | | **Note Editor** | A rich-text editing component in the Web SDK designed specifically for AI-generated clinical content, supporting editing, formatting, and section-level interaction. | | **Note Generation** | The automated process of creating structured clinical documentation from recorded patient encounters using AI technology. | | **Note ID** | It is the unique identifier for the generated note. It appears in the payload for the `onNoteSubmit` prop (React) and the `note-submission:success` event (React and JavaScript). See [Note Management](/web-sdk/guides/note-management). | | **Note Section** | A discrete, labeled portion of a clinical note identified by a LOINC code (e.g., HPI, Physical Exam, and Assessment and Plan) that organizes documentation into standardized categories. | | **Note Submission** | The action of finalizing and sending a completed clinical note to the partner's EHR system, typically triggered via an SDK callback or API event. | | **Notification Webhook** | A server-to-server HTTP callback from Suki to a partner's registered endpoint, triggered by events such as note generation completion or session status changes. |

# O Source: https://developer.suki.ai/Glossary/o Glossary terms starting with O

O

| Term | Definition | | :------------------ | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | **OAuth 2.0** | An industry-standard authorization framework that enables secure delegated access to resources without sharing passwords. | | **Offline Mode** | A capability that allows certain SDK features to function without an internet connection, enabling users to work in environments with limited connectivity. | | **Offline Session** | An ambient session recorded while the device has no network connectivity. Audio is stored locally and automatically uploaded when connectivity is restored. | | **OpenAPI** | A specification for describing REST APIs in a machine-readable format, used by Suki to document API endpoints, request/response schemas, and authentication requirements. | | **OpenID Connect** | An authentication layer built on top of OAuth 2.0, providing identity verification and user information access. | | **Organization** | A healthcare entity or health system that partners with Suki to provide AI-powered documentation services to their providers and clinicians. |

# P Source: https://developer.suki.ai/Glossary/p Glossary terms starting with P

P

| Term | Definition | | :------------------------ | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Partner** | An organization or company that integrates with Suki's platform to offer AI-powered clinical documentation services to their users. | | **Partner ID** | A unique identifier assigned by Suki during onboarding that links an application to its configuration in the Suki Developer Platform. | | **Partner Token** | A secure, digitally signed JWT issued by a partner's identity provider after user authentication, passed to Suki SDK for user verification. | | **Past Medical History** | A clinical note section (LOINC: 11348-0) documenting the patient's prior medical conditions, surgeries, hospitalizations, and significant health events. | | **Past Surgical History** | A clinical note section (LOINC: 10167-5) documenting the patient's prior surgical procedures and their outcomes. | | **Patient Instructions** | A clinical note section (LOINC: 69730-0) containing care instructions, follow-up guidance, and educational materials provided to the patient. | | **PAUSE** | A WebSocket streaming event that temporarily suspends audio transmission while keeping the session active, allowing resumption later. | | **PBC** | Problem-Based Charting. A clinical documentation approach that organizes notes around specific patient problems, with each problem having its own assessment and plan. | | **PBN** | Problem-Based Note. A clinical documentation format that organizes information around specific patient problems or diagnoses rather than traditional SOAP format. | | **PCM** | Pulse-Code Modulation. A method of digitally encoding analog audio signals. Suki uses LINEAR16 PCM format at 16KHz for audio streaming. | | **Personalization** | The ability to customize note generation behavior per provider, including preferred verbosity levels, section formats (narrative or bulleted), and specialty-specific templates. | | **PHI** | Protected Health Information. Any individually identifiable health information created, received, maintained, or transmitted by a covered entity, protected under HIPAA regulations. | | **Physical Exam** | A clinical note section (LOINC: 29545-1) documenting the physical examination findings during a patient encounter. | | **PII** | Personally Identifiable Information. Data that can be used to identify a specific individual, such as names, addresses, or social security numbers. Suki de-identifies PII from transcripts. | | **Presigned URL** | A time-limited, pre-authenticated URL that grants temporary access to a specific resource (such as an audio recording) without requiring additional authentication. | | **Problem List** | A clinical note section (LOINC: 11450-4) containing an active list of the patient's diagnosed conditions and ongoing health concerns. | | **Provider** | A healthcare professional (such as a doctor or nurse) within an organization who uses Suki's services to document patient care. | | **Provider ID** | A unique identifier for a specific healthcare provider within a partner organization, used to associate sessions, notes, and preferences with the correct clinician. |

# R Source: https://developer.suki.ai/Glossary/r Glossary terms starting with R

R

| Term | Definition | | :-------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Rate Limiting** | A mechanism that restricts the number of API requests a client can make within a given time period, used to protect platform stability and ensure fair usage. | | **Real-time** | Processing and response that occurs immediately or with minimal delay, such as live audio transcription and streaming to Suki's platform. | | **Reseller Program** | A business program that allows partners to embed Suki Platform's core technology directly into their own solutions and sell applications powered by Suki's assistive technology. | | **REST API** | Representational State Transfer Application Programming Interface. An architectural style for designing networked applications using standard HTTP methods. | | **RESUME** | A WebSocket streaming event that restarts audio transmission after a pause. | | **Review of Systems (ROS)** | A clinical note section (LOINC: 10187-3) documenting a systematic review of body systems to identify signs and symptoms the patient may be experiencing. | | **RS256** | RSA Signature with SHA-256. A digital signature algorithm used for signing and verifying JWT tokens in Suki's authentication flow. | | **RSA** | An asymmetric cryptographic algorithm used for secure data transmission and digital signatures, commonly used in JWT token verification. |

# S Source: https://developer.suki.ai/Glossary/s Glossary terms starting with S

S

| Term | Definition | | :-------------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Sampling Rate** | The number of audio samples captured per second, measured in Hertz. Suki requires 16KHz sampling rate for optimal audio quality. | | **SDK** | Software Development Kit. A collection of tools, libraries, and documentation to help developers build applications for a specific platform. | | **Service Contract** | A formal agreement between Suki and healthcare customers that defines service levels, data retention policies, and compliance requirements. | | **Semantic Versioning** | A versioning scheme (MAJOR.MINOR.PATCH) used for SDKs and APIs where major versions indicate breaking changes, minor versions add features, and patches fix bugs. | | **Session** | A single, time-bound instance of an ambient recording for a specific patient encounter. | | **Session Context** | Metadata provided when creating an ambient session (such as encounter type, patient age, diagnoses) that helps guide note generation and improve output quality. | | **Session ID** | In the Suki Web SDK, the **ambient session** identifier appears as **`ambientId`** on event payloads (`ambient:update`, `ambient:start` through `ambient:submit`; see [Emitter events](/web-sdk/api-reference/types/emitter-events)) and as **`activeAmbientId`** on `SDKClientInstance` (`string` or `null`; see [Classes](/web-sdk/api-reference/classes) and [Hooks](/web-sdk/api-reference/hooks)). After `startAmbient()`, read `sdkClient.activeAmbientId` or the same value from `useSuki()` in React. It is **not** the same as **`encounterId`** on the note submission payload ([Note management](/web-sdk/guides/note-management), [Encounter ID](/Glossary/e)). See [Session status](/web-sdk/guides/ambient-session-status) and [Create session](/web-sdk/guides/ambient-implementation). | | **Session Recovery** | The ability to reconnect and resume an interrupted ambient session, allowing continuation of recording and note generation after a network or device disruption. | | **Session Timeouts** | Automatic disconnection that occurs when no audio data is sent for 25 seconds (active state) or 30 minutes during pause with keep-alive events. | | **SNOMED** | Systematized Nomenclature of Medicine. A comprehensive clinical terminology system used for encoding clinical concepts like diagnoses, procedures, and findings. | | **SOC 2 Type II** | A security compliance certification that evaluates an organization's controls for data security, availability, processing integrity, confidentiality, and privacy over time. | | **Social History** | A clinical note section (LOINC: 29762-2) documenting lifestyle factors such as tobacco use, alcohol consumption, occupation, and living situation. | | **SHA-256** | Secure Hash Algorithm 256-bit. A cryptographic hash function used for data integrity verification and digital signatures in security protocols. | | **SOAP Note** | Subjective, Objective, Assessment, Plan. A traditional clinical documentation format that organizes patient information into these four standardized sections. | | **Speech Recognition** | Technology that converts spoken words into written text, enabling voice-to-text functionality for clinical documentation. | | **Structured Data** | Organized medical information extracted from clinical conversations, such as diagnoses, medications, allergies, and vital signs, formatted for integration with EHR systems. | | **Suki Developer Platform (SDP)** | The official name for the entire suite of Suki's developer tools, including all APIs and SDKs. | | **Suki Token** | The access token returned by Suki's authentication API, used to authorize subsequent API requests to the Suki platform. |

# T Source: https://developer.suki.ai/Glossary/t Glossary terms starting with T

T

# U Source: https://developer.suki.ai/Glossary/u Glossary terms starting with U

U

| Term | Definition | | :--------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------- | | **Upload Speed** | The rate at which data can be transmitted from a client device to Suki's servers. Suki requires minimum 768kbps upload speed for optimal performance. |

# V Source: https://developer.suki.ai/Glossary/v Glossary terms starting with V

V

| Term | Definition | | :----------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **VARCHAR** | A VARCHAR (Variable Character) data type in SQL accepts variable-length string data, including letters, numbers, and special characters. It is used for storing alphanumeric data where the length of the entries varies significantly, such as names, addresses, or descriptions. | | **varchar(36)** | A **VARCHAR** column with a **36-character** maximum length. Web SDK **`patient.identifier`** and **`encounter.identifier`** must not exceed **36 characters**. For the general **`VARCHAR`** SQL type, see the row above. | | **Verbosity** | A personalization setting that controls the level of detail in generated clinical notes. Options include concise, balanced, and detailed output levels. | | **Visit Type** | A classification of the clinical encounter (e.g., new patient, follow-up, annual wellness), used alongside encounter type to guide note generation behavior. | | **Vitals** | A clinical note section (LOINC: 8716-3) documenting measured vital signs such as blood pressure, heart rate, temperature, and respiratory rate. | | **Voice Commands** | Spoken instructions that trigger specific actions within the Suki platform, enabling hands-free interaction with clinical documentation features. |

# W Source: https://developer.suki.ai/Glossary/w Glossary terms starting with W

W

| Term | Definition | | :------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **WAF** | Web Application Firewall. A security service that protects web applications by filtering and monitoring HTTP traffic between applications and the internet. | | **Webhook** | A mechanism that allows Suki to send real-time event notifications (like `session_summary_generated`) to your application's server. | | **Webhook Payload** | The JSON data body sent by Suki to a partner's callback URL when a webhook event is triggered, containing event details and relevant session or note data. | | **WebSocket** | A communication protocol that provides full-duplex communication channels over a single TCP connection, used for real-time audio streaming to Suki's platform. | | **WebSocket Secure (WSS)** | The secure version of WebSocket protocol that uses TLS/SSL encryption for protected data transmission during real-time audio streaming. |

# Suki APIs Overview Source: https://developer.suki.ai/api-overview/overview Overview of REST, WebSocket, and webhook APIs on the Suki Developer Platform, with links to Ambient APIs, Form Filling APIs, and API guidelines.

Suki APIs

Suki provides partner APIs that let you integrate Suki's ambient clinical intelligence into your applications.

Introduction

Suki APIs use REST for API requests, Suki access tokens for authentication, and WebSockets for real-time audio streaming. The APIs return standard HTTP status codes and JSON response bodies. You can explore and test the APIs using the OpenAPI bundle. Access requires partner onboarding.

Use the APIs to capture clinical conversations, stream live audio, retrieve structured output, and receive webhook events while your application owns the UI and downstream integrations.

How it works

Use REST endpoints: Create sessions, send context, end sessions, and retrieve results from the API reference.
Add streaming when needed: Use WebSocket flows when a workflow needs live audio. Send the correct session context for that workflow.
Receive asynchronous notifications: Configure webhooks when you want completion and status events sent to your backend.

Authentication

Suki APIs are available only to approved partners. Complete Partner onboarding before you use them. Authentication has two layers:

Partner authentication: Your application sends a JWT from your identity provider (partner token). Suki validates it against your registered keys so traffic is tied to your organization.
Provider authentication: Register each clinician once, then sign them in for a Suki access token for REST, WebSocket, and related calls.

Get Started Authentication

Download OpenAPI description

Overview

Base URL

[https://sdp.suki.ai/](https://sdp.suki.ai/)

API support

[support@suki.ai](mailto:support@suki.ai) Email support

API guidelines

Languages

```bash theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}} curl -X POST https://sdp.suki.ai/api/v1/auth/login \ -H "Content-Type: application/json" \ -d '{ "partner_id": "your-partner-id", "partner_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...", "provider_id": "provider-123" }' ```

```typescript theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}} const response = await fetch("https://sdp.suki.ai/api/v1/auth/login", { method: "POST", headers: { "Content-Type": "application/json", }, body: JSON.stringify({ partner_id: "your-partner-id", partner_token: "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...", provider_id: "provider-123", // Optional }), }); if (response.ok) { const data = await response.json(); const sukiToken = data.suki_token; console.log(`Authentication successful. Token: ${sukiToken}`); } else { const error = await response.json(); console.error(`Authentication failed: ${response.status}`, error); } ```

```python theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}} import requests url = "https://sdp.suki.ai/api/v1/auth/login" payload = { "partner_id": "your-partner-id", "partner_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...", "provider_id": "provider-123" # Optional } response = requests.post(url, json=payload) if response.status_code == 200: data = response.json() suki_token = data["suki_token"] print(f"Authentication successful. Token: {suki_token}") else: print(f"Authentication failed: {response.status_code}") print(response.json()) ```

```ruby theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}} require "net/http" require "json" uri = URI("https://sdp.suki.ai/api/v1/auth/login") http = Net::HTTP.new(uri.host, uri.port) http.use_ssl = true req = Net::HTTP::Post.new(uri) req["Content-Type"] = "application/json" req.body = JSON.generate( "partner_id" => "your-partner-id", "partner_token" => "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...", "provider_id" => "provider-123" ) res = http.request(req) puts res.body ```

```java theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}} import java.net.URI; import java.net.http.HttpClient; import java.net.http.HttpRequest; import java.net.http.HttpResponse; public class LoginExample { public static void main(String[] args) throws Exception { String body = "{" + "\"partner_id\":\"your-partner-id\"," + "\"partner_token\":\"eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...\"," + "\"provider_id\":\"provider-123\"" + "}"; HttpClient client = HttpClient.newHttpClient(); HttpRequest request = HttpRequest.newBuilder() .uri(URI.create("https://sdp.suki.ai/api/v1/auth/login")) .header("Content-Type", "application/json") .POST(HttpRequest.BodyPublishers.ofString(body)) .build(); HttpResponse response = client.send(request, HttpResponse.BodyHandlers.ofString()); System.out.println(response.body()); } } ```

```php theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}} "your-partner-id", "partner_token" => "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...", "provider_id" => "provider-123", ]) ); $response = curl_exec($ch); curl_close($ch); echo $response; ```

Servers

Production host URL

[https://sdp.suki.ai](https://sdp.suki.ai)

Current API version

[https://sdp.suki.ai/api/v1](https://sdp.suki.ai/api/v1)

Confirm with your Suki partnership team for production URLs, and any host-specific routing before you go live.

Choose your API Workflow

Available APIs

Pick the APIs for your use case and workflow and start building your integration.

Ambient APIs

Use the Ambient APIs to build custom applications around clinical documentation workflows.

→

REST v1

Form Filling APIs

Use the Form Filling APIs to build custom applications around nursing and other clinical workflows.

→

REST v1

Dictation APIs

Use the Dictation APIs to transcribe audio from a patient visit and stream the transcription in real-time.

→

REST v1

Decide Your Workflow →

Start building

Ambient API Introduction Learn more about the Ambient API and how to get started.

Webhooks Introduction Learn more about the Webhooks to receive notifications from Suki.

Ambient API Quickstart Build your first ambient session and stream audio in minutes.

WebSocket APIs Stream visit audio over WebSocket for ambient and form filling sessions.

Form Filling API Introduction Learn more about the Form Filling API and how to get started.

API Guidelines Learn more about the API guidelines to help you build your integration.

Form Filling API Quickstart Build your first form-filling session and retrieve structured data in minutes.

Partner Onboarding Learn more about the partner onboarding process to start using the Suki APIs.

Stay updated

Learn about the latest updates to the Ambient, Form Filling, and Dictation APIs.

New endpoints, deprecations, and behavior notes for Ambient, and Dictation APIs. New endpoints, deprecations, and behavior notes for Form Filling APIs.

# Suki APIs Quickstarts Source: https://developer.suki.ai/api-overview/quickstarts Quickstarts for Suki APIs Get started with the Suki APIs by following the quickstarts below for your workflow of choice. Build your first ambient session, stream audio, and retrieve the note in minutes. Build your first form-filling session and retrieve structured data in minutes. Refer to the Ambient API reference to learn more about the Ambient API. Refer to the Form Filling API reference to learn more about the Form Filling API. Refer to the Dictation API reference to learn more about the Dictation API. # Ambient Content Retrieval API Source: https://developer.suki.ai/api-reference/ambient-content-retrieval Poll session status and retrieve transcripts, recordings, note content, and structured clinical data After you create and run an ambient session, use these endpoints to read processing state and to fetch artifacts: transcripts, audio, generated note text, and structured clinical payloads. Some routes are scoped to the ambient session id; others are scoped to the encounter id when content is shared across sessions for the same encounter. Make sure your session was not skipped. ## Endpoints # Get Ambient Session Content Source: https://developer.suki.ai/api-reference/ambient-content/content GET /api/v1/ambient/session/{ambient_session_id}/content Retrieve generated clinical content from completed ambient session **Updated:** You can now get the structured data blocks in the response of this API, including medication orders details. Use this endpoint to get the summary and structured data associated with the specified ambient session. This endpoint uses the `cumulative` query parameter to get the cumulative summary and structured data for the specified ambient session. If the query parameter is not provided, the default value is `false`. You have two options for the `cumulative` query parameter: Determines whether to retrieve cumulative or snapshot data. Cumulative summary and structured data up to the specified ambient session is retrieved. Snapshot summary and structured data for the specified ambient session is retrieved. **Understanding the SKIPPED Status** If you see a session with a `SKIPPED` status, it means that the clinical note was **not generated** because the conversation transcript was **empty**. This status is an expected outcome if an ambient session is started but contains no audible speech (for example, a silent recording). It does not indicate a system error. Unlike a `FAILED` status, which indicates a processing error, `SKIPPED` is a successful outcome where no action was needed. Typically filter out or ignore sessions with this status in your application's user interface. ## Code examples ```python theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}} import requests ambient_session_id = "123dfg-456dfg-789dfg-012dfg" url = f"https://sdp.suki-stage.com/api/v1/ambient/session/{ambient_session_id}/content" headers = { "sdp_suki_token": "", "sdp_provider_id": "" } # Get snapshot content (default, cumulative=false) response = requests.get(url, headers=headers, params={"cumulative": False}) if response.status_code == 200: content = response.json() print("Structured data blocks:") for block in content.get("structured_data", []) or []: print(f"\nBlock title: {block.get('title')}") data = block.get("data") or {} for key, value in data.items(): print(f" {key}: {value}") print("\nGenerated note (summary):") for section in content.get("summary", []) or []: print(f"\nTitle: {section.get('title')}") print(f"LOINC Code: {section.get('loinc_code')}") print(f"Content: {section.get('content')}") else: print(f"Failed to get content: {response.status_code}") print(response.json()) ``` ```typescript theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}} const ambientSessionId = '123dfg-456dfg-789dfg-012dfg'; // Get snapshot content (default, cumulative=false) const response = await fetch( `https://sdp.suki-stage.com/api/v1/ambient/session/${ambientSessionId}/content?cumulative=false`, { headers: { 'sdp_suki_token': '', 'sdp_provider_id': '' } } ); if (response.ok) { const content = await response.json(); console.log('Structured data blocks:'); (content.structured_data || []).forEach((block: any) => { console.log(`\nBlock title: ${block.title}`); const data = block.data || {}; Object.entries(data).forEach(([key, value]) => { console.log(` ${key}: ${value}`); }); }); console.log('\nGenerated note (summary):'); content.summary?.forEach((section: any) => { console.log(`\nTitle: ${section.title}`); console.log(`LOINC Code: ${section.loinc_code}`); console.log(`Content: ${section.content}`); }); } else { const error = await response.json(); console.error(`Failed to get content: ${response.status}`, error); } ``` # Get Ambient Encounter Content Source: https://developer.suki.ai/api-reference/ambient-content/encounter-content GET /api/v1/ambient/encounter/{encounter_id}/content Retrieve generated clinical content from completed encounter **Updated:** You can now get the medication orders for an encounter from the encounter content response. Use this endpoint to get the cumulative summary and structured data associated with the specified encounter. ## Code examples ```python theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}} import requests encounter_id = "123dfg-456dfg-789dfg-012dfg" url = f"https://sdp.suki-stage.com/api/v1/ambient/encounter/{encounter_id}/content" headers = { "sdp_suki_token": "", "sdp_provider_id": "" } response = requests.get(url, headers=headers) if response.status_code == 200: content = response.json() print("Encounter Summary:") for section in content.get("summary", []): print(f"\nTitle: {section.get('title')}") print(f"LOINC Code: {section.get('loinc_code')}") print(f"Content: {section.get('content')}") print("\nStructured Data:") for structured_block in content.get("structured_data", []): print(f"\n{structured_block.get('title')}:") # data is a key-value object data = structured_block.get('data', {}) for key, value in data.items(): print(f" {key}: {value}") else: print(f"Failed to get encounter content: {response.status_code}") print(response.json()) ``` ```typescript theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}} const encounterId = '123dfg-456dfg-789dfg-012dfg'; const response = await fetch( `https://sdp.suki-stage.com/api/v1/ambient/encounter/${encounterId}/content`, { headers: { 'sdp_suki_token': '', 'sdp_provider_id': '' } } ); if (response.ok) { const content = await response.json(); console.log('Encounter Summary:'); content.summary?.forEach((section: any) => { console.log(`\nTitle: ${section.title}`); console.log(`LOINC Code: ${section.loinc_code}`); console.log(`Content: ${section.content}`); }); console.log('\nStructured Data:'); content.structured_data?.forEach((structuredBlock: any) => { console.log(`\n${structuredBlock.title}:`); // data is a key-value object if (structuredBlock.data) { Object.entries(structuredBlock.data).forEach(([key, value]) => { console.log(` ${key}: ${value}`); }); } }); } else { const error = await response.json(); console.error(`Failed to get encounter content: ${response.status}`, error); } ``` # Get Ambient Encounter Structured Data Source: https://developer.suki.ai/api-reference/ambient-content/encounter-structured-data GET /api/v1/ambient/encounter/{encounter_id}/structured-data Retrieve structured clinical data from completed encounter **Updated:** You can now get the medication orders for an encounter from the encounter structured data endpoint. Use this endpoint to get the structured data associated with the specified encounter. ## Code examples ```python theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}} import requests encounter_id = "123dfg-456dfg-789dfg-012dfg" url = f"https://sdp.suki-stage.com/api/v1/ambient/encounter/{encounter_id}/structured-data" headers = { "sdp_suki_token": "", "sdp_provider_id": "" } response = requests.get(url, headers=headers) if response.status_code == 200: structured_data = response.json() print("Encounter Structured Data:") if "structured_data" in structured_data: diagnoses = structured_data["structured_data"].get("diagnoses", {}) if "values" in diagnoses: for diagnosis in diagnoses["values"]: print(f"Diagnosis Note: {diagnosis.get('diagnosis_note')}") # Additional diagnosis fields if diagnosis.get('laterality_indicator') is not None: print(f"Laterality Indicator: {diagnosis.get('laterality_indicator')}") if diagnosis.get('post_coord_lex_flag') is not None: print(f"Post-coordination Lexical Flag: {diagnosis.get('post_coord_lex_flag')}") # Diagnosis codes for code in diagnosis.get("codes", []): print(f" Code: {code.get('code')}") print(f" Description: {code.get('description')}") print(f" Type: {code.get('type')}") print("---") orders = structured_data["structured_data"].get("orders", {}) med_orders = orders.get("medication_orders") or {} for order in med_orders.get("values") or []: print(f"Order (submittable): {order.get('drug_name')} - {order.get('status')}") for order in med_orders.get("partial_values") or []: print(f"Order (partial): {order.get('drug_name')} - {order.get('status')}") else: print(f"Failed to get encounter structured data: {response.status_code}") print(response.json()) ``` ```typescript theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}} const encounterId = '123dfg-456dfg-789dfg-012dfg'; const response = await fetch( `https://sdp.suki-stage.com/api/v1/ambient/encounter/${encounterId}/structured-data`, { headers: { 'sdp_suki_token': '', 'sdp_provider_id': '' } } ); if (response.ok) { const structuredData = await response.json(); console.log('Encounter Structured Data:'); if (structuredData.structured_data) { const diagnoses = structuredData.structured_data.diagnoses || {}; if (diagnoses.values) { diagnoses.values.forEach((diagnosis: any) => { console.log(`Diagnosis Note: ${diagnosis.diagnosis_note}`); // Additional diagnosis fields if (diagnosis.laterality_indicator !== undefined && diagnosis.laterality_indicator !== null) { console.log(`Laterality Indicator: ${diagnosis.laterality_indicator}`); } if (diagnosis.post_coord_lex_flag !== undefined && diagnosis.post_coord_lex_flag !== null) { console.log(`Post-coordination Lexical Flag: ${diagnosis.post_coord_lex_flag}`); } // Diagnosis codes diagnosis.codes?.forEach((code: any) => { console.log(` Code: ${code.code}`); console.log(` Description: ${code.description}`); console.log(` Type: ${code.type}`); }); console.log('---'); }); } const orders = structuredData.structured_data.orders || {}; const medOrders = orders.medication_orders || {}; (medOrders.values || []).forEach((order: any) => { console.log(`Order (submittable): ${order.drug_name} - ${order.status}`); }); (medOrders.partial_values || []).forEach((order: any) => { console.log(`Order (partial): ${order.drug_name} - ${order.status}`); }); } } else { const error = await response.json(); console.error(`Failed to get encounter structured data: ${response.status}`, error); } ``` # Get Ambient Session Recording Source: https://developer.suki.ai/api-reference/ambient-content/recording GET /api/v1/ambient/session/{ambient_session_id}/recording Get presigned URLs for ambient session recordings for streaming or download Use this endpoint to get presigned URLs for all recordings for the ambient session. Refer to the [Audio streaming & download](/documentation/audio-streaming-download) guide for more details. Use the `download` query parameter to control the URL type: * If `download=true`, the URL is for downloading the **full** file. * If `download=false` or omitted, the URL supports streaming with **range** requests. ## Code examples ```python theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}} import requests ambient_session_id = "123dfg-456dfg-789dfg-012dfg" # this will be the ambient session id you get from the create ambient session API url = f"https://sdp.suki-stage.com/api/v1/ambient/session/{ambient_session_id}/recording" headers = { "sdp_suki_token": "", "sdp_provider_id": "" } # For streaming URLs (default) response = requests.get(url, headers=headers) # For download-only URLs # response = requests.get(url, headers=headers, params={"download": True}) if response.status_code == 200: data = response.json() print(f"Streamable: {data.get('is_streamable')}") for rec in data.get("recordings", []): print(f"Recording ID: {rec.get('recording_id')}") print(f"Presigned URL: {rec.get('presigned_url')}") print(f"Expires at: {rec.get('expires_at')}") print(f"Sequence: {rec.get('sequence_number')}") print("---") else: print(f"Failed to get recording URLs: {response.status_code}") print(response.json()) ``` ```typescript theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}} const ambientSessionId = '123dfg-456dfg-789dfg-012dfg'; // this will be the ambient session id you get from the create ambient session API // For streaming URLs (default) const response = await fetch( `https://sdp.suki-stage.com/api/v1/ambient/session/${ambientSessionId}/recording`, { headers: { 'sdp_suki_token': '', 'sdp_provider_id': '' } } ); // For download-only URLs, append ?download=true // const response = await fetch( // `https://sdp.suki-stage.com/api/v1/ambient/session/${ambientSessionId}/recording?download=true`, // { headers: { 'sdp_suki_token': '', 'sdp_provider_id': '' } } // ); if (response.ok) { const data = await response.json(); console.log('Streamable:', data.is_streamable); data.recordings?.forEach((rec: any) => { console.log('Recording ID:', rec.recording_id); console.log('Presigned URL:', rec.presigned_url); console.log('Expires at:', rec.expires_at); console.log('Sequence:', rec.sequence_number); console.log('---'); }); } else { const error = await response.json(); console.error(`Failed to get recording URLs: ${response.status}`, error); } ``` # Get Ambient Session Status Source: https://developer.suki.ai/api-reference/ambient-content/status GET /api/v1/ambient/session/{ambient_session_id}/status Check current status and processing state of ambient session Use this endpoint to get the **current status** of an ambient session. Use it to track the session's progress, for example, to see if it is ready to receive audio, still processing, or has completed. ## Session status values Use the following status values to track the session's progress: * **created**: The ambient session has been created but has not yet started. * **ready**: The ambient session has started and is ready for audio streaming. * **running**: The ambient session is actively processing audio and generating content. * **aborted**: The ambient session has been cancelled by the user or client. * **skipped**: The ambient session was skipped because not enough audio was received or the transcript was empty. * **failed**: The ambient session failed due to an error during processing. * **completed**: The ambient session completed successfully and generated the final content. **paused** status is no longer supported. Upon reaching **completed** state, the session is ready to return the content, transcripts, or other structured data. ## Code examples ```python theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}} import requests ambient_session_id = "123dfg-456dfg-789dfg-012dfg" url = f"https://sdp.suki-stage.com/api/v1/ambient/session/{ambient_session_id}/status" headers = { "sdp_suki_token": "", "sdp_provider_id": "" } response = requests.get(url, headers=headers) if response.status_code == 200: status_data = response.json() status = status_data.get("status") print(f"Session status: {status}") if status == "completed": print("Session completed successfully. Content is ready.") elif status == "failed": print("Session failed during processing.") elif status == "skipped": print("Session was skipped (empty transcript or too short).") else: print(f"Failed to get status: {response.status_code}") print(response.json()) ``` ```typescript theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}} const ambientSessionId = '123dfg-456dfg-789dfg-012dfg'; const response = await fetch( `https://sdp.suki-stage.com/api/v1/ambient/session/${ambientSessionId}/status`, { headers: { 'sdp_suki_token': '', 'sdp_provider_id': '' } } ); if (response.ok) { const statusData = await response.json(); const status = statusData.status; console.log(`Session status: ${status}`); if (status === 'completed') { console.log('Session completed successfully. Content is ready.'); } else if (status === 'failed') { console.log('Session failed during processing.'); } else if (status === 'skipped') { console.log('Session was skipped (empty transcript or too short).'); } } else { const error = await response.json(); console.error(`Failed to get status: ${response.status}`, error); } ``` # Get Ambient Session Structured Data Source: https://developer.suki.ai/api-reference/ambient-content/structured-data GET /api/v1/ambient/session/{ambient_session_id}/structured-data Retrieve structured clinical data from completed ambient session **Updated:** You can now get the medication orders for an ambient session from the structured data endpoint. Use this endpoint to get the cumulative structured data associated with the specified ambient session. ## Code examples ```python theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}} import requests ambient_session_id = "123dfg-456dfg-789dfg-012dfg" url = f"https://sdp.suki-stage.com/api/v1/ambient/session/{ambient_session_id}/structured-data" headers = { "sdp_suki_token": "", "sdp_provider_id": "" } response = requests.get(url, headers=headers) if response.status_code == 200: structured_data = response.json() print("Structured Data:") if "structured_data" in structured_data: diagnoses = structured_data["structured_data"].get("diagnoses", {}) if "values" in diagnoses: for diagnosis in diagnoses["values"]: print(f"Diagnosis Note: {diagnosis.get('diagnosis_note')}") # Additional diagnosis fields if diagnosis.get('laterality_indicator') is not None: print(f"Laterality Indicator: {diagnosis.get('laterality_indicator')}") if diagnosis.get('post_coord_lex_flag') is not None: print(f"Post-coordination Lexical Flag: {diagnosis.get('post_coord_lex_flag')}") # Diagnosis codes for code in diagnosis.get("codes", []): print(f" Code: {code.get('code')}") print(f" Description: {code.get('description')}") print(f" Type: {code.get('type')}") print("---") orders = structured_data["structured_data"].get("orders", {}) med_orders = orders.get("medication_orders") or {} for order in med_orders.get("values") or []: med_code = order.get("medication_code") or {} print(f"Order (submittable): {order.get('drug_name')} - {order.get('status')}") print(f" Medication code: {med_code.get('code')} ({med_code.get('type')})") print("---") for order in med_orders.get("partial_values") or []: med_code = order.get("medication_code") or {} print(f"Order (partial): {order.get('drug_name')} - {order.get('status')}") print(f" Medication code: {med_code.get('code')} ({med_code.get('type')})") print("---") else: print(f"Failed to get structured data: {response.status_code}") print(response.json()) ``` ```typescript theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}} const ambientSessionId = '123dfg-456dfg-789dfg-012dfg'; const response = await fetch( `https://sdp.suki-stage.com/api/v1/ambient/session/${ambientSessionId}/structured-data`, { headers: { 'sdp_suki_token': '', 'sdp_provider_id': '' } } ); if (response.ok) { const structuredData = await response.json(); console.log('Structured Data:'); if (structuredData.structured_data) { const diagnoses = structuredData.structured_data.diagnoses || {}; if (diagnoses.values) { diagnoses.values.forEach((diagnosis: any) => { console.log(`Diagnosis Note: ${diagnosis.diagnosis_note}`); // Additional diagnosis fields if (diagnosis.laterality_indicator !== undefined && diagnosis.laterality_indicator !== null) { console.log(`Laterality Indicator: ${diagnosis.laterality_indicator}`); } if (diagnosis.post_coord_lex_flag !== undefined && diagnosis.post_coord_lex_flag !== null) { console.log(`Post-coordination Lexical Flag: ${diagnosis.post_coord_lex_flag}`); } // Diagnosis codes diagnosis.codes?.forEach((code: any) => { console.log(` Code: ${code.code}`); console.log(` Description: ${code.description}`); console.log(` Type: ${code.type}`); }); console.log('---'); }); } const orders = structuredData.structured_data.orders || {}; const medOrders = orders.medication_orders || {}; (medOrders.values || []).forEach((order: any) => { const medCode = order.medication_code || {}; console.log(`Order (submittable): ${order.drug_name} - ${order.status}`); console.log(` Medication code: ${medCode.code} (${medCode.type})`); console.log('---'); }); (medOrders.partial_values || []).forEach((order: any) => { const medCode = order.medication_code || {}; console.log(`Order (partial): ${order.drug_name} - ${order.status}`); console.log(` Medication code: ${medCode.code} (${medCode.type})`); console.log('---'); }); } } else { const error = await response.json(); console.error(`Failed to get structured data: ${response.status}`, error); } ``` # Get Session Transcript Source: https://developer.suki.ai/api-reference/ambient-content/transcript GET /api/v1/ambient/session/{ambient_session_id}/transcript Retrieve conversation transcript from completed ambient session Use this endpoint to get the full transcript for a specified ambient session after it has completed. **Updated:** The response will now include the new `lang_id` field within the payload. The `lang_id` field indicates the language in which the transcript was sent. For a full list of language codes and their corresponding languages, refer to the [Language code reference](/api-reference/capabilities/multilingual#language-code-reference) section. ## Code examples ```python theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}} import requests ambient_session_id = "123dfg-456dfg-789dfg-012dfg" url = f"https://sdp.suki-stage.com/api/v1/ambient/session/{ambient_session_id}/transcript" headers = { "sdp_suki_token": "", "sdp_provider_id": "" } response = requests.get(url, headers=headers) if response.status_code == 200: transcript_data = response.json() print("Transcript:") for transcript in transcript_data.get("final_transcript", []): print(f"Transcript ID: {transcript.get('transcript_id')}") print(f"Recording ID: {transcript.get('recording_id')}") print(f"Language: {transcript.get('lang_id')}") print(f"Transcript: {transcript.get('transcript')}") print(f"Start Time: {transcript.get('start_time')}") print(f"End Time: {transcript.get('end_time')}") # Start offset (relative to beginning of audio) start_offset = transcript.get('start_offset', {}) if start_offset: print(f"Start Offset: {start_offset.get('hours')}h {start_offset.get('minutes')}m {start_offset.get('seconds')}s") # End offset (relative to beginning of audio) end_offset = transcript.get('end_offset', {}) if end_offset: print(f"End Offset: {end_offset.get('hours')}h {end_offset.get('minutes')}m {end_offset.get('seconds')}s") print("---") else: print(f"Failed to get transcript: {response.status_code}") print(response.json()) ``` ```typescript theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}} const ambientSessionId = '123dfg-456dfg-789dfg-012dfg'; const response = await fetch( `https://sdp.suki-stage.com/api/v1/ambient/session/${ambientSessionId}/transcript`, { headers: { 'sdp_suki_token': '', 'sdp_provider_id': '' } } ); if (response.ok) { const transcriptData = await response.json(); console.log('Transcript:'); transcriptData.final_transcript?.forEach((transcript: any) => { console.log(`Transcript ID: ${transcript.transcript_id}`); console.log(`Recording ID: ${transcript.recording_id}`); console.log(`Language: ${transcript.lang_id}`); console.log(`Transcript: ${transcript.transcript}`); console.log(`Start Time: ${transcript.start_time}`); console.log(`End Time: ${transcript.end_time}`); // Start offset (relative to beginning of audio) if (transcript.start_offset) { const { hours, minutes, seconds } = transcript.start_offset; console.log(`Start Offset: ${hours}h ${minutes}m ${seconds}s`); } // End offset (relative to beginning of audio) if (transcript.end_offset) { const { hours, minutes, seconds } = transcript.end_offset; console.log(`End Offset: ${hours}h ${minutes}m ${seconds}s`); } console.log('---'); }); } else { const error = await response.json(); console.error(`Failed to get transcript: ${response.status}`, error); } ``` # Dictation API Source: https://developer.suki.ai/api-reference/ambient-dictation Create dictation sessions, stream audio for transcription, and end sessions Use the dictation APIs when you need speech-to-text without the full ambient clinical note flow. You create a transcription session, open a WebSocket to stream audio, then end the session when capture is finished so resources can close cleanly. ## Usage scenarios * You need speech-to-text without the full ambient clinical note flow. * You want to create a transcription session, open a WebSocket to stream audio, then end the session when capture is finished so resources can close cleanly. ## How it works The dictation APIs work in four steps: Register the provider and obtain an **`sdp_suki_token`**. Refer to [Provider authentication](/api-reference/provider-authentication) and [Partner authentication](/documentation/partner-authentication). Call [Create dictation session](/api-reference/audio-transcription/create-session) and save **`transcription_session_id`**. Connect to [Stream audio to dictation session](/api-reference/audio-transcription/stream-transcription) when the session is **`READY`** or **`IDLE`**. Refer to [Dictation streaming](/documentation/dictation-streaming) for outbound audio messages and inbound transcript frames. Call [End dictation session](/api-reference/audio-transcription/end-session) when capture is finished. ## Endpoints # Ambient Session Management API Source: https://developer.suki.ai/api-reference/ambient-session-management Create and manage ambient sessions, stream audio, attach metadata, and end sessions These endpoints cover the ambient session lifecycle: create a session, set and update context, attach metadata, stream audio over WebSocket, and end the session when the recording is finished. ## Usage scenarios * Create a new ambient session for your patient encounter during in-person visits or virtual visits * Set and update session context with the patient information, provider details, and diagnosis codes * Stream audio over WebSocket to the Suki backend * End the session when the recording is finished ## Endpoints # Audio Streaming Source: https://developer.suki.ai/api-reference/ambient-sessions/audio-stream GET /ws/stream WebSocket endpoint for real-time audio streaming during ambient sessions Use this API to stream audio to the speech service over a WebSocket connection for ambient and form filling sessions. For more information on how to handle the **handshake**, **wire format**, **message order**, and **error handling**, refer to the [Ambient audio streaming](/documentation/ambient-audio-streaming) guide. ## Prerequisites Complete these steps **before** opening the WebSocket. Opening `/ws/stream` before the session and context are ready often leads to handshake failures or a broken stream. * **Authenticate** and obtain `sdp_suki_token` * **Create an ambient session** with POST [`/api/v1/ambient/session/create`](/api-reference/ambient-sessions/create). A successful create returns **201 Created**; keep the `ambient_session_id` you used or received. * **Seed session context** with POST [`/api/v1/ambient/session/{ambient_session_id}/context`](/api-reference/ambient-sessions/context). Send the JSON body your integration requires (see that endpoint for the full schema). * **Authenticate and open the WebSocket** on `wss://sdp.suki-stage.com/ws/stream`. To stream audio, you must first establish an **authenticated WebSocket connection**. The authentication method you use depends on your client types: browser or non-browser. ## Browser clients When connecting from a browser, include the `Sec-WebSocket-Protocol` header as part of the WebSocket handshake. Set the header value as a single comma-separated string. The order must be: * Subprotocol name * Ambient session ID - Your ambient session ID * Token - Your Suki token Avoid adding spaces between values unless your client library requires it. For example: ```bash theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}} Sec-WebSocket-Protocol: SukiAmbientAuth,, ``` The server negotiates this subprotocol to establish the connection. ## Non-browser clients For non-browser clients such as mobile apps, backend services, or testing tools, pass authentication details as separate HTTP headers in the WebSocket upgrade request. Do not use the `Sec-WebSocket-Protocol` header. Include the following headers: * `sdp_suki_token` - Your Suki token. * `sdp_provider_id` - Provider identifier. Optional for standard partners; **Required** for Single Auth Token authentication. * `ambient_session_id` - The ID for the current ambient session. If you push non-JSON payloads where the server expects JSON, you can see parse errors (for example invalid character or null byte errors). ## Code examples ```python theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}} # pip install websocket-client import base64 import json from datetime import datetime, timezone import websocket ambient_session_id = "" token = "" sdp_provider_id = "" # Optional; Required for Single Auth Token authentication CHUNK_BYTES = 3200 WAV_HEADER_BYTES = 44 # Non-browser: headers on upgrade. Staging WebSocket URL: ws_url = "wss://sdp.suki-stage.com/ws/stream" ws = websocket.create_connection( ws_url, header=[ f"sdp_suki_token: {token}", f"sdp_provider_id: {sdp_provider_id}", f"ambient_session_id: {ambient_session_id}", ], ) def b64(data: bytes) -> str: return base64.b64encode(data).decode("ascii") try: rfc3339 = datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ") ws.send(json.dumps({"type": "START_TIME", "data": b64(rfc3339.encode("utf-8"))})) with open("audio.wav", "rb") as f: raw = f.read() if len(raw) >= 12 and raw[:4] == b"RIFF" and raw[8:12] == b"WAVE": pcm = raw[WAV_HEADER_BYTES:] else: pcm = raw for i in range(0, len(pcm), CHUNK_BYTES): chunk = pcm[i : i + CHUNK_BYTES] ws.send(json.dumps({"type": "AUDIO", "data": b64(chunk)})) ws.send(json.dumps({"type": "AUDIO", "data": b64(b"EOF")})) while True: try: print(ws.recv()) except websocket.WebSocketConnectionClosedException: break finally: ws.close() ``` ```typescript theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}} // Browser example: same IDs as Python tab; add in your HTML. const ambientSessionId = ''; const token = ''; const CHUNK_BYTES = 3200; const WAV_HEADER_BYTES = 44; function utf8ToBase64(s: string): string { const bytes = new TextEncoder().encode(s); let binary = ''; for (let i = 0; i < bytes.length; i++) binary += String.fromCharCode(bytes[i]!); return btoa(binary); } function bytesToBase64(u8: Uint8Array): string { let binary = ''; for (let i = 0; i < u8.length; i++) binary += String.fromCharCode(u8[i]!); return btoa(binary); } // Staging WebSocket URL const ws = new WebSocket(`wss://sdp.suki-stage.com/ws/stream`, [ `SukiAmbientAuth,${ambientSessionId},${token}`, ]); ws.binaryType = 'arraybuffer'; ws.onopen = () => { const rfc3339 = new Date().toISOString().replace(/\.\d{3}Z$/, 'Z'); ws.send(JSON.stringify({ type: 'START_TIME', data: utf8ToBase64(rfc3339) })); const input = document.getElementById('audioFile') as HTMLInputElement; const file = input.files?.[0]; if (!file) return; const reader = new FileReader(); reader.onload = () => { const buf = new Uint8Array(reader.result as ArrayBuffer); let pcm = buf; if ( buf.length >= 12 && buf[0] === 0x52 && buf[1] === 0x49 && buf[2] === 0x46 && buf[3] === 0x46 && buf[8] === 0x57 && buf[9] === 0x41 && buf[10] === 0x56 && buf[11] === 0x45 ) { pcm = buf.subarray(WAV_HEADER_BYTES); } for (let i = 0; i < pcm.length; i += CHUNK_BYTES) { const chunk = pcm.subarray(i, i + CHUNK_BYTES); ws.send(JSON.stringify({ type: 'AUDIO', data: bytesToBase64(chunk) })); } ws.send( JSON.stringify({ type: 'AUDIO', data: bytesToBase64(new Uint8Array([0x45, 0x4f, 0x46])), }), ); }; reader.readAsArrayBuffer(file); }; ws.onmessage = (ev) => console.log('Received:', ev.data); ws.onerror = (e) => console.error(e); ws.onclose = () => console.log('closed'); ``` # Seed Ambient Session Context Source: https://developer.suki.ai/api-reference/ambient-sessions/context POST /api/v1/ambient/session/{ambient_session_id}/context Provide clinical context and patient information for ambient session **Updated:** You can now provide **EMR context** and **medication orders** in the ambient session context. Use this endpoint to provide or update the session context for an ambient session. Providing detailed context helps Suki generate a more accurate and relevant clinical note. For example, you can provide: * Provider details (e.g., specialty and role). * Patient and visit information. * A list of LOINC codes for the clinical sections you want to generate. * Existing diagnoses with their associated medical codes. * EMR context, including target EMR, when you need EMR-specific behavior (for example order submission rules). * Orders context (medication orders), including structured medication orders for active medications and related metadata. For more information about the context, refer to the [PBC](/api-reference/capabilities/problem-based-charting) and [Specialty](/documentation/specialties) section. For more information about medication orders, refer to the [Medication orders](/documentation/medication-orders) guide. You can use the `Codes` section to provide additional context for a session, such as **medical codes** for a **diagnosis**. To ensure your requests succeed, follow these validation rules when sending data to the API: ### Field validation and constraints * **Character Limits**: Ensure the **`chief_complaint`** and **`reason_for_visit`** fields do not exceed **255 characters**. * **Enumerated Values**: Use only the predefined string values for **`visit_type`**, **`encounter_type`**, and **`provider_role`**. * **EMR Selection**: You must set **`emr.target_emr`** to one of the following: **`ATHENA`**, **`EPIC`**, or **`CERNER`**. ### Medication order requirements When you send **`orders.medication_orders.values`**, include the following required properties for each object: * **Drug Information**: Provide both the **`drug_name`** and a **`medication_code`**. * **Coding Systems**: For **`medication_code`**, specify the **`code`** and set the **`type`** to **`RXCUI`** or **`NDC`**. * **Order Status**: Set the **`status`** to **`ACTIVE`**, **`DISCONTINUED`**, or **`REFILLED`**. * **Metadata**: Include the **`metadata`** object with a required **`origin`** of **`EMR`** or **`SUKI_AMBIENT`**. If you set **`origin`** to **`EMR`**, you must also set **`metadata.encounter_relation`** to either **`CURRENT_ENCOUNTER`** or **`PRIOR_ENCOUNTER`**. **Diagnosis links**: To link a diagnosis to an order, ensure the codes in **`linked_diagnosis_codes`** match a diagnosis already provided in the **`diagnoses`** section. Use the same coding system for both to allow the service to validate the link. ## Code examples ```python theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}} import requests ambient_session_id = "123dfg-456dfg-789dfg-012dfg" url = f"https://sdp.suki-stage.com/api/v1/ambient/session/{ambient_session_id}/context" headers = { "sdp_suki_token": "", "sdp_provider_id": "", "Content-Type": "application/json" } payload = { "provider": { "specialty": "CARDIOLOGY", "provider_role": "ATTENDING" }, "patient": { "dob": "2000-01-01", "sex": "male" }, "visit": { "chief_complaint": "Headache", "encounter_type": "AMBULATORY", "reason_for_visit": "Follow-up for migraines", "visit_type": "ESTABLISHED_PATIENT" }, "sections": [ {"loinc": "10164-2"}, {"loinc": "48765-2"} ], "diagnoses": { "values": [ { "codes": [ { "code": "I10", "description": "Essential hypertension", "type": "ICD10" } ], "diagnosis_note": "Hypertension" } ] }, "emr": { "target_emr": "EPIC" }, "orders": { "medication_orders": { "values": [ { "drug_name": "Acetaminophen 500mg Tab", "medication_code": {"code": "860975", "type": "RXCUI"}, "linked_diagnosis_codes": [ {"code": "I10", "type": "ICD10"} ], "metadata": {"origin": "SUKI_AMBIENT"}, "status": "ACTIVE", "instructions": "Take with food" } ] } } } response = requests.post(url, json=payload, headers=headers) if response.status_code == 200: print("Context seeded successfully") else: print(f"Failed to seed context: {response.status_code}") print(response.json()) ``` ```typescript theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}} const ambientSessionId = '123dfg-456dfg-789dfg-012dfg'; const response = await fetch( `https://sdp.suki-stage.com/api/v1/ambient/session/${ambientSessionId}/context`, { method: 'POST', headers: { 'sdp_suki_token': '', 'sdp_provider_id': '', 'Content-Type': 'application/json' }, body: JSON.stringify({ provider: { specialty: 'CARDIOLOGY', provider_role: 'ATTENDING' }, patient: { dob: '2000-01-01', sex: 'male' }, visit: { chief_complaint: 'Headache', encounter_type: 'AMBULATORY', reason_for_visit: 'Follow-up for migraines', visit_type: 'ESTABLISHED_PATIENT' }, sections: [ { loinc: '10164-2' }, { loinc: '48765-2' } ], diagnoses: { values: [ { codes: [ { code: 'I10', description: 'Essential hypertension', type: 'ICD10' } ], diagnosis_note: 'Hypertension' } ] }, emr: { target_emr: 'EPIC' }, orders: { medication_orders: { values: [ { drug_name: 'Acetaminophen 500mg Tab', medication_code: { code: '860975', type: 'RXCUI' }, linked_diagnosis_codes: [{ code: 'I10', type: 'ICD10' }], metadata: { origin: 'SUKI_AMBIENT' }, status: 'ACTIVE', instructions: 'Take with food' } ] } } }) } ); if (response.ok) { console.log('Context seeded successfully'); } else { const error = await response.json(); console.error(`Failed to seed context: ${response.status}`, error); } ``` # Create Ambient Session Source: https://developer.suki.ai/api-reference/ambient-sessions/create POST /api/v1/ambient/session/create Initialize a new ambient session for patient encounter documentation **Updated** The `multilingual` parameter is deprecated. Multilingual support is now **enabled by default** for all ambient sessions. You no longer need to pass this parameter. The API automatically supports conversations in multiple languages and generates the clinical note in English. Use this endpoint to create an ambient session. Suki will generate an `ambient_session_id` and return it in the response. Use the **`ambient_session_id`** to identify the session in future API calls. Many Suki APIs use this ID to perform operations such as checking session status, generating notes, retrieving transcripts, and other operations. Store the **`ambient_session_id`** after you create a session, as it is required for most session-related operations. ### Request body fields Both fields in the request body are optional. Suki generates any values you omit. | Field | Type | Description | | -------------------- | ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `ambient_session_id` | string (UUID) | Unique identifier for this ambient session. Must be a string in UUID format. If omitted, Suki generates one and returns it in the response. | | `encounter_id` | string (UUID) | Unique identifier for the patient encounter (visit). Must be a string in UUID format. Use the same `encounter_id` across multiple `session/create` calls to group several ambient sessions under the same visit. If omitted, Suki generates one. | `encounter_id` must be a **string** in UUID format. Numeric IDs from your system must be converted to a string (for example, `String(id)`) before you send them. We recommend that recordings are at least **1 minute** long. Short recordings may not contain enough information for note generation. **Important**: If the recording is too short, note generation may be **skipped**. ## Code examples ```python expandable theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}} from typing import Any, Optional, TypedDict, cast import requests BASE_URL = "https://sdp.suki-stage.com" class CreateAmbientSessionRequest(TypedDict, total=False): ambient_session_id: str encounter_id: str class CreateAmbientSessionResponse(TypedDict): ambient_session_id: str class ApiHttpError(RuntimeError): """Wrong HTTP status; OpenAPI errors usually include JSON with message + code.""" def __init__(self, status: int, url: str, detail: str) -> None: super().__init__(f"HTTP {status} {url}: {detail}") self.status = status self.url = url def _post_json_expect(url: str, headers: dict[str, str], payload: dict[str, Any], expect_status: int) -> dict[str, Any]: r = requests.post(url, json=payload, headers=headers, timeout=60) if r.status_code == expect_status: data = r.json() if isinstance(data, dict): return data raise ApiHttpError(expect_status, url, "response JSON was not an object") detail = "" try: err = r.json() if isinstance(err, dict) and isinstance(err.get("message"), str): detail = err["message"] except ValueError: detail = (r.text or "")[:500] raise ApiHttpError(r.status_code, url, detail or "(no body)") def create_ambient_session( suki_token: str, body: Optional[CreateAmbientSessionRequest] = None, ) -> CreateAmbientSessionResponse: """POST /api/v1/ambient/session/create (sdp_suki_token header required). HTTP 201.""" url = f"{BASE_URL}/api/v1/ambient/session/create" headers = {"sdp_suki_token": suki_token, "sdp_provider_id": "", "Content-Type": "application/json"} data = _post_json_expect(url, headers, dict(body or {}), 201) sid = data.get("ambient_session_id") if not isinstance(sid, str) or not sid: raise ValueError(f"{url}: 201 response missing ambient_session_id") return cast(CreateAmbientSessionResponse, {"ambient_session_id": sid}) if __name__ == "__main__": try: session = create_ambient_session( "", { # Optional UUIDs; omit to let Suki generate. "ambient_session_id": "123dfg-456dfg-789dfg-012dfg", "encounter_id": "123dfg-456dfg-789dfg-012dfg", }, ) print(session["ambient_session_id"]) except (ApiHttpError, ValueError) as e: print(e) ``` ```typescript expandable theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}} const BASE_URL = "https://sdp.suki-stage.com"; type CreateAmbientSessionRequest = { ambient_session_id?: string; encounter_id?: string; }; type CreateAmbientSessionResponse = { ambient_session_id: string }; class ApiHttpError extends Error { status: number; url: string; constructor(status: number, url: string, detail: string) { super(`HTTP ${status} ${url}: ${detail}`); this.status = status; this.url = url; } } async function postJsonExpectObject( url: string, headers: Record, body: Record, expectStatus: number ): Promise> { const res = await fetch(url, { method: "POST", headers, body: JSON.stringify(body) }); const text = await res.text(); const json = text ? JSON.parse(text) : {}; if (res.status !== expectStatus) { const msg = typeof (json as any)?.message === "string" ? (json as any).message : text?.slice(0, 500) || "(no body)"; throw new ApiHttpError(res.status, url, msg); } if (json && typeof json === "object" && !Array.isArray(json)) return json as Record; throw new ApiHttpError(res.status, url, "response JSON was not an object"); } export async function createAmbientSession( sdpSukiToken: string, body: CreateAmbientSessionRequest = {} ): Promise { const url = `${BASE_URL}/api/v1/ambient/session/create`; const data = await postJsonExpectObject( url, { sdp_suki_token: sdpSukiToken, sdp_provider_id: "", "Content-Type": "application/json" }, body as Record, 201 ); const ambientSessionId = data.ambient_session_id; if (typeof ambientSessionId !== "string" || !ambientSessionId) { throw new Error(`${url}: 201 response missing ambient_session_id`); } return { ambient_session_id: ambientSessionId }; } // Example usage const session = await createAmbientSession("", { // Optional UUIDs; omit to let Suki generate. ambient_session_id: "123dfg-456dfg-789dfg-012dfg", encounter_id: "123dfg-456dfg-789dfg-012dfg", }); console.log(session.ambient_session_id); ``` # End Ambient Session Source: https://developer.suki.ai/api-reference/ambient-sessions/end POST /api/v1/ambient/session/{ambient_session_id}/end Complete ambient session and trigger clinical note generation Use this endpoint to end an ambient session and trigger the clinical note generation process. If you get a `skipped` status, it means that the note was not generated because the conversation transcript was empty or the session was too short. ## Code examples ```python theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}} import requests ambient_session_id = "123dfg-456dfg-789dfg-012dfg" url = f"https://sdp.suki-stage.com/api/v1/ambient/session/{ambient_session_id}/end" headers = { "sdp_suki_token": "", "sdp_provider_id": "" } response = requests.post(url, headers=headers) if response.status_code == 200: print("Session ended successfully. Clinical note generation triggered.") else: print(f"Failed to end session: {response.status_code}") print(response.json()) ``` ```typescript theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}} const ambientSessionId = '123dfg-456dfg-789dfg-012dfg'; const response = await fetch( `https://sdp.suki-stage.com/api/v1/ambient/session/${ambientSessionId}/end`, { method: 'POST', headers: { 'sdp_suki_token': '', 'sdp_provider_id': '' } } ); if (response.ok) { console.log('Session ended successfully. Clinical note generation triggered.'); } else { const error = await response.json(); console.error(`Failed to end session: ${response.status}`, error); } ``` # Ambient Session Metadata Source: https://developer.suki.ai/api-reference/ambient-sessions/metadata POST /api/v1/ambient/session/{ambient_session_id}/metadata Add metadata to ambient session (deprecated; use context endpoint instead) This endpoint is `deprecated` We no longer support this endpoint. If you are using it, update your code to use the [Context](/api-reference/ambient-sessions/context) endpoint instead. That endpoint lets you set session context for an ambient session. # Update Ambient Session Context Source: https://developer.suki.ai/api-reference/ambient-sessions/update-context PATCH /api/v1/ambient/session/{ambient_session_id}/context Update existing session context with new clinical information **Updated:** You can now update the ambient session context with new **EMR context** and **medication orders**. Use this endpoint to update the session context for an ambient session. The API applies a field mask so you can send only the parts of the context you want to change. This is a **PATCH** operation that allows partial updates to the session context. ## Comparison with POST Context | Feature | POST (Seed) | PATCH (Update) | | :---------------- | ------------------------------------------------------------------ | ----------------------------------------------------------------- | | **Purpose** | Set entire context all at once when available | Incrementally build context as information becomes available | | **Data Approach** | Complete context payload | Partial context updates | | **Timing** | Before EndSession. When you have all context information together. | Before EndSession. As information becomes available progressively | | **Behavior** | Replaces entire context | Updates only specified fields | # API Reference Guidelines Source: https://developer.suki.ai/api-reference/api-guidelines Learn about the tags, indicators, and documentation standards we use in our API documentation This guide explains the **tags**, **indicators**, and **standards** we use in our API documentation. Understanding these conventions will help you navigate the reference materials more effectively and build robust integrations. ## API status tags We use the following tags next to endpoint titles to indicate their status and maturity. ### \[NEW] This tag indicates that an API endpoint has been recently added to Suki for partners. * Use this safely in production; it is fully supported and documented. * The API may receive additional non-breaking features in future updates. ### \[UPDATED] This tag indicates that an API endpoint has received significant, backward-compatible enhancements or modifications. * Look for new parameters, response fields, or behavior changes that you can implement. * Your existing integrations should continue to work without modification. ### \[DEPRECATED] This tag indicates that an API endpoint is scheduled for removal in a future version. * You should plan to migrate any existing integrations to the recommended alternatives. * Check the documentation for the specific migration timeline and replacement APIs. Suki provides migration guides to support your transition. You should avoid using this endpoint in new integrations. ### \[EARLY ACCESS] This tag indicates that an API endpoint is available for testing and feedback but may not be fully stable. * The API's behavior may change based on feedback, and breaking changes are possible before it becomes generally available. * Access to this API may require special configuration. We encourage your feedback to help us improve it. Use early access APIs with caution. The ws and webhook indicators in the API documentation indicate that an API endpoint is a WebSocket or a Webhook endpoint. ## Documentation standards ### Parameters Each parameter in an API request is clearly marked to ensure you know what is required. * **Required**: You must include these parameters in all API requests. Requests will fail without them. * **Optional**: Include these parameters to access enhanced functionality. When applicable, the documentation will note the default value used if you don't provide one. ### Examples All API endpoints include comprehensive examples to guide your implementation. * **Response examples**: You will find examples of success responses with realistic data, as well as common error responses. Each field in the response is described. * **Code examples**: You will find practical code snippets, such as `cURL` commands for direct testing and `JSON` payloads to illustrate the request and response structure. ## Using code examples in your integration Snippets in this reference (Python, TypeScript, cURL, and similar) show real paths, headers, and JSON shapes. To use them in your own systems, do the following: * **Use real credentials**: Replace placeholders (for example ``, ``, or ``) with values from your partner integration. Complete the [Partner onboarding](/documentation/partner-onboarding) flow first, then follow [Provider authentication](/api-reference/provider-authentication) for register, login, and how tokens map to API headers. Form Filling APIs follow the same authentication model; see [Form Filling authentication](/form-filling-api-reference/authentication) for that tab’s layout. * **Use the right base URL**: Examples may use a staging host (for example `https://sdp.suki-stage.com`). Use the base URL Suki gives you for each environment (staging, production, and so on). * **Keep secrets server-side**: Do not put partner tokens, JWTs, or `sdp_suki_token` in untrusted clients, public repos, or browser bundles where they can be extracted. * **Python**: Install any dependency the sample assumes (for example `requests` via `pip install requests`). Run calls from a backend service or trusted script with outbound HTTPS to Suki. * **TypeScript or JavaScript**: Run samples on the **server** using a runtime that provides **`fetch`** (for example **Node.js 18+**, Deno, or Bun). Older Node versions need another HTTP client or a `fetch` polyfill. Calling Suki **directly from a browser** usually hits **CORS** limits unless your integration is explicitly allowed; typical integrations call Suki from **your backend** or **your proxy**. * **cURL**: Use a shell with `curl` installed; pass the same headers and JSON bodies as in the docs, with real tokens and URL. ## Version management ### API versioning Our APIs follow semantic versioning principles to make updates predictable. * **Major versions (`v1`, `v2`)**: Indicate breaking changes that may require you to update your code. * **Minor versions (`v1.1`, `v1.2`)**: Introduce new features in a backward-compatible way. * **Patch versions (`v1.1.1`, `v1.1.2`)**: Include backward-compatible bug fixes and minor improvements. The following table shows which features are available in each version: | Feature | v1 | | ------------------------------- | -- | | Authentication (Login/Register) | ✓ | | Ambient session management | ✓ | | Audio streaming (WebSocket) | ✓ | | Content retrieval | ✓ | | Audio transcription | ✓ | | Multilingual support | ✓ | | Personalization | ✓ | | Problem-Based Charting (PBC) | ✓ | | Webhooks | ✓ | | User preferences | ✓ | | Form filling | ✓ | | Dictation | ✓ | ### Backward compatibility We are committed to making platform updates as smooth as possible. * We communicate breaking changes well in advance and provide migration guidance. * When we add new optional parameters, your existing integrations will not break. * Changes to the format of API responses are additive, meaning we may add new fields, but we will not remove or alter existing ones in a breaking way. ## Best practices ### Choosing the right API * **For production use**: You should use APIs that are unmarked or are tagged as `[NEW]` or `[UPDATED]`. These are stable, fully supported, and have long-term compatibility guarantees. * **For development and testing**: Consider using `[EARLY ACCESS]` APIs to preview upcoming features and provide feedback. This can help you plan for future integrations. ### Migration strategy When an API you are using is marked as `[DEPRECATED]`, we recommend the following process: 1. **Assess impact**: Review your current usage of the deprecated endpoint. 2. **Plan timeline**: Check the deprecation timeline in the documentation and plan your migration. 3. **Test alternatives**: Implement and test the recommended replacement API. 4. **Migrate**: Update your integration in phases to minimize disruption. ### Getting help For questions about API status, migration timelines, or implementation guidance, please contact our **customer success team**. Read the [API changelog](/api-reference/product-updates/changelog) section for the latest updates and changes to the APIs. ## Next steps Use the following API to get started with the Suki Platform: Learn about the Ambient API Learn about the Form Filling API Learn about the Dictation API # Asynchronous Notifications Source: https://developer.suki.ai/api-reference/asynchronous/webhook POST /webhooks/notification Webhook endpoint for receiving asynchronous notifications from Suki platform Use this endpoint specification to implement a webhook endpoint in your application that receives notifications from the Suki platform. This endpoint should be hosted by your application to receive notifications about session completion or failure. Learn more about how webhooks work and how to implement your own webhook endpoint to receive them in the [Notification webhook for partners](/documentation/webhook/overview) documentation. ## Code examples ```python theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}} from flask import Flask, request, jsonify app = Flask(__name__) @app.route('/webhooks/notification', methods=['POST']) def handle_webhook(): """ Webhook endpoint to receive notifications from Suki platform. This endpoint should be hosted by your application. """ # The payload is received in the request body from Suki data = request.get_json() # This is the payload sent by Suki if not data: return jsonify({"error": "Invalid request"}), 400 status = data.get("status") if status == "success": # Handle success notification session_id = data.get("session_id") encounter_id = data.get("encounter_id") sessions = data.get("sessions", []) additional_info = data.get("additional_info") print(f"Session {session_id} completed successfully") print(f"Encounter ID: {encounter_id}") print(f"Total sessions: {len(sessions)}") if additional_info: print(f"Additional info: {additional_info}") # Access links to retrieve content if "_links" in data: links = data["_links"] print("Available links:") # contents is an array of Link objects if "contents" in links: print(" Session contents:") for link in links["contents"]: print(f" {link.get('method')} {link.get('href')} - {link.get('name')}") # encounter_content is an array of Link objects if "encounter_content" in links: print(" Encounter content:") for link in links["encounter_content"]: print(f" {link.get('method')} {link.get('href')} - {link.get('name')}") # transcripts is an array of Link objects if "transcripts" in links: print(" Transcripts:") for link in links["transcripts"]: print(f" {link.get('method')} {link.get('href')} - {link.get('name')}") # status is an array of Link objects if "status" in links: print(" Status:") for link in links["status"]: print(f" {link.get('method')} {link.get('href')} - {link.get('name')}") return jsonify({"message": "Notification received"}), 200 elif status == "failure": # Handle failure notification session_id = data.get("session_id") encounter_id = data.get("encounter_id") error_code = data.get("error_code") error_detail = data.get("error_detail") print(f"Session {session_id} failed") print(f"Encounter ID: {encounter_id}") print(f"Error Code: {error_code}") print(f"Error Detail: {error_detail}") return jsonify({"message": "Failure notification received"}), 200 else: return jsonify({"error": "Unknown status"}), 400 if __name__ == '__main__': app.run(port=3000) ``` ```typescript theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}} import express from 'express'; const app = express(); app.use(express.json()); app.post('/webhooks/notification', (req, res) => { /** * Webhook endpoint to receive notifications from Suki platform. * This endpoint should be hosted by your application. */ // The payload is received in the request body from Suki const data = req.body; // This is the payload sent by Suki if (!data) { return res.status(400).json({ error: 'Invalid request' }); } const status = data.status; if (status === 'success') { // Handle success notification const sessionId = data.session_id; const encounterId = data.encounter_id; const sessions = data.sessions || []; const additionalInfo = data.additional_info; console.log(`Session ${sessionId} completed successfully`); console.log(`Encounter ID: ${encounterId}`); console.log(`Total sessions: ${sessions.length}`); if (additionalInfo) { console.log(`Additional info:`, additionalInfo); } // Access links to retrieve content if (data._links) { const links = data._links; console.log('Available links:'); // contents is an array of Link objects if (links.contents) { console.log(' Session contents:'); links.contents.forEach((link: any) => { console.log(` ${link.method} ${link.href} - ${link.name}`); }); } // encounter_content is an array of Link objects if (links.encounter_content) { console.log(' Encounter content:'); links.encounter_content.forEach((link: any) => { console.log(` ${link.method} ${link.href} - ${link.name}`); }); } // transcripts is an array of Link objects if (links.transcripts) { console.log(' Transcripts:'); links.transcripts.forEach((link: any) => { console.log(` ${link.method} ${link.href} - ${link.name}`); }); } // status is an array of Link objects if (links.status) { console.log(' Status:'); links.status.forEach((link: any) => { console.log(` ${link.method} ${link.href} - ${link.name}`); }); } } return res.status(200).json({ message: 'Notification received' }); } else if (status === 'failure') { // Handle failure notification const sessionId = data.session_id; const encounterId = data.encounter_id; const errorCode = data.error_code; const errorDetail = data.error_detail; console.log(`Session ${sessionId} failed`); console.log(`Encounter ID: ${encounterId}`); console.log(`Error Code: ${errorCode}`); console.log(`Error Detail: ${errorDetail}`); return res.status(200).json({ message: 'Failure notification received' }); } else { return res.status(400).json({ error: 'Unknown status' }); } }); app.listen(3000, () => { console.log('Webhook server listening on port 3000'); }); ``` # Create Dictation Session Source: https://developer.suki.ai/api-reference/audio-transcription/create-session POST /api/v1/transcription/session/create Creates a new transcription session for real-time audio transcription Use this endpoint to create a dictation session to transcribe audio from patient-provider conversations into text. Refer to the [Audio dictation guide](/documentation/dictation) for more information. Returns a `201 Created` status with the `transcription_session_id` that is used to identify the session for transcribing audio and ending the session. # End Dictation Session Source: https://developer.suki.ai/api-reference/audio-transcription/end-session POST /api/v1/transcription/session/{transcription_session_id}/end Ends an active transcription session and returns the final transcription results Use this endpoint to end an active dictation session and retrieve the final transcription results. This endpoint stops the audio streaming and returns the complete transcript along with session metadata. Returns a `200 OK` status with success message. # Stream Audio To Dictation Session Source: https://developer.suki.ai/api-reference/audio-transcription/stream-transcription GET /ws/transcribe Establishes a WebSocket connection to the transcription service for real-time audio streaming and transcription. Open only when the dictation session is READY or IDLE. Inbound frames use TranscriptionStreamResponse (partial and final transcripts, then a terminal EOF frame) Use this WebSocket endpoint to stream audio to an active dictation session for **real-time transcription**. For the complete workflow, **usage guidelines**, **wire format**, **message order**, and **error handling**, refer to the [Audio dictation](/documentation/dictation) and [Dictation streaming](/documentation/dictation-streaming) guides. * For a single guide that compares **`/ws/stream`** and **`/ws/transcribe`** (handshake, proxy behavior, and message shapes), refer to [Audio streaming](/documentation/audio-stream) guide. * Stream audio in **chunks** for the best latency and throughput. * For partial and final inbound transcript frames, **`EOF`**, and session state rules, refer to [Dictation streaming](/documentation/dictation-streaming). If the dictation session is **`RUNNING`**, **`COMPLETED`**, or in another state, the WebSocket handshake fails with **`FailedPrecondition`** (for example **transcript session is not accepting new speech sessions**). ## Inbound transcript messages The server sends **JSON text frames** that include `transcript`, `is_final`, and `transcript_id`. Use `is_final` to identify whether the transcript is a partial result or a final result. After the audio stream ends, the server sends `{ "transcript": { "transcript": "EOF" } }` and then closes the WebSocket connection. Refer to [Dictation streaming](/documentation/dictation-streaming) for frame examples, **`words`** and speaker IDs on finals, and client-side filtering rules. ## Authentication Authentication is applied during the WebSocket handshake. The method depends on your client type. Use `Sec-WebSocket-Protocol` header for browser clients, and `sdp_suki_token` and `transcription_session_id` headers for non-browser clients. ### Browser clients If you are connecting from a browser, you must use the `Sec-WebSocket-Protocol` header during the WebSocket handshake. The header must specify the `SukiAmbientAuth` protocol, followed by the **token** and the **transcription session ID** in the following format. ```bash theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}} Sec-WebSocket-Protocol: SukiAmbientAuth,, ``` ### Non-browser clients If you are connecting from a non-browser client, such as a mobile or server-side application, you must provide the **token** and **session ID** as separate HTTP headers in the initial WebSocket upgrade request. * `sdp_suki_token`: Your Suki token. * `sdp_provider_id`: Provider identifier. Optional for standard partners; **Required** for Single Auth Token authentication. * `transcription_session_id`: The ID for the current session. Important: * All messages must be sent as **JSON text** frames over the WebSocket connection. * Do not send raw binary data or use HTTP endpoints for streaming audio. ## Code examples ```python theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}} # pip install websocket-client import base64 import json import websocket # Replace with values from Create dictation session and your authentication flow. transcription_session_id = "" sdp_suki_token = "" sdp_provider_id = "" # Optional; Required for Single Auth Token authentication # Staging WebSocket URL ws_url = "wss://sdp.suki-stage.com/ws/transcribe" ws = websocket.create_connection( ws_url, header=[ f"sdp_suki_token: {sdp_suki_token}", f"sdp_provider_id: {sdp_provider_id}", f"transcription_session_id: {transcription_session_id}", ], ) # If the file is WAV, skip the 44-byte header so payloads are PCM_S16LE only. WAV_HEADER_BYTES = 44 CHUNK_BYTES = 3200 # Example chunk size; size your chunks to your capture pipeline. try: with open("audio.wav", "rb") as audio_file: if WAV_HEADER_BYTES: audio_file.read(WAV_HEADER_BYTES) chunk = audio_file.read(CHUNK_BYTES) while chunk: msg = { "type": "AUDIO", "audioData": base64.b64encode(chunk).decode("ascii"), } ws.send(json.dumps(msg)) chunk = audio_file.read(CHUNK_BYTES) ws.send(json.dumps({"type": "EVENT", "event": "AUDIO_END"})) finally: ws.close() ``` ```typescript theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}} // Browser example: same IDs as Python tab; add in your HTML. const transcriptionSessionId = ''; const sdpSukiToken = ''; // Staging WebSocket URL const ws = new WebSocket('wss://sdp.suki-stage.com/ws/transcribe', [ `SukiAmbientAuth,${sdpSukiToken},${transcriptionSessionId}`, ]); function uint8ToBase64(bytes: Uint8Array): string { let binary = ''; for (let i = 0; i < bytes.byteLength; i += 1) { binary += String.fromCharCode(bytes[i]!); } return btoa(binary); } ws.onopen = () => { const input = document.getElementById('audioFile') as HTMLInputElement | null; const file = input?.files?.[0]; if (!file) { console.error('Select a file for #audioFile'); ws.close(); return; } const reader = new FileReader(); reader.onload = () => { const buffer = reader.result as ArrayBuffer; const wavHeaderBytes = 44; // Set to 0 if the file is already raw PCM. const pcm = new Uint8Array(buffer, wavHeaderBytes); const chunkSize = 3200; for (let offset = 0; offset < pcm.byteLength; offset += chunkSize) { const end = Math.min(offset + chunkSize, pcm.byteLength); const chunk = pcm.subarray(offset, end); ws.send( JSON.stringify({ type: 'AUDIO', audioData: uint8ToBase64(chunk), }), ); } ws.send(JSON.stringify({ type: 'EVENT', event: 'AUDIO_END' })); }; reader.readAsArrayBuffer(file); }; ws.onmessage = (event) => { const payload = JSON.parse(event.data as string); if (payload.transcript?.transcript === 'EOF') { console.log('End of transcription stream'); return; } console.log('Partial:', !payload.is_final, payload.transcript?.transcript); }; ``` # Authentication API Source: https://developer.suki.ai/api-reference/authentication Learn how to register providers, obtain tokens, and retrieve JSON Web Key Set (JWKS) material for the Suki platform The authentication APIs provide the primary endpoints for connecting partners and providers to the Suki Developer Platform. Designed for security and integration, these endpoints allow you to manage user identities and secure your connection to our API gateway. ## Usage scenarios * Onboard a provider with your partner organization * Obtain a **Suki token** for a registered provider also known as a **`sdp_suki_token`** * Fetch the current **JSON Web Key Set** ## What happens when you call the endpoints * **Register** creates a new user and links it to your partner organization * **Login** exchanges your partner credentials for a **Suki token** also known as a **`sdp_suki_token`** * **JWKS** returns the current **JSON Web Key Set** ## Endpoints # JWKS URL Source: https://developer.suki.ai/api-reference/authentication/jwks GET /api/auth/.well-known/jwks-pub.json Public key endpoint for JWT token verification and signature validation Use this public endpoint to get the JWKS (JSON Web Key Set) containing Suki's public keys. Use these keys to verify the signature of any JWT issued by Suki, such as the `suki_token`. This endpoint follows the **RFC 7517** standard. **Authentication** This is a public endpoint and does not require authentication. ## Key use cases * **Verify Tokens**: Confirm the authenticity of the `suki_token` you receive from our authentication API. * **Handle Key Rotation**: Automatically discover new public keys when Suki rotates its signing keys. * **Maintain Security**: Follow industry best practices for JWT validation. ## Code examples ```python theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}} import requests url = "https://sdp.suki-stage.com/api/auth/.well-known/jwks-pub.json" response = requests.get(url) if response.status_code == 200: jwks = response.json() print("Public keys retrieved successfully") print(f"Keys: {jwks}") else: print(f"Failed to retrieve JWKS: {response.status_code}") ``` ```typescript theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}} const response = await fetch('https://sdp.suki-stage.com/api/auth/.well-known/jwks-pub.json'); if (response.ok) { const jwks = await response.json(); console.log('Public keys retrieved successfully'); console.log('Keys:', jwks); } else { console.error(`Failed to retrieve JWKS: ${response.status}`); } ``` # Login Source: https://developer.suki.ai/api-reference/authentication/login POST /api/v1/auth/login Authenticate healthcare provider and obtain access token for API usage Use this endpoint to authenticate a provider. On a successful request, this endpoint returns a Suki Token (`suki_token`/`sdp_suki_token`) that you must use to authorize all subsequent API calls for that user. The `suki_token` is a JWT that is valid for **one hour**. It contains the **user**, **organization**, and Partner information needed to access Suki services. If you are using the JWT Bearer/Assertion authentication method, the response may also include an additional `jwt_bearer` field. ## Code examples ```python theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}} import requests url = "https://sdp.suki-stage.com/api/v1/auth/login" payload = { "partner_id": "your-partner-id", "partner_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...", "provider_id": "provider-123" # Optional } response = requests.post(url, json=payload) if response.status_code == 200: data = response.json() suki_token = data["suki_token"] print(f"Authentication successful. Token: {suki_token}") else: print(f"Authentication failed: {response.status_code}") print(response.json()) ``` ```typescript theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}} const response = await fetch('https://sdp.suki-stage.com/api/v1/auth/login', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ partner_id: 'your-partner-id', partner_token: 'eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...', provider_id: 'provider-123' // Optional }) }); if (response.ok) { const data = await response.json(); const sukiToken = data.suki_token; console.log(`Authentication successful. Token: ${sukiToken}`); } else { const error = await response.json(); console.error(`Authentication failed: ${response.status}`, error); } ``` # Register Source: https://developer.suki.ai/api-reference/authentication/register POST /api/v1/auth/register Register new healthcare provider or link existing provider to partner organization Use this endpoint to register a **new healthcare provider** in the Suki platform or to link an **existing provider** to a new **Partner**-organization relationship. This is a **one-time** setup call for each provider within an organization. ## Registration scenarios This endpoint handles **three** different scenarios depending on the user's status in the Suki system. | Scenario | Condition | Actions Taken | Response | | --------------------------------- | ------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- | ------------ | | **New User** | The provider does not exist in Suki. | • Creates a new organization
• Links your partner account to the organization
• Creates a new user with the provided details | 201 Created | | **Existing User, New Link** | The provider exists but is not yet linked to your partner account. | • Verifies the user and organization details
• Links your partner account to the existing organization | 201 Created | | **Existing User, Already Linked** | The provider and organization are already linked to your partner account. | • Detects the existing link | 409 Conflict | ## Code examples ```python theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}} import requests url = "https://sdp.suki-stage.com/api/v1/auth/register" payload = { "partner_id": "your-partner-id", "partner_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...", "provider_name": "Dr. John Smith", "provider_org_id": "org-123", "provider_id": "provider-123", # Optional "provider_specialty": "CARDIOLOGY" # Optional, defaults to FAMILY_MEDICINE } response = requests.post(url, json=payload) if response.status_code == 201: print("Provider registered successfully") elif response.status_code == 409: print("Provider already linked to this partner") else: print(f"Registration failed: {response.status_code}") print(response.json()) ``` ```typescript theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}} const response = await fetch('https://sdp.suki-stage.com/api/v1/auth/register', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ partner_id: 'your-partner-id', partner_token: 'eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...', provider_name: 'Dr. John Smith', provider_org_id: 'org-123', provider_id: 'provider-123', // Optional provider_specialty: 'CARDIOLOGY' // Optional, defaults to FAMILY_MEDICINE }) }); if (response.status === 201) { console.log('Provider registered successfully'); } else if (response.status === 409) { console.log('Provider already linked to this partner'); } else { const error = await response.json(); console.error(`Registration failed: ${response.status}`, error); } ``` # Bearer Partner Type Authentication Source: https://developer.suki.ai/api-reference/bearer-partner-authentication Learn how Bearer partner authentication works, when to pass provider_id, and how to integrate with REST APIs Some partners cannot include per-user identity information in the OAuth 2.0 token they send to Suki. During onboarding, Suki configures these organizations as **Bearer partners**. Bearer partners authenticate the same way as other server-to-server partners. Send `partner_token` in the JSON request body for [Login](/api-reference/authentication/login) and [Register](/api-reference/authentication/register). Because the token is shared across providers, Bearer partners must also send `provider_id` in every Login and Register request so Suki can identify the active provider. **Important:** Suki assigns your partner type during onboarding. If you are not sure whether your organization is configured as a Bearer partner, contact your partnership team. This guide applies only to Bearer partners. It does not apply to partners that use a per-user ID token or user-scoped access token as partner\_token. ## Prerequisites Before you implement Bearer partner authentication, confirm the following: * **Bearer partner configuration** - Your Suki partner contact confirms that your organization is configured as a Bearer partner. * **Provider ID format** - You and Suki agree on a stable provider identifier format, such as an email address or external user ID. Use the same format on every login and register call. * **HTTPS required** - Send [Login](/api-reference/authentication/login) and [Register](/api-reference/authentication/register) requests as HTTPS POST requests with a JSON body. Do not send credentials in query parameters. ## Use cases Use Bearer partner authentication when your integration matches one of these scenarios: Your backend uses a single shared `partner_token` for multiple clinicians, and the token does not identify the signed-in provider. Send `provider_id` on every [Login](/api-reference/authentication/login) and [Register](/api-reference/authentication/register) request so Suki can identify the correct provider. Your application already knows the signed-in provider, such as through a session or database record, but you cannot include that identity in the `partner_token`. Instead, send a stable identifier as `provider_id` in the authentication request body. Your identity provider does not issue a per-user ID token for Suki, or you cannot add user claims to the access token. Bearer partner authentication lets you keep your existing token model and identify the provider by using `provider_id`. Diagram: Tenant A, Tenant B, and Tenant C connect through shared partner tokens, then to the Suki platform.

Diagram: Tenant A, Tenant B, and Tenant C connect through shared partner tokens, then to the Suki platform.

## How Bearer partners differ from other partners | Topic | Standard partner authentication | Bearer partner authentication | | :--------------------------------- | :------------------------------------- | :------------------------------------------------------ | | User identity source | Derived from `partner_token` | Passed as `provider_id` in the request body | | `partner_token` type | Per-user ID token or user-scoped token | Typically one shared `partner_token` for many providers | | `provider_id` on login or register | Optional and ignored | Required | In Bearer partner authentication, the partner application provides the provider identity on behalf of the signed-in user. This is different from the HTTP `Authorization: Bearer` header format. You still send `partner_token` in the JSON request body for login and register requests. ## Authentication workflow For Bearer partners, Suki validates `partner_id` and `provider_id` on [Login](/api-reference/authentication/login). If the provider is not registered, call [Register](/api-reference/authentication/register), then call Login again. The flow matches standard partners after registration. Learn more about registration scenarios in [Provider authentication](/api-reference/provider-authentication#registration-scenarios). ## Login and Register request fields Bearer partners use the same login and register endpoints as standard partners. You must include `provider_id` on every login and register call. ### Login **Endpoint:** [Login](/api-reference/authentication/login) **Method:** POST | Field | Bearer partners | | :-------------- | :------------------------------------------------------------------------------------------------------------------------------------ | | `partner_id` | Required. Partner ID from Suki. | | `partner_token` | Required. Shared `partner_token` your integration uses for authentication. | | `provider_id` | Required. Stable identifier for the provider in your system. Must match the format agreed with Suki during onboarding. | #### Example request ```bash cURL theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}} curl -X POST https://sdp.suki-stage.com/api/v1/auth/login \ -H "Content-Type: application/json" \ -d '{ "partner_id": "your-partner-id", "partner_token": "your-shared-partner-token", "provider_id": "provider-123" }' ``` On success, the API returns `suki_token`. Use it as the `sdp_suki_token` header on later Ambient API calls. The token is valid for **1 hour**. To refresh it, call Login again with a valid `partner_token`. ### Register Register a provider once before their first login. Refer to [Provider authentication](/api-reference/provider-authentication#registration-scenarios) for new user, existing user, and conflict responses. **Endpoint:** [Register](/api-reference/authentication/register) **Method:** POST | Field | Bearer partners | | :------------------- | :--------------------------------------------------------------------------------------------------------------------------- | | `partner_id` | Required. Partner ID from Suki. | | `partner_token` | Required. Shared `partner_token` your integration uses for authentication. | | `provider_id` | Required. Stable identifier for the provider in your system. Use this as the user identifier at registration. | | `provider_name` | Required. Display name for the provider. | | `provider_org_id` | Required. Organization the provider belongs to. | | `provider_specialty` | Optional. Defaults to `FAMILY_MEDICINE` if omitted. | #### Example request ```bash cURL theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}} curl -X POST https://sdp.suki-stage.com/api/v1/auth/register \ -H "Content-Type: application/json" \ -d '{ "partner_id": "your-partner-id", "partner_token": "your-shared-partner-token", "provider_id": "provider-123", "provider_name": "Dr. Jane Smith", "provider_org_id": "org-123" }' ``` For all Register fields and response codes, refer to the [Register API reference](/api-reference/authentication/register). **Security considerations** If an attacker gets your shared `partner_token` and a valid `provider_id`, they could try to impersonate a provider. To reduce risk: * Allow only trusted systems to call the login and register endpoints. * Monitor for suspicious or unexpected authentication activity. * Rotate shared `partner_token` values regularly when your identity provider allows it. # Multilingual Support Source: https://developer.suki.ai/api-reference/capabilities/multilingual Multi-language support for ambient sessions and clinical documentation

Quick summary

Multilingual support lets patients and providers speak in their preferred language during clinical conversations, while Suki automatically generates the final clinical note in English.

Last updated: June 2026

**Multilingual support is supported by:** Ambient APIs, Mobile SDK, Web SDK (v2.1.1+) Multilingual support lets patients and providers speak in their preferred language during clinical conversations, while Suki automatically generates the final clinical note in English. This removes the need for manual translation and makes healthcare more accessible to diverse patient populations. When you enable multilingual support for an ambient session, you get the following benefits: * **Patient comfort**: Patients can communicate in their native language, leading to more accurate information sharing * **Better care quality**: When patients speak in their preferred language, they provide more detailed and accurate information * **No translation needed**: Clinicians don't need to translate conversations manually, Suki handles it automatically * **EHR compatibility**: All notes are generated in English, ensuring compatibility with standard EHR systems * **Wider accessibility**: Support for 80+ languages makes healthcare more inclusive ## How it works When you enable multilingual support for an ambient session, Suki automatically: 1. **Detects the language** spoken during the conversation 2. **Transcribes the audio** in the detected language 3. **Translates and processes** the conversation content 4. **Generates the clinical note** in English The transcript API returns a `lang_id` field that identifies which language was detected for each segment of the conversation. This helps you understand what language was spoken during different parts of the session. ## How to enable multilingual support Enable multilingual support when creating an ambient session. The exact method depends on whether you're using the Mobile SDK or APIs. **Mobile SDK Example:** ```swift Swift theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}} let sessionContext = [ SukiAmbientConstant.kSessionId: encounterId, SukiAmbientConstant.kMultilingual: true // Enable multilingual support ] as [String : AnyHashable] SukiAmbientCoreManager.shared.createSession( with: sessionContext, onCompletion: { result in switch result { case .success(let sessionResponse): let sessionId = sessionResponse.sessionId // Store sessionId for future use case .failure(let error): // Handle error } } ) ``` **API Example:** ```python Python theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}} payload = { "ambient_session_id": "123dfg-456dfg-789dfg-012dfg", # Optional "encounter_id": "123dfg-456dfg-789dfg-012dfg", # Optional "multilingual": false # [!code --] Deprecated in v1.1.1 } response = requests.post( "https://sdp.suki-stage.com/api/v1/ambient/session/create", json=payload, headers={"sdp_suki_token": "", "sdp_provider_id": ""} ) ``` For complete API documentation, see the [Create ambient session API](/api-reference/ambient-sessions/create). Multilingual support is **enabled by default** for all ambient sessions The `multilingual` parameter is deprecated. You no longer need to pass it when creating a session. Once active, it applies to the entire session and cannot be changed mid-session. ## Supported languages Suki supports over **80 languages** for ambient sessions. The following languages are currently supported: | | | | | | | ------------------- | ------------------ | ----------- | ------------- | --------- | | Spanish | Norwegian | Macedonian | Kazakh | Yoruba | | Italian | Finnish | Hungarian | Icelandic | Telugu | | English | Vietnamese | Tamil | Marathi | Khmer | | Portuguese | Thai | Hindi | Maori | Malayalam | | German | Slovak | Estonian | Swahili | Lao | | Japanese | Greek | Urdu | Armenian | Punjabi | | Polish | Czech | Latvian | Belarusian | Gujarati | | Russian | Croatian | Slovenian | Nepali | Somali | | Dutch | Danish | Azerbaijani | Occitan | Bengali | | Indonesian | Tagalog | Hebrew | Lingala | Georgian | | Catalan | Korean | Lithuanian | Maltese | Assamese | | French | Romanian | Persian | Tajik | Mongolian | | Turkish | Bulgarian | Welsh | Luxembourgish | Myanmar | | Swedish | Galician | Serbian | Hausa | Shona | | Ukrainian | Bosnian | Afrikaans | Uzbek | Amharic | | Malay | Arabic | Kannada | Pashto | Sindhi | | Chinese (Cantonese) | Chinese (Mandarin) | | | | ## Language code reference Pick a **Letter** below to show languages starting with that letter, then use the table to map each `lang_id` to its corresponding language. This helps you interpret the language codes returned by the Transcript API. We regularly update this list as we add support for new languages. If a language is not included in this table, it is not yet supported.

**A** | Language | Language ID (`lang_id`) | | ----------- | ----------------------- | | afrikaans | af | | amharic | am | | arabic | ar | | armenian | hy | | assamese | as | | azerbaijani | az |

**B** | Language | Language ID (`lang_id`) | | ---------- | ----------------------- | | belarusian | be | | bengali | bn | | bosnian | bs | | bulgarian | bg |

**C** | Language | Language ID (`lang_id`) | | ------------------ | ----------------------- | | catalan | ca | | chinese | zh | | chinese\_cantonese | yue | | chinese\_mandarin | cmn | | croatian | hr | | czech | cs |

**D** | Language | Language ID (`lang_id`) | | -------- | ----------------------- | | danish | da | | dutch | nl |

**E** | Language | Language ID (`lang_id`) | | -------- | ----------------------- | | english | en | | estonian | et |

**F** | Language | Language ID (`lang_id`) | | -------- | ----------------------- | | finnish | fi | | french | fr |

**G** | Language | Language ID (`lang_id`) | | -------- | ----------------------- | | galician | gl | | georgian | ka | | german | de | | greek | el | | gujarati | gu |

**H** | Language | Language ID (`lang_id`) | | --------- | ----------------------- | | hausa | ha | | hebrew | he | | hindi | hi | | hungarian | hu |

**I** | Language | Language ID (`lang_id`) | | ---------- | ----------------------- | | icelandic | is | | indonesian | id | | italian | it |

**J** | Language | Language ID (`lang_id`) | | -------- | ----------------------- | | japanese | ja |

**K** | Language | Language ID (`lang_id`) | | -------- | ----------------------- | | kannada | kn | | kazakh | kk | | khmer | km | | korean | ko |

**L** | Language | Language ID (`lang_id`) | | ------------- | ----------------------- | | lao | lo | | latvian | lv | | lingala | ln | | lithuanian | lt | | luxembourgish | lb |

**M** | Language | Language ID (`lang_id`) | | ---------- | ----------------------- | | macedonian | mk | | malay | ms | | malayalam | ml | | maltese | mt | | maori | mi | | marathi | mr | | mongolian | mn | | myanmar | my |

**N** | Language | Language ID (`lang_id`) | | --------- | ----------------------- | | nepali | ne | | norwegian | no |

**O** | Language | Language ID (`lang_id`) | | -------- | ----------------------- | | occitan | oc |

**P** | Language | Language ID (`lang_id`) | | ---------- | ----------------------- | | pashto | ps | | persian | fa | | polish | pl | | portuguese | pt | | punjabi | pa |

**R** | Language | Language ID (`lang_id`) | | -------- | ----------------------- | | romanian | ro | | russian | ru |

**S** | Language | Language ID (`lang_id`) | | --------- | ----------------------- | | serbian | sr | | shona | sn | | sindhi | sd | | slovak | sk | | slovenian | sl | | somali | so | | spanish | es | | swahili | sw | | swedish | sv |

**T** | Language | Language ID (`lang_id`) | | -------- | ----------------------- | | tagalog | tl | | tajik | tg | | tamil | ta | | telugu | te | | thai | th | | turkish | tr |

**U** | Language | Language ID (`lang_id`) | | --------- | ----------------------- | | ukrainian | uk | | urdu | ur | | uzbek | uz |

**V** | Language | Language ID (`lang_id`) | | ---------- | ----------------------- | | vietnamese | vi |

**W** | Language | Language ID (`lang_id`) | | -------- | ----------------------- | | welsh | cy |

**Y** | Language | Language ID (`lang_id`) | | -------- | ----------------------- | | yoruba | yo |

## Best practices * **Enable when needed**: Only enable multilingual support when you expect conversations in multiple languages. This optimizes performance. * **Set patient language preference**: If you know the patient's preferred language, you can display this information in your UI to help providers prepare. * **Monitor language detection**: Use the `lang_id` from transcripts to understand language usage patterns in your application. * **Test with your languages**: Verify multilingual support works correctly with the languages your patients commonly use. * **Note language in UI**: Consider displaying the detected language in your UI so providers know what language was spoken. ## Related APIs Use these APIs to work with multilingual support: Retrieve transcripts with language detection information (`lang_id`) Create ambient sessions with multilingual support enabled # Personalization Source: https://developer.suki.ai/api-reference/capabilities/personalization Customize clinical note generation based on provider preferences and specialty

Quick summary

Personalization allows you to customize how Suki generates clinical notes based on each provider's preferences. Control how much detail (short and concise, balanced, or very detailed) and how it's formatted (continuous paragraphs or bullet points).

Last updated: June 2026

**Personalization is supported by:** APIs, Web SDK, Mobile SDK Personalization allows you to help providers customize how Suki generates their clinical notes. Every provider has different preferences, some want short bullet points, others want detailed paragraphs. Personalization ensures each provider gets notes that match their style. When you use personalization, you can customize two aspects of note generation: * **How much detail**: Short and concise, balanced, or very detailed notes * **How it's formatted**: Continuous paragraphs (narrative) or bullet points Once you set a provider's preferences, Suki automatically applies them to all future notes for that provider. You set it once, and Suki remembers, no need to send preferences with every request. Using personalization, you get the following benefits: * **Provider satisfaction**: Notes match each provider's preferred style and level of detail * **Consistent documentation**: Once set, preferences apply automatically to all future notes * **Efficiency**: Providers don't need to manually adjust notes; they're generated according to their preferences * **Flexibility**: Different providers can have different preferences based on their specialty and workflow * **Better adoption**: When notes match provider preferences, they're more likely to use and trust the system ## How it works Personalization settings are saved at the user level, not per session. Once you set a provider's preferences, Suki automatically applies them to all future note generation for that provider. **The process:** 1. **Set preferences**: Use the Mobile SDK `setPersonalizationPreferences` method or the User Preferences API to configure a provider's preferences 2. **Automatic application**: Suki applies these settings to all future notes for that provider 3. **Update anytime**: Update preferences at any time; the most recent settings always take effect Personalization settings are **persistent** and **user-specific**. Once set, you don't need to send preferences with every session request. Suki automatically uses the saved preferences for each provider. ## How to set personalization preferences Set personalization preferences using the Mobile SDK or APIs. The exact method depends on your integration. **Mobile SDK Example:** ```swift Swift theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}} let preferences: [String: AnyHashable] = [ "verbosity": "CONCISE", // Options: CONCISE, BALANCED, DETAILED "section_format": [ [ "loinc": "10164-2", "style": "NARRATIVE" // Options: NARRATIVE, BULLETED ] ] ] SukiAmbientCore.shared.setPersonalizationPreferences(preferences) { result in switch result { case .success: print("Preferences updated successfully") case .failure(let error): print("Error updating preferences: \(error)") } } ``` **API Example:** ```python Python theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}} import requests url = "https://sdp.suki-stage.com/api/v1/user/preferences" payload = { "personalization_preference": { "section_format": [ { "loinc": "10164-2", "style": "NARRATIVE" } ], "verbosity": "CONCISE" } } headers = { "sdp_suki_token": "", "sdp_provider_id": "", "Content-Type": "application/json" } ``` **When to set preferences:** * **After user registration**: Set default preferences when a new provider is added to your system * **When preferences change**: Update preferences whenever a provider requests changes * **Before sessions start**: For best results, set preferences before audio streaming begins The **User Preferences API** is a `PATCH` request, so you only need to send the fields you want to change. Update verbosity and section formats independently. ## Personalization options Customize two aspects of note generation: ### Verbosity Controls how much detail is included in the generated notes. This setting applies to **all note sections**. **Applies to:** All note sections Generates shorter, to-the-point notes with essential information only. Provides a moderate level of detail: comprehensive but not excessive. Generates comprehensive notes with extensive detail and context. ### Section style Controls the formatting style for specific clinical sections. Set different styles for different sections as needed. **Applies to:** * History of Present Illness **(10164-2)** * Assessment and Plan **(51847-2)** * Assessment **(51848-0)** * Plan **(18776-5)** Generates notes in a continuous, story-like format that flows naturally. Generates notes using bullet points for easy scanning and quick reference. **Example:** ```json JSON theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}} "section_format": [ { "loinc": "10164-2", "style": "NARRATIVE" }, { "loinc": "51848-0", "style": "BULLETED" } ] ``` ## Best practices * **Set defaults early**: Configure preferences when providers are first registered in your system * **Offer a UI**: Let providers choose their preferences through your application's settings page * **Explain options**: Help providers understand the difference between verbosity levels and style options * **Update when requested**: Make it easy for providers to change their preferences as their needs evolve * **Test with real notes**: Verify that preferences produce notes that match provider expectations ## Related APIs Set and update personalization preferences for providers # Problem-Based Charting Source: https://developer.suki.ai/api-reference/capabilities/problem-based-charting Problem-based clinical documentation approach with diagnosis context integration **Updated** Pass the patient's existing diagnoses when starting a PBC session so the generated note merges them with what's discussed in the visit. Use the Context API for APIs, or `ambientOptions.diagnoses` for the Web SDK (**v2.1.2+**). Optional visit-level fields in `ambientOptions` (`visitType`, `encounterType`, `providerRole`, `reasonForVisit`, `chiefComplaint`) ship in the Web SDK **v2.2.0+** to improve note generation. See [AmbientOptions](/web-sdk/api-reference/types/ambient-options). For how the system reconciles those diagnoses with the conversation (API flow), refer to [Reconciliation](/api-reference/capabilities/problem-based-charting#reconciliation). For Web SDK implementation details, refer to [Existing patient diagnoses](/web-sdk/guides/ambient-problem-based-charting#existing-patient-diagnoses).

Quick summary

Problem-Based Charting (PBC) is a clinical documentation approach that organizes notes by patient problems instead of traditional note sections, and suggests diagnoses for each problem.

Last updated: June 2026

**Problem-Based Charting is supported by:** Ambient APIs, Web SDK, Mobile SDK Problem-Based Charting (PBC) organizes clinical notes by patient problems instead of traditional note sections. When you use PBC, Suki generates two things: 1. **Clinical note**: Organized by each problem or diagnosis 2. **Structured artifacts**: Suggested diagnoses with ICD10 and IMO codes PBC notes are different from traditional notes. In traditional notes, information is organized by sections like "History," "Assessment," and "Plan." In PBC notes, information is organized by each problem, grouping all related information together. When you enable PBC, providers get a note that has the following benefits: * **Easier to read**: See everything about each problem in one place * **Better continuity**: Includes existing problems from previous visits automatically * **Complete picture**: Captures both old and new problems discussed during the visit * **Structured data**: Generates standardized codes (ICD10, IMO) for EHR integration ## How to use PBC for APIs and SDKs You enable PBC by doing three things: * Define which note sections to generate and which one is the PBN * Pass the patient's existing diagnoses into session context * Read structured diagnosis output after the session finishes - **Web SDK:** In `ambientOptions.sections`, set `isPBNSection: true` on **exactly one** section. Rules for defaults, overrides, and errors are in [Configuration rules](/api-reference/capabilities/problem-based-charting#configuration-rules-for-pbc). - **Ambient APIs:** Send the LOINC `sections` array in the [Context API](/api-reference/ambient-sessions/context) body so the Suki backend knows which note sections to generate. PBN defaults (for example, when Assessment & Plan, LOINC `51847-2`, is treated as the PBN) follow the same rules as in [Configuration rules](/api-reference/capabilities/problem-based-charting#configuration-rules-for-pbc). - **Mobile SDK (iOS):** Pass LOINC sections in `kSections` via `setSessionContext`. See the Mobile SDK [Create session](/mobile-sdk/ambient-guides/create-session#provide-clinical-context-optional-but-recommended) guide for field names and examples. * **Ambient APIs:** Include diagnoses when you POST (and, if needed, PATCH) session context. * **Web SDK:** Use `ambientOptions.diagnoses`. Refer to the [AmbientOptions type](/web-sdk/api-reference/types/ambient-options) for more details. * **Mobile SDK (iOS):** Use `SukiAmbientConstant.kDiagnosisInfo` in `setSessionContext`. Refer to the Mobile SDK [Create session](/mobile-sdk/ambient-guides/create-session#provide-clinical-context-optional-but-recommended) guide for more details. * **Ambient APIs:** After the session has finished processing, use the [Structured Data](/api-reference/ambient-content/structured-data) or [Encounter Structured Data](/api-reference/ambient-content/encounter-structured-data) APIs and related endpoints to read suggested diagnoses. * **Mobile SDK (iOS):** After the session completes, call `getStructuredData(for:)`. See [Session status and content retrieval](/mobile-sdk/ambient-guides/session-status-and-content-retrieval#get-structured-data). * **Web SDK:** After the user submits the ambient session and note generation succeeds, read results from the **`onNoteSubmit`** callback (React) or the **`note-submission:success`** event (JavaScript and React). Refer to [Receiving note content](/web-sdk/guides/note-management#receiving-note-content), [Response structure](/web-sdk/guides/note-management#response-structure), [NoteContent](/web-sdk/api-reference/types/note-content), and [Diagnosis](/web-sdk/api-reference/types/diagnosis) for more details. ## Implementation examples Use the `diagnoses` block in `ambientOptions` to provide existing patient diagnoses when starting a session. **Code example:** ```javascript JavaScript theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}} sdkClient.mount({ rootElement: document.getElementById("suki-root"), encounter: encounterDetails, ambientOptions: { sections: [ { loinc: "51848-0", isPBNSection: true }, // Mark as PBN section { loinc: "11450-4" }, { loinc: "29545-1" }, ], diagnoses: { // [!code ++:14] New in v2.1.2 values: [ { codes: [ { code: "I10", description: "Essential hypertension", type: "ICD10", }, ], diagnosisNote: "Hypertension", }, ], }, }, }); ``` Use `setSessionContext` to pass LOINC sections and structured diagnosis information. After the session ends, call `getStructuredData(for:)` to retrieve diagnoses and other structured output. Refer to the Mobile SDK [Create session](/mobile-sdk/ambient-guides/create-session#provide-clinical-context-optional-but-recommended) guide for more details. **Code example:** ```swift Swift theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}} let context = SukiAmbientContext( sections: [ SukiAmbientSection(loinc: "51848-0", isPBNSection: true), // Mark as PBN section SukiAmbientSection(loinc: "11450-4"), SukiAmbientSection(loinc: "29545-1"), ], diagnosisInfo: [ SukiAmbientDiagnosisInfo( codes: [ SukiAmbientCode(code: "I10", description: "Essential hypertension", type: .icd10), ], diagnosisNote: "Hypertension", ), ], ) ``` Use the [Context API](/api-reference/ambient-sessions/context) to provide existing patient diagnoses when starting a session. **Code example:** ```python Python theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}} payload = { "diagnoses": { "values": [ { "codes": [ { "code": "I10", "description": "Essential hypertension", "type": "ICD10", }, ], "diagnosis_note": "Hypertension", }, ], }, } ``` **APIs to use:** Provide initial diagnoses when starting a session Update or add diagnoses during a session ## Configuration rules for PBC When configuring PBC, follow these rules: Only one section can have `isPBNSection: true`. If multiple sections are marked as PBN, the ambient session will fail to start. If no section includes the `isPBNSection` flag and the Assessment & Plan section (51847-2) is present, that section automatically becomes the PBN. Explicitly set `isPBNSection: false` to prevent automatic PBN assignment. For a given ambient session, **only one section** can have `isPBNSection: true`. If more than one section is marked as PBN, the ambient session will fail to start. ## Core principles Understanding these principles helps you use PBC effectively: The ICD10 code is treated as the **primary identifier** for all clinical problems during processing. **System uses ICD10 for:** * Diagnosis identification and matching * Clinical problem categorization * Cross-session diagnosis continuity * Normalization of other code types (IMO, SNOMED) Non-ICD10 codes are automatically converted to ICD10 equivalents when possible. All diagnosis generation is done on a **best-effort** basis. The system prioritizes returning partial, useful information over failing an entire request due to an issue with a single data point. In reambient scenarios, diagnoses from previous sessions are **not automatically carried forward**. You must provide the full context for each new session. **Your Responsibility**: Include all relevant diagnoses (previous + new + modified) in each session context. ## How PBC works PBC processes diagnoses in three steps: You provide existing diagnoses when starting the session using the Context APIs. Suki's AI analyzes the conversation and identifies new problems or updates to existing diagnoses. Suki generates a clinical note organized by problem and structured artifacts with standardized codes. ```mermaid actions={false} theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}} %%{init: {'theme':'base', 'themeVariables': { 'primaryColor':'#FFE148','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[Session audio/transcript] --> B[ML processing] B --> C[Suki Backend] C --> D{Valid ICD10?} D -->|Yes| E[Case 1: Enrich with IMO
Add description,
laterality, IMO code] D -->|No| F[Case 2: Enrich with IMO
Add ICD10, description,
laterality, IMO code] E --> G[Final Output
Problems with Code,
Description, Diagnosis Note] F --> G 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:#FFE148,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 ``` Suki backend includes the ML-suggested problem name and returns standardized ICD10 code, description, and IMO equivalent in the final output. ### Validation rules Each diagnosis in your request must follow these rules: * **One code per diagnosis**: Each diagnosis must have exactly one code (ICD10 or IMO) * **No mixed codes**: A single diagnosis cannot contain multiple code types * **Code required**: Every diagnosis must include a code ### Input processing Suki processes diagnoses through normalization and deduplication: Normalization does not preserve the original input code. If a code cannot map to an ICD10 equivalent, **Suki skips the entire diagnosis object** and continues processing the remaining input. ### Reconciliation When you send existing diagnoses via the Context API at session start, Suki **reconciles** them with what is discussed during the session. You get one problem list and no duplicates. This section describes the API flow (Context API to send, Structured Data API to retrieve). For Web SDK, refer to the [Existing patient diagnoses](/web-sdk/guides/ambient-problem-based-charting#existing-patient-diagnoses) section in the ambient guide for more details. **What happens to each diagnosis you send:** * **Discussed in the session** - The diagnosis is updated and returned in the structured data output. * **Not discussed in the session** - The diagnosis is not included in the final output. * **Matches something discussed** - Your diagnosis and the one discussed are merged into a single entry (no duplicate). The Structured Data API returns only diagnoses that were updated or newly generated. ### How diagnoses are generated During the session, Suki's AI analyzes the conversation and takes one of three actions on the diagnoses you provided: 1. **Update existing diagnosis**: Modify the content if it was discussed 2. **Generate new diagnosis**: Create a new diagnosis if a new problem was discussed 3. **Keep unchanged**: Leave a diagnosis untouched if it wasn't significantly discussed Only diagnoses that were **updated or newly generated** are returned in the final output. Untouched diagnoses are not returned. If a diagnosis wasn't discussed, it won't appear in the output. ### Output enrichment For any diagnosis that was updated or newly generated, Suki enriches it with: * **ICD10 code**: Standard diagnosis code * **IMO code**: Intelligent Medical Objects code * **Laterality**: Left/right/bilateral information when applicable * **Post coordination flag**: Indicates if the diagnosis requires additional modifiers The IMO code returned in the output may be different from any IMO code that was sent in the input payload. This is normal: Suki uses the most accurate code based on the conversation content. If enrichment fails, Suki still returns the diagnosis with available information to ensure you don't lose generated content. ### Retrieving generated diagnoses Refer to the [How to use PBC for APIs and SDKs](/api-reference/capabilities/problem-based-charting#how-to-use-pbc-for-apis-and-sdks) section for more details. ## Handling reambient scenarios In reambient scenarios, where a single patient encounter involves multiple recording sessions, understanding how context is managed is critical. Sessions do not **automatically inherit diagnoses** from previous sessions. Each session starts fresh. You must provide all relevant diagnoses for each new session. **What this means:** * When you use APIs in your implementation, only diagnoses passed via the Context APIs for the current session are considered * Diagnoses from previous sessions are **not automatically carried forward** * You must provide the complete and current list of all relevant diagnoses for each new session **Your responsibilities:** Because sessions don't inherit context, you must provide the complete list of all relevant diagnoses for each new session. This includes: * **Modified diagnoses**: Any diagnoses that were changed by the provider in previous sessions * **New diagnoses**: Any newly added diagnoses from previous sessions * **Existing diagnoses**: Diagnoses from previous sessions that should be retained **Recommended workflow:** ```mermaid actions={false} theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}} %%{init: {'theme':'base', 'themeVariables': { 'primaryColor':'#FFE148','primaryTextColor':'#1a1a1a','primaryBorderColor':'#FFE148','lineColor':'#FFE148','secondaryColor':'#FFF394','tertiaryColor':'#FFFADE','mainBkg':'#FFF394','secondBkg':'#FFFADE','border1':'#FFE148','border2':'#FFE148','arrowheadColor':'#FFE148','fontFamily':'Inter, system-ui, sans-serif','fontSize':'14px','nodeBorder':'#FFE148','clusterBkg':'#FFFADE','clusterBorder':'#FFE148','defaultLinkColor':'#FFE148','titleColor':'#1a1a1a','edgeLabelBackground':'#FFE148','nodeTextColor':'#1a1a1a'}}}%% graph TD A[Start session] --> B[Context with
existing diagnoses] B --> C[Conduct encounter] C --> D[End session] D --> E[Get generated
diagnoses] E --> F{Reambient session?} F -->|Yes| G[Include all
relevant diagnoses] F -->|No| H[Complete] G --> B style A fill:#FFF394,stroke:#FFE148,stroke-width:2px,color:#1a1a1a style B fill:#FFF394,stroke:#FFE148,stroke-width:2px,color:#1a1a1a style C fill:#FFF394,stroke:#FFE148,stroke-width:2px,color:#1a1a1a style D fill:#FFF394,stroke:#FFE148,stroke-width:2px,color:#1a1a1a style E fill:#FFF394,stroke:#FFE148,stroke-width:2px,color:#1a1a1a style F fill:#FFE148,stroke:#FFE148,stroke-width:2px,color:#1a1a1a style G fill:#FFF394,stroke:#FFE148,stroke-width:2px,color:#1a1a1a style H fill:#FFF394,stroke:#FFE148,stroke-width:2px,color:#1a1a1a ``` After each session, retrieve the generated diagnoses using the Structured Data API, then include all relevant diagnoses (including any modifications) when starting the next session. ## Best practices * **Provide complete context**: Always include all relevant existing diagnoses when starting a session * **Use ICD10 when possible**: ICD10 codes are preferred and processed most reliably * **Handle reambient carefully**: Retrieve diagnoses after each session and include them in the next session * **Validate codes**: Ensure diagnosis codes are valid before sending them * **Monitor output**: Check which diagnoses were updated or generated to understand what was discussed * **Update after user edits**: If providers modify diagnoses, include those modifications in subsequent sessions ## FAQs In reambient scenarios, the system does not automatically carry forward diagnoses from previous sessions. You must provide the complete and current list of all relevant diagnoses for each new session. The system uses [IMO APIs](https://www.imohealth.com/) to find the best possible ICD10 code equivalent for non-ICD10 codes. If a code cannot be mapped, that diagnosis is skipped. The system normalizes all codes to ICD10 before processing. ICD10 is used as the source of truth for all diagnosis operations. The system deduplicates diagnoses based on the ICD10 code. Diagnoses with the same ICD10 code are merged, and their notes are combined. Only diagnoses that were updated or newly generated are returned. Diagnoses that weren't discussed during the session are not included in the output. # Audio Capture & Streaming Source: https://developer.suki.ai/api-reference/faqs/audio-capture-streaming Questions about audio capture, streaming, and WebSocket implementation LINEAR16 (16KHz sampling rate) over the mono channel. Audio should be chunked into 100ms packets for optimal performance. We only support 100ms audio chunks to achieve the right balance between quality, latency, and efficiency. Network connection speed and consistency are important for Suki to perform well. **Suki requires:** * **Upload speed**: 1Mbps * **Bitrate**: 768kbps * **Ping time**: 150ms * **Unloaded latency**: \<50ms * **Loaded latency**: \<150ms Client should set up a WebSocket Secure (wss\://) request with the Suki endpoint. Refer to the [Audio stream API](/api-reference/ambient-sessions/audio-stream) for implementation details. For **Ambient** WebSocket **`/ws/stream`** message format, send **LINEAR16**, **16 kHz**, **mono** audio, in about **100 ms** chunks (see the [Audio streaming](/api-reference/ambient-sessions/audio-stream) reference and [Ambient audio streaming](/documentation/ambient-audio-streaming) guide). ### How messages are sent Each outbound message from the client must be: * **One WebSocket text frame** (UTF-8) with **one JSON object** inside * **One logical send** per frame (do not pack multiple JSON objects in one frame) On **`/ws/stream`**, do **not** send PCM as **binary** WebSocket frames. Do **not** stream raw audio over HTTP with `Content-Type: application/json`. **Field names (proto-style JSON)** * **`START_TIME`** and **`AUDIO`**: use **`type`** and **`data`** * **`data`**: standard Base64 ([RFC 4648](https://datatracker.ietf.org/doc/html/rfc4648)) of the **raw bytes** you mean to send (same idea as Go `encoding/json` for `[]byte`). Do not use hex, URL-safe Base64, or raw binary inside the JSON string. * **`EVENT`**: use **`type`**: `"EVENT"` and the **`event`** field. Do **not** put the action name in **`data`**. ### Message order (each stream segment) 1. Send **`START_TIME`** once: **`data`** is Base64 of a UTF-8 **RFC 3339** timestamp (for example `2026-04-25T12:34:56Z`). 2. Send one or more **`AUDIO`** messages: **`data`** is Base64 of each **raw PCM** chunk. 3. Send a final **`AUDIO`** to end audio: **`data`** is **`RU9G`** (Base64 of ASCII **`EOF`**, bytes `0x45`, `0x4F`, `0x46`). Do not use a separate `end_of_stream` type unless your integration team tells you otherwise. `EVENT` messages can go **anywhere** in the stream when you need control (pause, resume, keep-alive, cancel, abort). ### EVENT values you can send Use **`{"type":"EVENT","event":""}`** with one of: | Value | What it does | | :-------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------- | | **PAUSE** | Pause the stream | | **RESUME** | Resume the stream | | **CANCEL** | User cancels the stream | | **ABORT** | Stream is aborted (interruption) | | **KEEP\_ALIVE** | Keep the connection alive during inactivity. While **paused**, send at least once every **five seconds** so the server does not close the connection. | ### Message examples ```json START_TIME theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}} { "type": "START_TIME", "data": "" } ``` ```json AUDIO (PCM chunk) theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}} { "type": "AUDIO", "data": "Base64EncodedPcmBytes" } ``` ```json AUDIO (stream end marker) theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}} { "type": "AUDIO", "data": "RU9G" } ``` ```json PAUSE Event theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}} { "type": "EVENT", "event": "PAUSE" } ``` ```json RESUME Event theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}} { "type": "EVENT", "event": "RESUME" } ``` ```json CANCEL Event theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}} { "type": "EVENT", "event": "CANCEL" } ``` ```json KEEP_ALIVE Event theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}} { "type": "EVENT", "event": "KEEP_ALIVE" } ``` ```json ABORT Event theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}} { "type": "EVENT", "event": "ABORT" } ``` The stream end marker is an **`AUDIO`** message whose **`data`** is Base64 of the raw bytes **`EOF`**, not a bare JSON string `"EOF"` and not an **`EVENT`** named EOF, unless your stack documentation says otherwise. # Authentication Source: https://developer.suki.ai/api-reference/faqs/authentication Authentication and authorization questions for API access We support * OAuth 2.0 ID token for public clients such as browsers, mobile devices etc. * Access token for confidential clients such as backend systems. We support [HMAC (Hash-based message authentication code)](https://www.okta.com/identity-101/hmac/) for webhook authentication (Details can be shared) Client systems cannot authenticate with Suki's platform via APIs when a JWT token fails. It's handled with standard HTTPS error codes; refer API reference # Miscellaneous Source: https://developer.suki.ai/api-reference/faqs/miscellaneous General API questions and miscellaneous topics To handle different doctor roles/specialties dynamically, clients use our context API to seed session context with the provider role (e.g. SPECIALTY). # Technical Constraints & Risks Source: https://developer.suki.ai/api-reference/faqs/technical-constraints-risks Technical limitations, constraints, and risk considerations for API integration No we don't have such pre-approved domains. In order to register for our webhook, you just need to give your callback URL so we can notify you there. This step is currently via manual sharing; in the future we plan to upgrade this system. N/A, we can share the IP of our system which calls callback URL if need be A POST call will be made to the webhook hosted by the Partner using the HTTPS protocol. Yes, the Webhook URL should be configured at the Partner level during [partner onboarding](/documentation/partner-onboarding). We currently do not support session-based webhook callbacks or similar configurations; webhook support is only for APIs and not for Web SDK. The client is responsible for creating and managing the `encounter_id`. We support combining sessions and generating the note based on the provided `encounter_id`. An encounter can include multiple ambient sessions. 1. Obtain a developer platform test license (POC: Commercials team).
2. Complete partner onboarding:
* Share required details for partner creation in our system → you will receive a Partner ID (`partner_id`).
* Let us know the unique identifier you will use in the OAuth 2.0 JWT token to identify the user (provider).
Example: user\_id, email\_id, sid, pid, etc. (need not be actual id from your system, can be hash value as well)
* Provide your JWKS endpoint for accessing your public key.
* Test authentication with Suki.
Here's a minimal flow for your reference: `/login → /session/create → /context (optional) → /stream → /end` This flow automatically triggers note generation. Either: 1. Use `/status` to poll the note generation status, then call /content to retrieve the note. 2. Receive a notification through our webhook. As long as the stream is active, there is no upper limit on call duration. The system allows a maximum pause of 30 minutes during the streaming. If you get disconnected and then rejoin, or lose the WebSocket connection, Suki stitches the sessions together using the same session ID. Although there is no strict lower limit, Suki needs a minimum amount of data to generate recommendations. For calls **shorter than 1 minute**, Suki may not have enough meaningful data/information to provide accurate recommendations and returns empty content. The session will be marked as **skipped**. # Ambient Session User Feedback Source: https://developer.suki.ai/api-reference/feedback/feedback POST /api/v1/ambient/session/{session_id}/{entity}/feedback Submit user feedback on generated clinical content for continuous improvement Use the **Feedback API** to collect quantitative (ratings) and qualitative (comments) feedback. Capturing feedback helps drive AI model improvement and increases client confidence. The API supports the following actions: * **Quantitative Feedback**: Rate content using a scale with configurable minimum and maximum values. * **Qualitative Feedback**: Provide optional, free-form comments for detailed insights. * **Entity-Level Tracking**: Tie feedback to specific entities within sessions. ## Supported entity types Provide feedback on the following entity types: | Entity type | Description | | ----------- | -------------------------- | | `content` | Generated clinical content | Within a single ambient session (session\_id), you can provide feedback for each `entity type` only **once**. If you provide feedback for the same `entity type` multiple times, the feedback will not be valid. Also, a single `session_id` can contain **multiple feedbacks**, provided each entry corresponds to a **different** entity type. ## Rating system The `ratingFeedback` object provides quantitative feedback. It includes the following fields: * `min_rating`: The minimum rating value (e.g., 0). * `max_rating`: The maximum rating value. * `rating`: The actual rating you provide within the min-max range. Configure the rating scale by setting the `min_rating` and `max_rating` values. The range is **inclusive**, so both the `min_rating` and `max_rating` values are valid ratings. For example: * To create a rating scale of 0 to 5, set `min_rating` to 0 and `max_rating` to 5. A user can provide any integer rating from 0 to 5. * To create a binary scale, set `min_rating` to 0 and `max_rating` to 1. A user can provide a rating of either 0 or 1. * Suki suggests using a scale of 1 to 5 for the rating. ## Character limits * `qualitative_comments`: Maximum **2000** characters. Your feedback helps Suki to improve the AI-generated content. All feedback is reviewed and used to enhance quality. ## Code examples ```python theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}} import requests session_id = "session_abc_123" entity = "content" url = f"https://sdp.suki-stage.com/api/v1/ambient/session/{session_id}/{entity}/feedback" headers = { "sdp_suki_token": "", "sdp_provider_id": "", "Content-Type": "application/json" } payload = { "ratingFeedback": { "min_rating": 0, "max_rating": 5, "rating": 4 }, "qualitative_comments": "The generated content was accurate and helpful. Great job!" # Optional, max 2000 chars } response = requests.post(url, json=payload, headers=headers) if response.status_code == 201: data = response.json() feedback_id = data.get("feedback_id") print(f"Feedback submitted successfully. Feedback ID: {feedback_id}") else: print(f"Failed to submit feedback: {response.status_code}") print(response.json()) ``` ```typescript theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}} const sessionId = 'session_abc_123'; const entity = 'content'; const response = await fetch( `https://sdp.suki-stage.com/api/v1/ambient/session/${sessionId}/${entity}/feedback`, { method: 'POST', headers: { 'sdp_suki_token': '', 'sdp_provider_id': '', 'Content-Type': 'application/json' }, body: JSON.stringify({ ratingFeedback: { min_rating: 0, max_rating: 5, rating: 4 }, qualitative_comments: 'The generated content was accurate and helpful. Great job!' // Optional, max 2000 chars }) } ); if (response.status === 201) { const data = await response.json(); const feedbackId = data.feedback_id; console.log(`Feedback submitted successfully. Feedback ID: ${feedbackId}`); } else { const error = await response.json(); console.error(`Failed to submit feedback: ${response.status}`, error); } ``` # HTTPS Guidelines Source: https://developer.suki.ai/api-reference/https-guidelines Learn about the standard HTTPS guidelines for APIs that Suki uses Suki uses **standard HTTP status codes** to indicate the outcome of an API request. * **`2xx` codes** indicate success. * **`4xx` codes** indicate a client-side error (e.g., you omitted a required parameter or provided an invalid configuration). * **`5xx` codes** indicate a server-side error on Suki's end. These are rare. The following table lists the most common HTTP status codes you may receive. | Code | Title | Description | | :----------------------- | :---------------- | :---------------------------------------------------------------------------------------------------------------------------------------- | | **`200`** | OK | The request was successful. | | **`201`** | Created | The resource was created successfully. The URL for the new resource is in the `Location` header. | | **`204`** | No Content | The request was successful, and there is no content to return. | | **`400`** | Bad Request | The request was unacceptable, often due to malformed syntax or a missing parameter. | | **`401`** | Unauthorized | The request was not authenticated. This could be due to missing, invalid, or insufficient credentials. | | **`402`** | Over Quota | The request was valid, but you have exceeded your plan's quota or rate limits. | | **`403`** | Forbidden | The request was not authenticated. This could be due to missing, invalid, or insufficient credentials. | | **`404`** | Not Found | The requested resource does not exist. | | **`409`** | Conflict | The request conflicts with the current state of the resource (e.g., the resource already exists, or the request was based on stale data). | | **`422`** | Validation Failed | The request was parsed correctly but failed a validation rule. | | **`429`** | Too Many Requests | You have sent too many requests in a short period. We recommend using an exponential backoff strategy for your requests. | | **`500, 502, 503, 504`** | Server Errors | An unexpected error occurred on Suki's servers. | # Info API Source: https://developer.suki.ai/api-reference/info Reference data for specialties, diagnoses, encounter types, visit types, LOINC codes, and provider roles These read-only endpoints return catalogs and coded lists for building requests, forms, and client-side validation. Response bodies are stable reference data you can cache on a schedule that fits your release process. ## Endpoints # Supported Diagnosis Codes Source: https://developer.suki.ai/api-reference/info/diagnosis GET /api/v1/info/diagnosis Get list of supported diagnosis codes and medical conditions Use this endpoint to get the list of supported diagnosis codes. ## Code examples ```python theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}} import requests url = "https://sdp.suki-stage.com/api/v1/info/diagnosis" headers = { "sdp_suki_token": "", "sdp_provider_id": "" } response = requests.get(url, headers=headers) if response.status_code == 200: diagnosis_data = response.json() print("Supported Diagnosis Code Types:") for code_type in diagnosis_data.get("diagnosis_code_types", []): print(f" {code_type.get('code_type')}") else: print(f"Failed to get diagnosis codes: {response.status_code}") print(response.json()) ``` ```typescript theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}} const response = await fetch('https://sdp.suki-stage.com/api/v1/info/diagnosis', { headers: { 'sdp_suki_token': '', 'sdp_provider_id': '' } }); if (response.ok) { const diagnosisData = await response.json(); console.log('Supported Diagnosis Code Types:'); diagnosisData.diagnosis_code_types?.forEach((codeType: any) => { console.log(` ${codeType.code_type}`); }); } else { const error = await response.json(); console.error(`Failed to get diagnosis codes: ${response.status}`, error); } ``` # Encounter Types Source: https://developer.suki.ai/api-reference/info/encounter-types GET /api/v1/info/encounter-types Get list of supported clinical encounter types Use this endpoint to get the list of supported encounter types. ## Code examples ```python theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}} import requests url = "https://sdp.suki-stage.com/api/v1/info/encounter-types" headers = { "sdp_suki_token": "", "sdp_provider_id": "" } response = requests.get(url, headers=headers) if response.status_code == 200: encounter_types_data = response.json() print("Supported Encounter Types:") for encounter_type in encounter_types_data.get("encounter_types", []): print(f" {encounter_type.get('code')}") else: print(f"Failed to get encounter types: {response.status_code}") print(response.json()) ``` ```typescript theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}} const response = await fetch('https://sdp.suki-stage.com/api/v1/info/encounter-types', { headers: { 'sdp_suki_token': '', 'sdp_provider_id': '' } }); if (response.ok) { const encounterTypesData = await response.json(); console.log('Supported Encounter Types:'); encounterTypesData.encounter_types?.forEach((encounterType: any) => { console.log(` ${encounterType.code}`); }); } else { const error = await response.json(); console.error(`Failed to get encounter types: ${response.status}`, error); } ``` # System Information Source: https://developer.suki.ai/api-reference/info/information GET /api/v1/info Get system information and supported configuration values Use this endpoint to get the list of supported LOINC codes, specialties, encounter types, visit types, provider roles, diagnosis code types, and medication order metadata (coding systems, dosage units, frequency types, timings, order statuses, encounter relations, and origins). You can also fetch each category with dedicated `GET /api/v1/info/...` routes listed under **Info** in the API reference. ## Code examples ```python theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}} import requests url = "https://sdp.suki-stage.com/api/v1/info" headers = { "sdp_suki_token": "", "sdp_provider_id": "" } response = requests.get(url, headers=headers) if response.status_code == 200: info = response.json() print("System Information:") print(f"LOINCs: {len(info.get('loincs', []))} codes") print(f"Specialties: {len(info.get('specialties', []))} specialties") print(f"Encounter Types: {len(info.get('encounter_types', []))} types") print(f"Visit Types: {len(info.get('visit_types', []))} types") print(f"Provider Roles: {len(info.get('provider_roles', []))} roles") print(f"Diagnosis Code Types: {len(info.get('diagnosis_code_types', []))} types") print(f"Medication coding systems: {len(info.get('medication_coding_systems', []))}") print(f"Medication dosage units: {len(info.get('medication_dosage_units', []))}") print(f"Medication frequency types: {len(info.get('medication_frequency_types', []))}") print(f"Medication timings: {len(info.get('medication_timings', []))}") print(f"Medication order statuses: {len(info.get('medication_order_statuses', []))}") print(f"Order encounter relations: {len(info.get('order_encounter_relations', []))}") print(f"Order origins: {len(info.get('order_origins', []))}") else: print(f"Failed to get system information: {response.status_code}") print(response.json()) ``` ```typescript theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}} const response = await fetch('https://sdp.suki-stage.com/api/v1/info', { headers: { 'sdp_suki_token': '', 'sdp_provider_id': '' } }); if (response.ok) { const info = await response.json(); console.log('System Information:'); console.log(`LOINCs: ${info.loincs?.length || 0} codes`); console.log(`Specialties: ${info.specialties?.length || 0} specialties`); console.log(`Encounter Types: ${info.encounter_types?.length || 0} types`); console.log(`Visit Types: ${info.visit_types?.length || 0} types`); console.log(`Provider Roles: ${info.provider_roles?.length || 0} roles`); console.log(`Diagnosis Code Types: ${info.diagnosis_code_types?.length || 0} types`); console.log(`Medication coding systems: ${info.medication_coding_systems?.length ?? 0}`); console.log(`Medication dosage units: ${info.medication_dosage_units?.length ?? 0}`); console.log(`Medication frequency types: ${info.medication_frequency_types?.length ?? 0}`); console.log(`Medication timings: ${info.medication_timings?.length ?? 0}`); console.log(`Medication order statuses: ${info.medication_order_statuses?.length ?? 0}`); console.log(`Order encounter relations: ${info.order_encounter_relations?.length ?? 0}`); console.log(`Order origins: ${info.order_origins?.length ?? 0}`); } else { const error = await response.json(); console.error(`Failed to get system information: ${response.status}`, error); } ``` # Supported LOINCs Source: https://developer.suki.ai/api-reference/info/loincs GET /api/v1/info/loincs Get list of supported LOINC codes for clinical note sections Use this endpoint to get the list of supported LOINC codes. For more information about the LOINC codes, refer to the [Note sections](/documentation/note-sections). ## Code examples ```python theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}} import requests url = "https://sdp.suki-stage.com/api/v1/info/loincs" headers = { "sdp_suki_token": "", "sdp_provider_id": "" } response = requests.get(url, headers=headers) if response.status_code == 200: loincs_data = response.json() print("Supported LOINC Codes:") for loinc in loincs_data.get("loincs", []): print(f" {loinc.get('code')}: {loinc.get('common_name')}") else: print(f"Failed to get LOINC codes: {response.status_code}") print(response.json()) ``` ```typescript theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}} const response = await fetch('https://sdp.suki-stage.com/api/v1/info/loincs', { headers: { 'sdp_suki_token': '', 'sdp_provider_id': '' } }); if (response.ok) { const loincsData = await response.json(); console.log('Supported LOINC Codes:'); loincsData.loincs?.forEach((loinc: any) => { console.log(` ${loinc.code}: ${loinc.common_name}`); }); } else { const error = await response.json(); console.error(`Failed to get LOINC codes: ${response.status}`, error); } ``` # Medication Order Metadata Source: https://developer.suki.ai/api-reference/info/orders GET /api/v1/info/orders Get all supported medication order metadata in one response Use this endpoint to get supported metadata for medication orders in one response, including coding systems, dosage units, frequency types, timings, statuses, origins, and encounter relations. For more information about medication orders, refer to the [Medication orders](/documentation/medication-orders). ## Code examples ```python theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}} import requests url = "https://sdp.suki-stage.com/api/v1/info/orders" headers = { "sdp_suki_token": "", "sdp_provider_id": "" } response = requests.get(url, headers=headers) if response.status_code == 200: order_info = response.json() print("Medication order metadata:") print(f" Coding systems: {len(order_info.get('coding_systems', []))}") print(f" Dosage units: {len(order_info.get('dosage_units', []))}") print(f" Encounter relations: {len(order_info.get('encounter_relations', []))}") print(f" Frequency types: {len(order_info.get('frequency_types', []))}") print(f" Origins: {len(order_info.get('origins', []))}") print(f" Statuses: {len(order_info.get('statuses', []))}") print(f" Timings: {len(order_info.get('timings', []))}") else: print(f"Failed to get medication order metadata: {response.status_code}") print(response.json()) ``` ```typescript theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}} const response = await fetch('https://sdp.suki-stage.com/api/v1/info/orders', { headers: { 'sdp_suki_token': '', 'sdp_provider_id': '' } }); if (response.ok) { const orderInfo = await response.json(); console.log('Medication order metadata:'); console.log(` Coding systems: ${orderInfo.coding_systems?.length ?? 0}`); console.log(` Dosage units: ${orderInfo.dosage_units?.length ?? 0}`); console.log(` Encounter relations: ${orderInfo.encounter_relations?.length ?? 0}`); console.log(` Frequency types: ${orderInfo.frequency_types?.length ?? 0}`); console.log(` Origins: ${orderInfo.origins?.length ?? 0}`); console.log(` Statuses: ${orderInfo.statuses?.length ?? 0}`); console.log(` Timings: ${orderInfo.timings?.length ?? 0}`); } else { const error = await response.json(); console.error(`Failed to get medication order metadata: ${response.status}`, error); } ``` # Medication Coding Systems Source: https://developer.suki.ai/api-reference/info/orders-coding-systems GET /api/v1/info/orders/coding-systems Get supported medication coding systems Use this endpoint to get the list of supported medication coding systems. ## Code examples ```python theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}} import requests url = "https://sdp.suki-stage.com/api/v1/info/orders/coding-systems" headers = { "sdp_suki_token": "", "sdp_provider_id": "" } response = requests.get(url, headers=headers) if response.status_code == 200: coding_systems_data = response.json() print("Supported Medication Coding Systems:") for item in coding_systems_data.get("coding_systems", []): print(f" {item.get('code')}") else: print(f"Failed to get medication coding systems: {response.status_code}") print(response.json()) ``` ```typescript theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}} const response = await fetch('https://sdp.suki-stage.com/api/v1/info/orders/coding-systems', { headers: { 'sdp_suki_token': '', 'sdp_provider_id': '' } }); if (response.ok) { const codingSystemsData = await response.json(); console.log('Supported Medication Coding Systems:'); codingSystemsData.coding_systems?.forEach((item: any) => { console.log(` ${item.code}`); }); } else { const error = await response.json(); console.error(`Failed to get medication coding systems: ${response.status}`, error); } ``` # Medication Dosage Units Source: https://developer.suki.ai/api-reference/info/orders-dosage-units GET /api/v1/info/orders/dosage-units Get supported medication dosage units Use this endpoint to get the list of supported medication dosage units. ## Code examples ```python theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}} import requests url = "https://sdp.suki-stage.com/api/v1/info/orders/dosage-units" headers = { "sdp_suki_token": "", "sdp_provider_id": "" } response = requests.get(url, headers=headers) if response.status_code == 200: dosage_units_data = response.json() print("Supported Medication Dosage Units:") for item in dosage_units_data.get("dosage_units", []): print(f" {item.get('code')}") else: print(f"Failed to get medication dosage units: {response.status_code}") print(response.json()) ``` ```typescript theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}} const response = await fetch('https://sdp.suki-stage.com/api/v1/info/orders/dosage-units', { headers: { 'sdp_suki_token': '', 'sdp_provider_id': '' } }); if (response.ok) { const dosageUnitsData = await response.json(); console.log('Supported Medication Dosage Units:'); dosageUnitsData.dosage_units?.forEach((item: any) => { console.log(` ${item.code}`); }); } else { const error = await response.json(); console.error(`Failed to get medication dosage units: ${response.status}`, error); } ``` # Order Encounter Relations Source: https://developer.suki.ai/api-reference/info/orders-encounter-relations GET /api/v1/info/orders/encounter-relations Get supported order encounter relations Use this endpoint to get the list of supported order encounter relations. ## Code examples ```python theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}} import requests url = "https://sdp.suki-stage.com/api/v1/info/orders/encounter-relations" headers = { "sdp_suki_token": "", "sdp_provider_id": "" } response = requests.get(url, headers=headers) if response.status_code == 200: encounter_relations_data = response.json() print("Supported Order Encounter Relations:") for item in encounter_relations_data.get("encounter_relations", []): print(f" {item.get('code')}") else: print(f"Failed to get order encounter relations: {response.status_code}") print(response.json()) ``` ```typescript theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}} const response = await fetch('https://sdp.suki-stage.com/api/v1/info/orders/encounter-relations', { headers: { 'sdp_suki_token': '', 'sdp_provider_id': '' } }); if (response.ok) { const encounterRelationsData = await response.json(); console.log('Supported Order Encounter Relations:'); encounterRelationsData.encounter_relations?.forEach((item: any) => { console.log(` ${item.code}`); }); } else { const error = await response.json(); console.error(`Failed to get order encounter relations: ${response.status}`, error); } ``` # Medication Frequency Types Source: https://developer.suki.ai/api-reference/info/orders-frequencies GET /api/v1/info/orders/frequencies Get supported medication frequency types Use this endpoint to get the list of supported medication frequency types. ## Code examples ```python theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}} import requests url = "https://sdp.suki-stage.com/api/v1/info/orders/frequencies" headers = { "sdp_suki_token": "", "sdp_provider_id": "" } response = requests.get(url, headers=headers) if response.status_code == 200: frequency_types_data = response.json() print("Supported Medication Frequency Types:") for item in frequency_types_data.get("frequency_types", []): print(f" {item.get('code')}") else: print(f"Failed to get medication frequency types: {response.status_code}") print(response.json()) ``` ```typescript theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}} const response = await fetch('https://sdp.suki-stage.com/api/v1/info/orders/frequencies', { headers: { 'sdp_suki_token': '', 'sdp_provider_id': '' } }); if (response.ok) { const frequencyTypesData = await response.json(); console.log('Supported Medication Frequency Types:'); frequencyTypesData.frequency_types?.forEach((item: any) => { console.log(` ${item.code}`); }); } else { const error = await response.json(); console.error(`Failed to get medication frequency types: ${response.status}`, error); } ``` # Medication Timings Source: https://developer.suki.ai/api-reference/info/orders-medication-timings GET /api/v1/info/orders/medication-timings Get supported medication timings Use this endpoint to get the list of supported medication timings. ## Code examples ```python theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}} import requests url = "https://sdp.suki-stage.com/api/v1/info/orders/medication-timings" headers = { "sdp_suki_token": "", "sdp_provider_id": "" } response = requests.get(url, headers=headers) if response.status_code == 200: timings_data = response.json() print("Supported Medication Timings:") for item in timings_data.get("timings", []): print(f" {item.get('code')}") else: print(f"Failed to get medication timings: {response.status_code}") print(response.json()) ``` ```typescript theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}} const response = await fetch('https://sdp.suki-stage.com/api/v1/info/orders/medication-timings', { headers: { 'sdp_suki_token': '', 'sdp_provider_id': '' } }); if (response.ok) { const timingsData = await response.json(); console.log('Supported Medication Timings:'); timingsData.timings?.forEach((item: any) => { console.log(` ${item.code}`); }); } else { const error = await response.json(); console.error(`Failed to get medication timings: ${response.status}`, error); } ``` # Order Origins Source: https://developer.suki.ai/api-reference/info/orders-origins GET /api/v1/info/orders/origins Get supported order origins Use this endpoint to get the list of supported order origins. ## Code examples ```python theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}} import requests url = "https://sdp.suki-stage.com/api/v1/info/orders/origins" headers = { "sdp_suki_token": "", "sdp_provider_id": "" } response = requests.get(url, headers=headers) if response.status_code == 200: origins_data = response.json() print("Supported Order Origins:") for item in origins_data.get("origins", []): print(f" {item.get('code')}") else: print(f"Failed to get order origins: {response.status_code}") print(response.json()) ``` ```typescript theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}} const response = await fetch('https://sdp.suki-stage.com/api/v1/info/orders/origins', { headers: { 'sdp_suki_token': '', 'sdp_provider_id': '' } }); if (response.ok) { const originsData = await response.json(); console.log('Supported Order Origins:'); originsData.origins?.forEach((item: any) => { console.log(` ${item.code}`); }); } else { const error = await response.json(); console.error(`Failed to get order origins: ${response.status}`, error); } ``` # Medication Order Statuses Source: https://developer.suki.ai/api-reference/info/orders-statuses GET /api/v1/info/orders/statuses Get supported medication order statuses Use this endpoint to get the list of supported medication order statuses. ## Code examples ```python theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}} import requests url = "https://sdp.suki-stage.com/api/v1/info/orders/statuses" headers = { "sdp_suki_token": "", "sdp_provider_id": "" } response = requests.get(url, headers=headers) if response.status_code == 200: statuses_data = response.json() print("Supported Medication Order Statuses:") for item in statuses_data.get("statuses", []): print(f" {item.get('code')}") else: print(f"Failed to get medication order statuses: {response.status_code}") print(response.json()) ``` ```typescript theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}} const response = await fetch('https://sdp.suki-stage.com/api/v1/info/orders/statuses', { headers: { 'sdp_suki_token': '', 'sdp_provider_id': '' } }); if (response.ok) { const statusesData = await response.json(); console.log('Supported Medication Order Statuses:'); statusesData.statuses?.forEach((item: any) => { console.log(` ${item.code}`); }); } else { const error = await response.json(); console.error(`Failed to get medication order statuses: ${response.status}`, error); } ``` # Provider Roles Source: https://developer.suki.ai/api-reference/info/provider-roles GET /api/v1/info/provider-roles Get list of supported healthcare provider roles Use this endpoint to get the list of supported provider roles. ## Code examples ```python theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}} import requests url = "https://sdp.suki-stage.com/api/v1/info/provider-roles" headers = { "sdp_suki_token": "", "sdp_provider_id": "" } response = requests.get(url, headers=headers) if response.status_code == 200: provider_roles_data = response.json() print("Supported Provider Roles:") for provider_role in provider_roles_data.get("provider_roles", []): print(f" {provider_role.get('code')}") else: print(f"Failed to get provider roles: {response.status_code}") print(response.json()) ``` ```typescript theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}} const response = await fetch('https://sdp.suki-stage.com/api/v1/info/provider-roles', { headers: { 'sdp_suki_token': '', 'sdp_provider_id': '' } }); if (response.ok) { const providerRolesData = await response.json(); console.log('Supported Provider Roles:'); providerRolesData.provider_roles?.forEach((providerRole: any) => { console.log(` ${providerRole.code}`); }); } else { const error = await response.json(); console.error(`Failed to get provider roles: ${response.status}`, error); } ``` # Supported Medical Specialties Source: https://developer.suki.ai/api-reference/info/specialties GET /api/v1/info/specialties Get list of supported medical specialties and their identifiers Use this endpoint to get the list of supported medical specialties. This list is used to validate the specialty field in the session context when creating or updating an ambient session. For more information about the specialties, refer to the [Medical specialties section](/documentation/specialties). ## Code examples ```python theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}} import requests url = "https://sdp.suki-stage.com/api/v1/info/specialties" headers = { "sdp_suki_token": "", "sdp_provider_id": "" } response = requests.get(url, headers=headers) if response.status_code == 200: specialties_data = response.json() print("Supported Medical Specialties:") for specialty in specialties_data.get("specialties", []): print(f" {specialty.get('code')}") else: print(f"Failed to get specialties: {response.status_code}") print(response.json()) ``` ```typescript theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}} const response = await fetch('https://sdp.suki-stage.com/api/v1/info/specialties', { headers: { 'sdp_suki_token': '', 'sdp_provider_id': '' } }); if (response.ok) { const specialtiesData = await response.json(); console.log('Supported Medical Specialties:'); specialtiesData.specialties?.forEach((specialty: any) => { console.log(` ${specialty.code}`); }); } else { const error = await response.json(); console.error(`Failed to get specialties: ${response.status}`, error); } ``` # Visit Types Source: https://developer.suki.ai/api-reference/info/visit-types GET /api/v1/info/visit-types Get list of supported clinical visit types Use this endpoint to get the list of supported visit types. ## Code examples ```python theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}} import requests url = "https://sdp.suki-stage.com/api/v1/info/visit-types" headers = { "sdp_suki_token": "", "sdp_provider_id": "" } response = requests.get(url, headers=headers) if response.status_code == 200: visit_types_data = response.json() print("Supported Visit Types:") for visit_type in visit_types_data.get("visit_types", []): print(f" {visit_type.get('code')}") else: print(f"Failed to get visit types: {response.status_code}") print(response.json()) ``` ```typescript theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}} const response = await fetch('https://sdp.suki-stage.com/api/v1/info/visit-types', { headers: { 'sdp_suki_token': '', 'sdp_provider_id': '' } }); if (response.ok) { const visitTypesData = await response.json(); console.log('Supported Visit Types:'); visitTypesData.visit_types?.forEach((visitType: any) => { console.log(` ${visitType.code}`); }); } else { const error = await response.json(); console.error(`Failed to get visit types: ${response.status}`, error); } ``` # Medication Orders Info API Source: https://developer.suki.ai/api-reference/medication-orders-info Get supported medication order metadata in one response Use this endpoint to get supported metadata for medication orders in one response, including coding systems, dosage units, frequency types, timings, statuses, origins, and encounter relations. ## Endpoints # Ambient APIs Overview Source: https://developer.suki.ai/api-reference/overview Introduction to the Suki Ambient APIs: REST, Partner WebSocket audio, webhooks, sessions, clinical notes, and structured clinical output Suki provides **REST APIs** that let you add **Ambient Clinical Documentation workflows** to your application. The APIs give you full control over your application workflows and user experience while enabling you to capture visit conversations and generate clinical notes. The Suki Ambient APIs support **ambient sessions** where providers and patients have real-time conversations. During a session, Suki processes encounter audio and produces **clinical notes** for your product to retrieve. Most operations use REST endpoints and return standard [HTTP status codes](/api-reference/https-guidelines). You stream visit audio over the Partner WebSocket (`GET /ws/stream`) using your ambient session ID. Webhooks notify your application when processing is complete, which removes the need for continuous polling. ## Key capabilities The Ambient APIs expose the capabilities below so you can control capture, note quality, and how generated outputs reach your product and downstream systems. Create ambient sessions, stream encounter audio over the Partner WebSocket, and pause, resume, or end capture when the visit is complete. Turn provider-patient conversations into structured clinical notes and full transcripts, then retrieve draft content and metadata after processing finishes. Let patients speak in 80+ languages while Suki generates English notes and transcripts that fit standard EHR workflows. Set provider-level verbosity and section formats through the User Preferences API so generated notes match how each clinician documents care. Organize documentation by patient problems, merge existing diagnoses from context, and retrieve ICD10 and IMO structured output for EHR integration. Extract diagnoses, medications, and other encounter-level artifacts from the conversation for charting, orders, and analytics in your application. Configure which LOINC-based sections appear in generated notes so output aligns with your specialty templates and compliance requirements. Run speech-to-text sessions when you need transcription without the full ambient clinical note workflow. Receive webhook callbacks when processing completes, and submit feedback on transcripts or generated content to track quality over time. ## Requirements Before you can use the Ambient APIs, you need to meet the following requirements: * You must be a Suki partner. Learn more about how to become a Suki partner in the [Partner onboarding](/documentation/partner-onboarding) documentation. * HTTP/2.0 compliant authentication system (e.g. OAuth 2.0, JWT, etc.). * JWT tokens with consistent user identifiers (e.g. `sub`, `email`, `userId`, etc.). * Publicly accessible JWKS endpoint for token verification. ## What you can build Use the Ambient APIs to build custom ambient clinical documentation workflows. Control how sessions are created, how audio is captured and streamed, and how notes and outputs are presented in your product. You can configure note generation based on: * Visit types * Specialties * Compliance requirements * Existing clinical processes etc. Implement your own logic for session state management, note review, editing, and downstream handoff workflows and connect to your EHR, telehealth platform, or internal systems using REST APIs, WebSockets, and optional webhooks. ### Common use cases Create your own ambient session workflow with full control over the user experience, from session creation to note retrieval. Build custom UI and workflow logic for pausing, resuming, and canceling ambient sessions within your application. Integrate ambient session creation, audio streaming, and structured output retrieval directly into your EHR or telehealth platform. ## API versioning All endpoints use the `/api/v1/` prefix. **v1** is the stable version. Non-breaking changes may ship without a major version jump. For policies and migration, refer to [API guidelines](/api-reference/api-guidelines#version-management). These APIs may include Early Access features. If you are unsure what is enabled for your account, contact your Suki representative. ## Available APIs The following set of APIs are available for the ambient and dictation workflows. View each card below to learn more about the endpoints that are available and how to use them. Endpoints for authentication and authorization. Endpoints for ambient session management. Endpoints for dictation. Endpoints for content retrieval after the session is completed. Endpoints for managing the user preferences. Endpoints for managing user feedback. Endpoints for managing notifications to your service. Endpoints for retrieving information about the encounter type, visit type, and provider role. Endpoints for retrieving information about the medication orders. ## Suki Ambient APIs workflow To integrate with the Suki Ambient API, you follow a session-based workflow. ```mermaid actions={false} theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}} flowchart TD Start([Start Session]) --> Auth[Authentication] Auth --> Check{User registered?} Check -->|No| Register[Register new user] Register --> Auth Check -->|Yes| Token[Get sdp_suki_token] Token --> Create[Create session] Create --> SessionID[Get session_id] SessionID --> Context{Seed Context?} Context -->|Yes| AddContext[Add additional context] Context -->|No| Stream AddContext --> Stream[Stream audio chunks] Stream --> Control[PAUSE/RESUME
/KEEP_ALIVE] Control --> Done{Session Complete?} Done -->|No| Stream Done -->|Yes| End[Generate note] End --> Wait[AI processing] Wait --> Notify{Webhook configured?} Notify -->|Yes| Hook[Receive notification] Notify -->|No| Poll[Poll status] Hook --> Retrieve Poll --> Retrieve[Retrieve note] Retrieve --> Complete([Session Complete]) classDef authStyle fill:#FFE148,stroke:#D4A017,stroke-width:2px,color:#000000 classDef registerStyle fill:#FFF394,stroke:#FFE148,stroke-width:2px,color:#000000 classDef highlightStyle fill:#FFD700,stroke:#D4A017,stroke-width:3px,color:#000000 class Auth,Create,Stream,End authStyle class Register registerStyle class Retrieve highlightStyle ``` ### Developer workflow Authenticate with Suki to get a Suki authentication token also called `suki_token`. Create an ambient session to start a new visit. Stream visit audio over WebSocket to the Suki backend. End the session when the visit is complete. Retrieve generated outputs through REST endpoints. If webhooks are enabled for your partner account, your application receives automatic completion notifications instead of relying only on polling. **Best practices** * Store **partner\_id**, **partner\_token**, and issued tokens securely; rotate credentials per your security policy. * Send API traffic over HTTPS and validate webhook signatures when your integration receives callbacks. * Read HTTP status and error bodies from REST responses; handle auth expiry by refreshing **suki\_token** as documented. ## Next steps Refer to the [Ambient APIs quickstart](/api-reference/quickstart) to get started. # API Changelog Source: https://developer.suki.ai/api-reference/product-updates/changelog API product updates and announcements Suki's API versioning policy is based on the semantic versioning standard. For example, in version 1.2.3, 1 is the major version, 2 is the minor version, and 3 is the patch version. When we release a new API version for new features or bug fixes, we increment one of these three version components depending on the type of change introduced. **API version numbering policy** All Suki REST APIs are currently in `v1` version. **Release version** The release version in this changelog page represents the incremental progress. It is not the API version. It tracks new optional fields, performance improvements, new endpoints, and other changes.

No changelog entries match this filter. Choose All or another scope.

### Enhancements * Suki now supports **Single Auth Token authentication**: your backend can use one shared `partner_token` for all clinicians instead of a per-user token. The shared token proves your organization is authorized, but it does not identify who is signed in. If you use this model, you **must** send `sdp_provider_id` on every API call so Suki can route each call to the correct clinician. Learn more in the [Provider authentication](/api-reference/provider-authentication) documentation. ```json JSON theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}} { "sdp_suki_token": "your-suki-token", // sdp_suki_token required for all API calls // Required with Single Auth Token auth: send sdp_provider_id on Register, Login, and every API call "sdp_provider_id": "doc1234567890" } ``` ### New endpoints * **Info endpoints**: Added new endpoints to get the list of supported medication coding systems, dosage units, encounter relations, frequencies, medication timings, origins, and statuses. * GET [/api/v1/info/orders/coding-systems](/api-reference/info/orders-coding-systems) * GET [/api/v1/info/orders/dosage-units](/api-reference/info/orders-dosage-units) * GET [/api/v1/info/orders/encounter-relations](/api-reference/info/orders-encounter-relations) * GET [/api/v1/info/orders/frequencies](/api-reference/info/orders-frequencies) * GET [/api/v1/info/orders/medication-timings](/api-reference/info/orders-medication-timings) * GET [/api/v1/info/orders/origins](/api-reference/info/orders-origins) * GET [/api/v1/info/orders/statuses](/api-reference/info/orders-statuses) ### Enhancements * **Medication orders**: You can now send and retrieve medication orders for an ambient session and encounter using the following endpoints. **Structured data endpoints**: These endpoints return the structured data for an ambient session and encounter. * GET [/api/v1/ambient/session//structured-data](/api-reference/ambient-content/structured-data) * GET [/api/v1/ambient/session//encounter-structured-data](/api-reference/ambient-content/encounter-structured-data) **Context API**: This endpoint allows you to update the ambient session context with new EMR context and medication orders. * POST [/api/v1/ambient/session//context](/api-reference/ambient-sessions/update-context) **Content API**: This endpoint returns the content for an ambient session and encounter. * GET [/api/v1/ambient/session//content](/api-reference/ambient-content/content) * GET [/api/v1/ambient/session//encounter-content](/api-reference/ambient-content/encounter-content) **Payload structure**: ```json JSON theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}} { "structured_data": { "orders": { "medication_orders": { "values": [ { "drug_name": "Drug Name", "status": "Status", "medication_code": "Medication Code", "medication_code_type": "Medication Code Type" } ] } } } } ``` When you send medication orders to the context API, the medication orders are validated against the EMR context. If the medication orders are not valid, the context API will return an error. Learn more in the [Medication orders](/documentation/medication-orders) documentation.

### New endpoints * **Audio streaming and download**: We've added a new endpoint for audio streaming and download from ambient sessions. Stream or download the audio recording from an ambient session. * GET [/api/v1/ambient/session//recording](/api-reference/ambient-content/recording) Learn more in the [Audio streaming and download](/documentation/audio-streaming-download) documentation.

### Deprecated * **Multilingual support**: The `multilingual` parameter is deprecated in the `Create Ambient Session` endpoint. When you call create ambient session API, the multilingual support is now **set to true by default**.

### New endpoints * **Audio Dictation API**: Added support for real-time audio transcription/dictation. Create dictation sessions, stream audio data, and end sessions to get final transcripts. This enables use cases like dictation, real-time captioning, and transcript generation. * POST [/api/v1/transcription/session/create](/api-reference/audio-transcription/create-session) * POST [/api/v1/transcription/session//end](/api-reference/audio-transcription/end-session) * GET [/ws/transcribe](/api-reference/audio-transcription/stream-transcription)

### Enhancements * **Code examples**: Added code examples in Python and TypeScript for all APIs, making it easier to integrate with the platform regardless of your preferred programming language.

### New endpoints * **Info endpoints**: Introduced three new info endpoints to provide supported enum values, helping you validate context data before submission and ensuring data consistency. * GET [/api/v1/info/encounter-types](/api-reference/info/encounter-types) * GET [/api/v1/info/visit-types](/api-reference/info/visit-types) * GET [/api/v1/info/provider-roles](/api-reference/info/provider-roles) * **API reference guidelines**: Added a new [API reference guidelines](/api-reference/api-guidelines) page to help you understand API status tags, versioning, and documentation standards. ### Enhancements * **Enhanced API documentation**: Significantly restructured and enhanced API reference documentation for better developer experience, clearer organization, and improved discoverability. * **Problem-based charting guide**: Completely rewritten the Problem-Based Charting (PBC) guide with a clearer structure and more detailed explanations of the processing pipeline. * **Audio streaming authentication**: Added detailed authentication guidance for both browser and non-browser clients in the Audio streaming API reference documentation. * **Enhanced context support**: Updated the [Ambient session context APIs](/api-reference/ambient-sessions/context) to support a new `VisitContext` schema, including fields like `chief_complaint` and `visit_type`. The provider context has also been enhanced to support `provider_role`. ### Removed support * **SNOMED codes**: SNOMED codes are no longer supported for the diagnosis context * **Paused state**: Paused state is no longer supported for ambient sessions

# Provider Authentication Source: https://developer.suki.ai/api-reference/provider-authentication Learn how to authenticate providers and users to use the Suki ambient APIs **Not a Suki Partner yet?** To use the Suki APIs, you must first register your organization as a partner. To begin, follow the [Partner onboarding](/documentation/partner-onboarding) guide to learn more or schedule a call with Suki using the **Ask AI** chat assistant. After you register, you use a Partner Token (`partner_token`) to authenticate your API requests. The `partner_token` is a JWT that **you** provide, and it is a **required parameter** when registering a provider. Find more details on how to get a `partner_token` in the [Partner authentication](/documentation/partner-authentication) guide. All Suki Partner APIs require partner authentication. To authenticate, exchange your Partner Token (`partner_token`) to get a Suki access token. Use the Suki access token to call the [Register](/api-reference/authentication/register) and [Login](/api-reference/authentication/login) APIs and authenticate clinicians with Suki. Suki access tokens are valid for **1 hour**. This guide explains the **two main endpoints** for the authentication workflow: * **Register user**: A **one-time** call to register a **new provider** in the Suki system. * **Authenticate user**: Call this endpoint to get a **suki\_token** (`sdp_suki_token`) for a registered provider. ## Authentication methods Suki supports the following authentication methods. Suki configures your method during [Partner onboarding](/documentation/partner-onboarding). ### Standard partner authentication Each clinician authenticates with their own `partner_token`. Suki derives provider identity from that token, so you do not need to send `provider_id` on Register or Login. **Best for** * Enterprise deployments where each clinician has their own account in your identity provider * Integrations where your IdP issues a per-user ID token or user-scoped JWT as `partner_token` * Flows where the token already identifies the signed-in provider without a separate `provider_id` ### Single Auth Token authentication Your backend uses one shared `partner_token` for multiple clinicians. The token proves your organization is authorized, but it does not identify who is signed in. Send `provider_id` on every Register, Login, and API request. **Best for** * Server backends that authenticate to Suki with one organization-level token for many clinicians * Applications that already know the active provider from your session, EHR, or user directory * Identity setups that cannot include per-user claims in the `partner_token` * Bearer partner configurations (refer to [Bearer partner authentication](/api-reference/bearer-partner-authentication)) If you plan to use Single Auth Token authentication, see [Authentication with a Single Auth Token](/api-reference/provider-authentication#authentication-with-a-single-auth-token) for more details. * To refresh a Suki access token, send another **POST** request to [Login](/api-reference/authentication/login) with a valid `partner_token`. * You need the Suki access token to call all Suki REST and WebSocket APIs. If you are a Bearer partner, you must send `sdp_provider_id` on every REST API and WebSocket API call. Refer to [Bearer partner authentication](/api-reference/bearer-partner-authentication) for more details. ## Register provider/user account Use the below endpoint to **register** a new **provider/user** in the Suki platform. You only need to do this **once** for each new provider. **Endpoint**: [Register](/api-reference/authentication/register) **Method:** POST ### Registration scenarios Flowchart: POST register leads to User Exists; if No, New User Registration, Create User and Link, then Response 201; if Yes, Linked to this Partner; if No, Existing User New Partner Link, Link User to Partner, then Response 201; if Yes, Existing User Already Linked, then Response 409 Conflict.

Flowchart: POST register leads to User Exists; if No, New User Registration, Create User and Link, then Response 201; if Yes, Linked to this Partner; if No, Existing User New Partner Link, Link User to Partner, then Response 201; if Yes, Existing User Already Linked, then Response 409 Conflict.

The `Register` endpoint handles three main scenarios: * **New user registration**: If the provider **does not exist** in the Suki system, this call **creates a new user** and links them to your partner account and organization. * **Existing user, new partner link**: If the provider **already exists** but is not linked to your partner account, this call **links them to your partner** and their existing organization. * **Existing user, already linked**: If the provider is already registered and linked to your partner account, the API returns a `409` Conflict error. ## Authenticate provider/user session After a provider is registered, call [Login](/api-reference/authentication/login) endpoint to get a Suki access token (`sdp_suki_token`). If you are a Bearer partner, you must send `provider_id` on every API call, including [Login](/api-reference/authentication/login). Refer to [Bearer partner authentication](/api-reference/bearer-partner-authentication) for more details. ### JWKS endpoint Suki provides a public **JWKS (JSON Web Key Set)** endpoint that you can use to verify the signature of the `sdp_suki_token` that our API returns. **Endpoint:** [JWKS URL](/api-reference/authentication/jwks) **Method:** GET **Authentication:** None (Public) ### Use cases Diagram: Fetch Public Keys leads to JWKS Endpoint; from JWKS, three branches to Token Verification, Signature Validation, and Key Rotation.

Diagram: Fetch Public Keys leads to JWKS Endpoint; from JWKS, three branches to Token Verification, Signature Validation, and Key Rotation.

* **Token verification**: Fetch public keys to verify JWTs issued by Suki. * **Signature validation**: Validate the signature of the `sdp_suki_token`. * **Key rotation**: Automatically discover new public keys when Suki rotates our signing keys. ## Authentication with a Single Auth Token Some partners use **one shared `partner_token`** for all providers instead of a per-user token from their identity provider. Suki configures this during [Partner onboarding](/documentation/partner-onboarding). Because the shared token does not identify which clinician is signed in, your backend must send **`provider_id`** in the body of Register and Login requests and **`sdp_provider_id`** as a header on every subsequent request so Suki knows who each request is for. ### Typical flow **Register** each clinician once with [Register](/api-reference/authentication/register). Use a stable **`provider_id`** for that person. **Login** with [Login](/api-reference/authentication/login). Send your `partner_id`, shared `partner_token`, and the active clinician's **`provider_id`**. **Call Suki APIs** with the **`sdp_suki_token`** returned from Login. Include the **`sdp_provider_id`** header on every REST and WebSocket request. **Refresh** the token before it expires (**1 hour**). Call Login again with the same `partner_token` and `provider_id`. ### Send sdp\_provider\_id with all API requests When you use **Single Auth Token authentication method** for all clinicians, include the `sdp_provider_id` header on **every** Suki API request after Login. The token proves your organization is authorized; it does not identify which clinician is acting. You pass `sdp_provider_id` to tell Suki that. * **Register and Login:** Your app already knows which clinician is signing in. Send that person's identifier as `provider_id` so Suki can register or authenticate them. * **All other APIs:** After Login, send `sdp_provider_id` on every REST and WebSocket request along with `sdp_suki_token`. Suki uses it to route the request to the correct clinician. Register each provider with a stable `provider_id` before their first Login. If Login fails because the provider is not registered, call Register, then call Login again. For request fields, security guidance, and examples, refer to [Bearer partner authentication](/api-reference/bearer-partner-authentication). # Ambient API Quickstart Source: https://developer.suki.ai/api-reference/quickstart Step-by-step guide to authenticate, create a session, stream audio, and retrieve the clinical note This guide walks you through the steps to use the Suki Ambient APIs to create an ambient session, stream audio, and retrieve the clinical note. **What you will do** 1. **Authenticate** to get a Suki token (and **register** the user if needed). 2. **Create** an ambient session and optionally **seed context** for better notes. 3. **Stream audio** over the WebSocket, send control events, and **end** the session when the visit is done. 4. **Retrieve** the clinical note and transcript, or rely on a **webhook** when processing finishes. **Using an AI coding tool?** Copy the following prompt to add the Suki developer documentation as a skill and [MCP server](/documentation/mcp) to your tool for better AI-assisted coding during the integration process. For all AI options (contextual menu, `llms.txt`, and `skill.md`), refer to [AI-optimized documentation](/documentation/ai-optimized-documentation). Install the Suki developer docs as skill to get context on Suki's developer tools, APIs, and SDKs. npx skills add [https://developer.suki.ai](https://developer.suki.ai) Then add the Suki developer docs MCP server for access to documentation search. Follow the MCP instructions at [https://developer.suki.ai/documentation/mcp](https://developer.suki.ai/documentation/mcp). ## Access and credentials You need partner credentials to use the Suki Ambient API. Contact our [Partnership team](https://www.suki.ai/suki-partners/) to get your credentials. They will guide you through the [Onboarding process](/documentation/partner-onboarding) and provide what you need to get started. ### Prerequisites To use the Suki Ambient APIs, you must have the following: * An OAuth-compliant authentication system * JWT tokens with consistent user identifiers * A publicly accessible JWKS endpoint (or Okta authorization server) for token validation Refer to the [Partner onboarding](/documentation/partner-onboarding) and [Partner authentication](/documentation/partner-authentication) guides for more details. ### Environments to use for development and testing This guide uses **`https://sdp.suki-stage.com`** and **`wss://sdp.suki-stage.com`** for API and WebSocket examples (staging). **Important**: * The production environment is **`https://sdp.suki.ai`** and **`wss://sdp.suki.ai`**. * The staging environment is **`https://sdp.suki-stage.com`** and **`wss://sdp.suki-stage.com`**. * Your partnership team will confirm which environment, base URL, and credentials apply for your integration. ## Step 1: Authenticate and get token To begin, you must authenticate to get your access token. Send a **POST** request to the [/api/v1/auth/login](/api-reference/authentication/login) endpoint with the following parameters in the request body: 1. **partner\_id**: Your unique Partner ID, which we provide to you securely offline. 2. **partner\_token**: The user's OAuth 2.0 ID token (Partner Token) from your identity provider. 3. **provider\_id** (Optional): Unique identifier for the provider. Required for Bearer type partners only. Suki verifies the `partner_token` using your publicly exposed **JWKS endpoint** (or your Okta authorization server URL if you use Okta). On a successful request, the API returns a Suki Token (`suki_token`) that you must include as the `sdp_suki_token` header for all subsequent API calls. **Handling an unregistered user**: * If the user is not yet registered in our system, the `/login` request will fail. * In this case, you must first call the [/api/v1/auth/register](/api-reference/authentication/register) endpoint to create the user, then call `/login` again. * You only need to call the register endpoint once for each new user. * Refer to the [Register API reference](/api-reference/authentication/register) for the full specification. ```bash cURL theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}} curl -X POST https://sdp.suki-stage.com/api/v1/auth/login \ -H "Content-Type: application/json" \ -d '{ "partner_id": "your-partner-id", "partner_token": "your-jwt-token", "provider_id": "provider-123" }' ``` Save the `suki_token` from the response. This token is valid for **1 hour**. When it is about to expire, you can get a new one by making the same **POST** request to `/login` with a valid `partner_token`. ## Step 2: Create ambient session To start an ambient session, send a **POST** request to the [/api/v1/ambient/session/create](/api-reference/ambient-sessions/create) endpoint with the following parameters in the request body: This guide uses `encounter_id`. In older versions of the API, this parameter was named `session_group_id`. The old name will be deprecated in a future release. The `multilingual` parameter is deprecated. Multilingual support is now **true** by default for all Suki for Partner users. 1. **encounter\_id** (Optional): A unique identifier for the patient encounter (also called a visit). This can be any alphanumeric string up to **255 characters** long. 2. **ambient\_session\_id** (Optional): A UUID v4 to identify the session. If you do not provide one, Suki will generate it and include it in the response. ```bash cURL theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}} curl -X POST https://sdp.suki-stage.com/api/v1/ambient/session/create \ -H "sdp_suki_token: YOUR_SUKI_TOKEN" \ -H "sdp_provider_id: " \ -H "Content-Type: application/json" \ -d '{ "ambient_session_id": "123dfg-456dfg-789dfg-012dfg", "encounter_id": "123dfg-456dfg-789dfg-012dfg" }' ``` Save the `ambient_session_id` from the response. You will need it to stream audio and retrieve content. ## Step 3: Seed context After creating the session, you can send a **POST** request to the [/api/v1/ambient/session//context](/api-reference/ambient-sessions/context) endpoint to provide additional metadata. Providing **context** significantly improves the accuracy of the generated clinical note. Include the following parameters in the request body: * **provider\_specialty** (Optional): The specialty of the provider (e.g., "cardiology"). * **sections** (Optional): A list of the clinical sections you want summarized, such as "Assessment and Plan" or "Chief Complaint". If you do not provide this, a default set of sections will be used. * **patient\_info** (Optional): An object containing `date_of_birth` (for accurate age calculation) and `sex` (**MALE**, **FEMALE**, **OTHER**, or **UNKNOWN**; defaults to **UNKNOWN**). Refer to the [Context API reference](/api-reference/ambient-sessions/context) for the full request structure. ## Step 4: Stream audio via WebSocket After you **create** the ambient session and **seed context** (previous steps), open a **WebSocket** to `wss://sdp.suki-stage.com/ws/stream`. Upgrading before the session exists or before context is ready often fails. For authentication, use the `Sec-WebSocket-Protocol` header (browser clients) with the comma-separated value `SukiAmbientAuth,,`, or send `sdp_suki_token` and `ambient_session_id` as separate HTTP headers on the upgrade (non-browser clients). See the [Audio streaming API reference](/api-reference/ambient-sessions/audio-stream) for the full wire format and code samples. **Audio format**: You must stream **raw PCM** in each `AUDIO` message (after Base64 encoding) with: * **encoding**: LINEAR16 * **sample\_rate**: 16KHz * **channel**: Mono `.wav` files are containers; strip the usual **44-byte** WAV header (or decode to PCM) before chunking. Sending RIFF headers as PCM hurts recognition. For optimal performance, we recommend chunking the audio into **100ms packets**. **Outbound WebSocket messages** must each be **one JSON text frame** (one object per send). Use proto JSON field names: **`type`** and **`data`** for `START_TIME` and `AUDIO`. The **`data`** field is always **standard Base64** (RFC 4648) of **raw bytes**. Do not send PCM as binary WebSocket frames on this endpoint. **Required send order** for a stream segment: 1. **`START_TIME`**: `data` is Base64 of the UTF-8 RFC 3339 timestamp string. 2. **`AUDIO`**: one or more messages with `data` set to Base64 of each PCM chunk. 3. **End marker**: an **`AUDIO`** message whose `data` is Base64 of the three bytes **`EOF`** (ASCII), value **`RU9G`**. Do not use `{"type":"end_of_stream"}` for this protocol. **`EVENT` messages** use **`{"type":"EVENT","event":""}`** (not `data` for the action). Supported values include: * **PAUSE**: Pauses the stream. * **RESUME**: Resumes a paused audio stream. * **CANCEL**: Immediately mark an ambient session as CANCELLED in our system, it closes the WebSocket. The session cannot be resumed again; create a new session if you want to record again. * Deprecated **ABORT**: Aborts the stream due to an interruption. A note will be generated from the audio received so far. The session remains active and can be resumed. * **KEEP\_ALIVE**: Pings the server to keep the connection alive during periods of inactivity (e.g., when paused). When you are done sending audio, **close the WebSocket**, then call the **end session** endpoint (next step) and **poll status and REST content endpoints** for the final note and transcript. Final results are not guaranteed from the WebSocket alone. **Keep the connection alive**: You must send a **KEEP\_ALIVE** event at least once every **five seconds** when the stream is paused to prevent the connection from closing. **Stream behavior and timeouts**: 1. **Session Timeouts**: If no audio data is sent for **25 seconds**, Suki will disconnect the stream. 2. **Paused Stream**: If the stream is paused and receiving KEEP\_ALIVE events, Suki will disconnect the stream after **30 minutes** of inactivity. **CANCEL vs. ABORT**: Sending **CANCEL** terminates the session completely. No note will be generated. Sending **ABORT** ends the current stream, but the session remains **active**. Suki will generate a note from the audio received before the interruption. Resume streaming to the same `ambient_session_id` later. ## Step 5: End session To complete the session and begin the note generation process, send a **POST** request to the [/api/v1/ambient/session//end](/api-reference/ambient-sessions/end) endpoint. This signals that no more audio will be sent for this session. ```bash cURL theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}} curl -X POST "https://sdp.suki-stage.com/api/v1/ambient/session/YOUR_SESSION_ID/end" \ -H "sdp_suki_token: YOUR_SUKI_TOKEN" \ -H "sdp_provider_id: " ``` ## Step 6: Retrieve generated content Once the note is ready, Suki notifies your application. The recommended way to know when a note is ready is to use a **webhook**. Suki will send a `session_summary_generated` event to a webhook endpoint that you provide. Details on configuring your webhook and its authentication will be provided during the onboarding process. **Retrieving content manually**: Alternatively, you can use the following endpoints to check the status and retrieve the session's content: 1. [GET /api/v1/ambient/session//status](/api-reference/ambient-content/status): Check the processing status of a session. 2. [GET /api/v1/ambient/session//content](/api-reference/ambient-content/content): Retrieve the final, structured clinical note. 3. [GET /api/v1/ambient/session//transcript](/api-reference/ambient-content/transcript): Get the full conversation transcript, including **timestamps** for each part of the dialogue. ```bash cURL theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}} # Get clinical note curl -X GET "https://sdp.suki-stage.com/api/v1/ambient/session/YOUR_SESSION_ID/content?cumulative=false" \ -H "sdp_suki_token: YOUR_SUKI_TOKEN" \ -H "sdp_provider_id: " # Get transcript curl -X GET "https://sdp.suki-stage.com/api/v1/ambient/session/YOUR_SESSION_ID/transcript" \ -H "sdp_suki_token: YOUR_SUKI_TOKEN" \ -H "sdp_provider_id: " ``` **Session Duration Requirement** Your ambient session must be **at least 1 minute long** for note generation to occur. Sessions shorter than 1 minute will receive a `SKIPPED` status, meaning no clinical note was generated. For complete technical specifications, please refer to the relevant API Reference pages. ## Next steps After completing your first session, explore these resources to deepen your integration: [Authentication API](/api-reference/authentication/login) - Login, register, and JWKS configuration. [Context API](/api-reference/ambient-sessions/context) - Seed specialty, sections, and patient info for better note accuracy. [Audio Streaming API](/api-reference/ambient-sessions/audio-stream) - WebSocket connection details and message formats. [Webhook](/api-reference/asynchronous/webhook) - Configure webhooks to receive notifications when notes are ready. # Security & Best Practices Source: https://developer.suki.ai/api-reference/security-best-practices Learn about the best practices for securing your Suki APIs This section provides best practices for securing your Suki APIs and SDKs. ## Security best practices All API requests must use **HTTPS** (TLS 1.2 or higher) to ensure data encryption in transit. Never send requests over unencrypted HTTP connections. ### Token management Following are the best practices for token management: Never expose `sdp_suki_token` in client-side code, logs, or version control. Store tokens securely on your backend server. Implement token refresh logic to automatically obtain a new `sdp_suki_token` when the current one expires. Call the `/login` endpoint with a valid partner token to refresh. When receiving `sdp_suki_token` from Suki, verify its signature using the public keys from the JWKS endpoint ([Authentication JWKS](/api-reference/authentication/jwks)) (`/api/auth/.well-known/jwks-pub.json`). Your partner token must be a standards-compliant JWT signed with RS256 (RSA Signature with SHA-256) algorithm. Ensure your JWKS endpoint is publicly accessible and properly configured. ### Webhook security Following are the best practices for webhook security: Suki signs webhook POSTs with **HMAC-SHA-256**. A **secret key** on your **partner record** is provided by Suki. Each request sends **`generated-at`** (Unix ms) and **`X-API-Key`** (hex HMAC of `generated-at`, a colon, and the raw JSON body). Verify before you process the body. For the exact steps, refer to [Notification webhook for Partners](/documentation/webhook/signature-verification) for more details. Your webhook callback URL must use HTTPS protocol. Never use HTTP endpoints for webhooks. Always validate the webhook payload structure and verify the HMAC signature before processing notifications. ### Data protection Following are the best practices for data protection: All data transmitted to and from Suki is encrypted using TLS 1.2. Ensure your application maintains encryption standards for data at rest. Ensure your integration complies with HIPAA requirements. Obtain patient consent before sending personal data to the platform. Only send the minimum required data for each API call. Avoid including unnecessary patient or provider information. ### Error handling Following are the best practices for error handling: If you receive a `401 Unauthorized` or `403 Forbidden` response, verify your `sdp_suki_token` is valid and not expired. Re-authenticate if necessary. For transient errors (5xx status codes), implement exponential backoff retry logic. Do not retry on 4xx client errors. When logging API errors, never include tokens, passwords, or sensitive patient data in logs. For more details on security and compliance, see the [Security FAQs](/documentation/faqs/security). # Send Notifications API Source: https://developer.suki.ai/api-reference/send-notifications Receive asynchronous notifications from Suki using your notification endpoint Configure your application to expose an HTTPS URL that accepts inbound requests when asynchronous work completes. Suki calls that URL with a signed or documented payload so your backend can pull results or update job state without polling. Learn more about how to configure your application to receive notifications from Suki in the [Notification webhook for partners](/documentation/webhook/overview) documentation. ## Usage scenarios * Receive asynchronous notifications from Suki using your notification endpoint * Receive notifications when a session is completed or failed * Receive notifications when a session is timed out or cancelled * Receive notifications when a session is created or updated * Receive notifications when a session is deleted * Receive notifications when a session is started or stopped * Receive notifications when a session is paused or resumed ## Endpoints # User Feedback API Source: https://developer.suki.ai/api-reference/user-feedback Submit feedback on ambient session entities such as transcripts or generated content Send structured feedback tied to a session and a specific entity so Suki can track quality issues, regressions, or user-reported problems against concrete artifacts. ## Usage scenarios * Submit feedback on ambient session entities such as transcripts or generated content ## Endpoints # User Preferences API Source: https://developer.suki.ai/api-reference/user-preferences Read and update end-user preferences for the Suki platform Use this endpoint to read or change preferences for the authenticated user so your client stays aligned with Suki defaults for language, layout, or other user-scoped settings exposed by the API. ## Endpoints # User Preferences Source: https://developer.suki.ai/api-reference/user-preferences/preferences PATCH /api/v1/user/preferences Update user personalization preferences for clinical note generation Use this endpoint to update and save a user's personalization preferences. These settings are saved at the user level, not per session, and will be applied to all of the user's future interactions. For details, see [Personalization](/api-reference/capabilities/personalization). Section format preferences use LOINC codes to identify note sections. This is a `PATCH` request, you only need to send the fields you want to change. For the best results, we recommend that you call this endpoint before the **main interaction begins** (for example, before audio streaming starts or before you call the `/end` endpoint). This ensures the user's preferences are applied before content is generated. However, you can call this endpoint at any time to update the settings. ## Code examples ```python theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}} import requests url = "https://sdp.suki-stage.com/api/v1/user/preferences" headers = { "sdp_suki_token": "", "sdp_provider_id": "", "Content-Type": "application/json" } payload = { "personalization_preference": { "verbosity": "CONCISE", # Options: CONCISE, BALANCED, DETAILED "section_format": [ { "loinc": "10164-2", "style": "NARRATIVE" # Options: NARRATIVE, BULLETED } ] } } response = requests.patch(url, json=payload, headers=headers) if response.status_code == 200: data = response.json() print("Preferences updated successfully") print(f"Updated preferences: {data}") else: print(f"Failed to update preferences: {response.status_code}") print(response.json()) ``` ```typescript theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}} const response = await fetch('https://sdp.suki-stage.com/api/v1/user/preferences', { method: 'PATCH', headers: { 'sdp_suki_token': '', 'sdp_provider_id': '', 'Content-Type': 'application/json' }, body: JSON.stringify({ personalization_preference: { verbosity: 'CONCISE', // Options: CONCISE, BALANCED, DETAILED section_format: [ { loinc: '10164-2', style: 'NARRATIVE' // Options: NARRATIVE, BULLETED } ] } }) }); if (response.ok) { const data = await response.json(); console.log('Preferences updated successfully'); console.log('Updated preferences:', data); } else { const error = await response.json(); console.error(`Failed to update preferences: ${response.status}`, error); } ``` # Dictation SDK Changelog Source: https://developer.suki.ai/dictation-sdk/changelog Dictation SDK product updates and announcements Suki's Dictation SDK versioning policy is based on the semantic versioning standard. For example, in version 1.2.3, 1 is the major version, 2 is the minor version, and 3 is the patch version. When we release a new Dictation SDK version for new features or bug fixes, we increment one of these three version components depending on the type of change introduced. ### New features * **Initial beta release**: First release of the Suki Dictation SDK. Build custom speech-to-text integrations with complete control over your user interface. Currently in **beta** stage for you to try out and provide feedback. # General Source: https://developer.suki.ai/dictation-sdk/faqs/general General questions about the Suki Dictation SDK The Suki Dictation SDK is a JavaScript and React library for dictation in the browser. It lets you add speech-to-text to your web application using Suki's hosted dictation experience, authentication helpers, and callbacks. Read the [Dictation SDK Overview](/dictation-sdk/introduction) for supported packages, In-field and Scratchpad modes, and how a typical session flows. You can build dictation in two ways: * **In-field:** Dictation overlays a target field. This pattern fits notes, forms, and similar workflows. * **Scratchpad:** Dictation uses a floating panel that is not tied to a single input. Read [In-field mode](/dictation-sdk/guides/in-field-mode) and [Scratchpad mode](/dictation-sdk/guides/scratchpad-mode). The [Introduction](/dictation-sdk/introduction) page also summarizes both. **Dictation SDK:** Your app embeds dictation in the browser. The SDK handles platform authentication with **`SukiAuthManager`**, the iframe lifecycle, and callbacks such as **`onSubmit`**. **Dictation APIs:** You call Suki's REST and WebSocket dictation APIs from your own code without using this iframe SDK. That path is documented under [Audio dictation](/documentation/dictation) and the [Dictation API](/api-reference/ambient-dictation) reference. The [Introduction](/dictation-sdk/introduction) page includes a short note that compares the two approaches. Every setup uses **`@suki-sdk/core`** for **`SukiAuthManager`**. You then add one surface package: * **JavaScript (vanilla or non-React frameworks):** **`@suki-sdk/dictation`** plus **`@suki-sdk/core`**. * **React:** **`@suki-sdk/dictation-react`** plus **`@suki-sdk/core`**. You still import **`DictationClient`** from **`@suki-sdk/dictation`** in examples when you construct the client in code. Copy-paste install commands are in [Installation](/dictation-sdk/installation). Package names also appear on the [Introduction](/dictation-sdk/introduction) page. No. The product is meant for **browser** embedding. Your page needs a real **`HTMLIFrameElement`**, **`postMessage`**, and layout so the hosted UI can mount and size correctly. **Not supported:** Using Node.js as the runtime that hosts **`DictationClient`** or the dictation iframe, or relying on **SSR alone** to render dictation instead of initializing on the client after the DOM (and your container, when you use one) exists. Read the runtime section in [Error handling](/dictation-sdk/guides/error-handling) and [Prerequisites](/dictation-sdk/prerequisites). # Integration Source: https://developer.suki.ai/dictation-sdk/faqs/integration Integration questions about the Suki Dictation SDK **JavaScript:** Use **`DictationClient`** from **`@suki-sdk/dictation`** and call **`await dictationClient.show({ ... })`** when the user should dictate. Walk through [Dictation SDK JavaScript integration](/dictation-sdk/javaScript-integration/javaScript). **React:** Use **`DictationProvider`** and **`Dictation`** from **`@suki-sdk/dictation-react`**, with the same **`DictationClient`** instance passed into the provider. Walk through [Dictation SDK React integration](/dictation-sdk/react-integration/react). Pick the guide that matches your stack. The [Quickstart](/dictation-sdk/quickstart) shows both patterns in one place if you want a shorter comparison. The documentation treats **`SukiAuthManager`** and **`DictationClient`** as **long-lived** for a page or session. If you create a new **`DictationClient`** on every render or for every textarea, the iframe and session tend to tear down and start again, which feels unstable. That guidance is spelled out in the [Quickstart](/dictation-sdk/quickstart) (recommended integration pattern) and in the best-practices sections of the [JavaScript](/dictation-sdk/javaScript-integration/javaScript) and [React](/dictation-sdk/react-integration/react) integration guides. Call **`show()`** again with the next field's options. A new **`show()`** call **replaces** the active session. You do **not** need to call **`hide()`** manually just to move from one field to another for that pattern. See [JavaScript integration](/dictation-sdk/javaScript-integration/javaScript) and [Configuration](/dictation-sdk/guides/configuration) for examples and option details. Keep a **single** **`client`** and **`DictationProvider`**. Use state (for example **`activeFieldId`** or a boolean) so **only one** **`Dictation`** is mounted at a time, or change **`fieldId`** / **`initialText`** when you remount. You do **not** need to call **`hide()`** yourself for that kind of switch. Full pattern: [React integration](/dictation-sdk/react-integration/react). When **`Dictation`** unmounts, the SDK **automatically** calls **`hide()`**. For normal React flows you do **not** call **`hide()`** yourself. Details: [React integration](/dictation-sdk/react-integration/react). # Technical Source: https://developer.suki.ai/dictation-sdk/faqs/technical Technical questions about the Suki Dictation SDK **Required** * **`partnerId`** * **`partnerToken`** **Optional** (when your integration needs them) * **`environment`** (for example **`"staging"`** or **`"production"`**) * **`autoRegister`** * **`loginOnInitialize`** Field descriptions and **AuthConfig** details are in [Configuration](/dictation-sdk/guides/configuration) and [Authentication](/dictation-sdk/guides/authentication). Invalid **`partnerId`** or **`partnerToken`** block iframe initialization, as noted on those pages and in [Prerequisites](/dictation-sdk/prerequisites). **`fieldId`** is a **stable, unique** string that names one dictation session. Every callback returns it together with **`text`** so you know which field the result belongs to. It does **not** have to match a DOM **`id`**, but using the same string as your input's **`id`** is a simple pattern. Naming examples and guidance: [Configuration](/dictation-sdk/guides/configuration) (Field IDs in practice) and [Callbacks](/dictation-sdk/guides/callbacks). **`onSubmit`** runs when the user **commits** the transcript. If you omit it, dictation often **closes immediately** after the user acts, so production integrations should always implement it. Read [Configuration](/dictation-sdk/guides/configuration) and [Callbacks](/dictation-sdk/guides/callbacks) for the full callback contract. **`rootElement`** is the **DOM node** where the SDK mounts the dictation iframe. The iframe **sizes to that container**, so the node should have real width and height. **Layout:** Wrapper markup and CSS patterns are described under **Wrapper layout** on the [Configuration](/dictation-sdk/guides/configuration) page. [In-field mode](/dictation-sdk/guides/in-field-mode) and [Error handling](/dictation-sdk/guides/error-handling) cover related layout issues. **React:** Some examples omit **`rootElement`**; the [React integration](/dictation-sdk/react-integration/react) guide explains when the minimal pattern skips it and when to pass it (including refs in real apps). [Configuration examples](/dictation-sdk/guides/examples/configuration-examples) includes sample wiring. Work through checks in this order: 1. **Runtime:** Browser-only use, correct timing (call after the DOM and container exist and have size). 2. **Layout:** **`rootElement`** (when used), height, and CSS. 3. **Auth and CSP:** Valid partner credentials and any CSP rules that affect iframes. 4. **Configuration and callbacks:** **AuthConfig**, **ShowOptions**, and a working **`onSubmit`**. That order is documented on [Error handling](/dictation-sdk/guides/error-handling). Use [Configuration](/dictation-sdk/guides/configuration) for every option field. # Dictation SDK Architecture Source: https://developer.suki.ai/dictation-sdk/guides/architecture Learn how your application, the Dictation SDK, sign-in, and Suki-hosted dictation fit together

Quick summary

Learn about the architecture of the Suki Dictation SDK and how your application, the Dictation SDK, sign-in, and Suki-hosted dictation fit together.

Last updated: June 2026

This guide explains the responsibilities for embedding dictation in your application. You maintain control of your user interface and determine when you turn dictation on or off. The Suki Dictation SDK hosts the microphone experience and transcription to ensure a consistent look and behavior across every integration. ## Architecture of the Suki Dictation SDK There are four main components in the Suki Dictation SDK: * Your application * The Suki Auth Manager * The Dictation SDK * The Suki hosted dictation iframe The following diagram illustrates the architecture of the Suki Dictation SDK and how each component fits together: Diagram: your web application contains application code, Dictation SDK, and layout with callbacks; Suki provides sign-in and hosted dictation; arrows show authenticate and tokens, hosted dictation session, and transcript back to your app.

Diagram: your web application contains application code, Dictation SDK, and layout with callbacks; Suki provides sign-in and hosted dictation; arrows show authenticate and tokens, hosted dictation session, and transcript back to your app.

Your app never has to build the dictation screen itself. The SDK opens that experience in the place you choose and passes results back to your code. ### What each layer does | Layer | What it does | | :------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Your application** | You decide when dictation should appear, where it mounts on the page, and what to do with text when the user is done (and optional live updates if you use them). | | **Dictation SDK** | The client you install talks to Suki, shows or hides the hosted dictation experience, and wires your callbacks so you receive transcripts. | | **Sign-in** | You configure this once with your partner details. It checks your setup, signs in with Suki, refreshes access when needed, and gives the hosted experience what it needs to run securely. | | **Hosted dictation** | The surface users speak into lives on Suki's side. It stays separate from your page's styles and layout so the experience stays consistent.

The iframe is isolated from host CSS and DOM to ensure consistent rendering across integrations. | If you need step-by-step setup, start with [Authentication](./authentication), then the [Quickstart](../quickstart). ## Lifecycle of a dictation session Diagram: four steps from configure SukiAuthManager, create DictationClient, open dictation, to close dictation.

Diagram: four steps from configure SukiAuthManager, create DictationClient, open dictation, to close dictation.

Create and configure [SukiAuthManager](/dictation-sdk/guides/authentication#use-sukiauthmanager-for-authentication) with your partner credentials. Sign-in may run when you initialize, depending on your settings. Create [DictationClient](/dictation-sdk/javaScript-integration/javaScript), or use the React provider and component, tied to that auth. When the user should dictate, **open** dictation (in-field or scratchpad). A session is active while they work. When they finish or you no longer need dictation, **close** it. In React, unmounting the dictation UI usually closes the session for you. For full implementation details for these APIs, refer to [JavaScript integration](../javaScript-integration/javaScript) for JavaScript, and [React integration](../react-integration/react) for React. ## Next steps Refer to the [Callbacks guide](/dictation-sdk/guides/callbacks) for more details on how to use the callbacks. # Dictation SDK Authentication Source: https://developer.suki.ai/dictation-sdk/guides/authentication Sign in to Suki before dictation opens: use SukiAuthManager with the partner ID and token Suki gives you The Dictation SDK uses a helper called **`SukiAuthManager`** from the **`@suki-sdk/core`** package. You give it the **partner ID** and **partner token** Suki assigned to your app. You create this helper **once**, then hand it to **`DictationClient`** in JavaScript or to **`DictationProvider`** in React. After sign-in works, Suki can show the dictation experience (the screen users talk to) inside your page. The helper also renews access when it expires. If the ID or token is wrong, or sign-in never finishes, that dictation screen will not appear. ## Prerequisites Before you set up **`SukiAuthManager`**, you must have: * **Partner ID** (the **`partnerId`** value): Suki gives you this when you complete [Partner onboarding](/documentation/partner-onboarding). * **Partner token** (the **`partnerToken`** value): The access value your program uses for this SDK. Your Suki contact explains how you get it and what it looks like. ## Use SukiAuthManager for authentication Create the helper when your app already knows **`partnerId`** and **`partnerToken`** by running the following code: ```javascript JavaScript expandable theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}} import { SukiAuthManager } from "@suki-sdk/core"; const authManager = new SukiAuthManager({ partnerId: "YOUR_PARTNER_ID", // required partnerToken: "YOUR_PARTNER_TOKEN", // required environment: "staging", // optional: "staging" or "production" (default "production") loginOnInitialize: true, // optional (default false) autoRegister: false, // optional (default false); when true, provider fields below are often required providerId: "YOUR_PROVIDER_ID", // optional; provider identifier in your system providerName: "YOUR_PROVIDER_NAME", // optional; full name, often required if autoRegister is true providerOrgId: "YOUR_PROVIDER_ORG_ID", // optional; org in your system, often required if autoRegister is true providerSpecialty: "FAMILY_MEDICINE", // optional; often required if autoRegister is true }); ``` For values you can pass as **`providerSpecialty`**, see [Specialties](/documentation/specialties). ## What SukiAuthManager does * **Checks** your settings before dictation tries to open. * **Signs in** to Suki's platform with your partner details. * **Renews access** when the SDK needs a fresh session. * **Lets** Suki's hosted dictation UI run with the right permissions. A bad **`partnerId`** or **`partnerToken`** stops dictation from loading. Users will not see the dictation UI until sign-in succeeds. Refer to [AuthConfig](/dictation-sdk/guides/configuration#authconfig) section in [Configuration](/dictation-sdk/guides/configuration) guide for more details on the available options and how to use them. If **`autoRegister`** is on, you may need extra **provider metadata**. Check your package README or ask your Suki contact. ## Sign in later instead of on create You can create **`SukiAuthManager`** first and call **`login()`** when your app is ready, instead of **`loginOnInitialize: true`**. Use whatever pattern your installed SDK version supports. ## Next steps Refer to [Quickstart](/dictation-sdk/quickstart) guide to get started with the Dictation SDK. # Callbacks Source: https://developer.suki.ai/dictation-sdk/guides/callbacks Learn about Callback contract payload shape, and JavaScript vs React usage for onSubmit, onCancel, and onDraft in the Dictation SDK

Quick summary

The Suki Dictation SDK supports three callbacks: `onSubmit`, `onCancel`, and `onDraft`. These callbacks are called when the user commits, cancels, or drafts the dictation respectively. You can use these callbacks to handle the dictation result, cancel the session, or receive intermediate updates while the user is dictating.

Last updated: June 2026

**Callbacks** allow your application to run your own code when the user commits, cancels, or moves on without committing during dictation. You supply functions; the Suki Dictation SDK calls them when those events occur. You do **not** poll on a timer or in a loop for new text. **Registering callbacks** When you start a session, register them in **JavaScript** as properties on the object you pass to `DictationClient.show()`, or in **React** as props on ``. **Callback execution** It calls **`onSubmit`** after the user commits, and **`onCancel`** if they leave without committing. If you supply **`onDraft`**, the SDK may call it when the user does **not** submit and switches to another field (or otherwise moves on without committing). **`onDraft`** is **not** invoked on every live transcript change while dictation stays on one field. The SDK does **not** persist draft text to your systems; only your **`onDraft`** handler decides whether to store or send it to your partner backend. **Payload** Every callback receives the same argument: one object, `{ fieldId, text }`. The `fieldId` value is whatever you passed into `show()` or ``. A common pattern is to set it to the **same value as the target control's `id`**, so `onSubmit` can use `document.getElementById(fieldId)` and write `text` into that element. ## Supported callbacks Dictation SDK supports the following callbacks: Runs when the user commits the dictation result. **Optional**: Runs when the user discards the session without committing. **Optional**. May run when the user leaves dictation **without** submitting and switches context (for example, to another field). Use it if you want to capture unstaged transcript text; the SDK does not save or forward it unless you do. **Mode** controls how dictation is shown. Set it to **`in-field`** when the UI is tied to a container on your page, or **`scratchpad`** for a standalone surface. Refer to [In-field mode](/dictation-sdk/guides/in-field-mode) and [Scratchpad mode](/dictation-sdk/guides/scratchpad-mode) guides for behavior and layout. For every other option you pass to `DictationClient.show()` or to `` as props, including **`rootElement`**, **`initialText`**, and these callbacks, use the [Configuration](/dictation-sdk/guides/configuration) reference. ## Callback contract payload shape All callbacks receive a **single** argument: an object with these fields: This is the string you invent to name this dictation session. The SDK includes it in every callback so you know which field the `text` is for. Using the same text as your input’s `id` (for example `clinical-notes`) is a simple way to tie them together. The transcript string for this callback (committed result, state at cancel, or interim draft, depending on which handler ran). **Example:** ```javascript JavaScript theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}} // After the user commits, your onSubmit might receive: { fieldId: "clinical-notes", text: "The user said hello.", } ``` For structured notes, use **stable**, **unique** ids per section, for example **`soap.subjective`**, **`soap.objective`**, **`soap.assessment`**, **`soap.plan`**, or **`scratchpad`** for a floating session. See [Field IDs](/dictation-sdk/guides/configuration#field-ids-in-practice). If **`onSubmit`** is missing, dictation often **closes immediately** after the user acts. Always implement `onSubmit`. ## Code examples Use callbacks as properties on the object you pass to **`await dictationClient.show({ ... })`**. They sit alongside `mode`, `fieldId`, `rootElement`, `initialText`, and other options from [Configuration](/dictation-sdk/guides/configuration). The iframe **resizes to the container** you pass as `rootElement` when you use `in-field` mode. ```javascript JavaScript theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}} import { SukiAuthManager } from "@suki-sdk/core"; import { DictationClient } from "@suki-sdk/dictation"; const authManager = new SukiAuthManager({ partnerId: "YOUR_PARTNER_ID", // Required partnerToken: "YOUR_PARTNER_TOKEN", // Required environment: "staging", // Optional loginOnInitialize: true, autoRegister: false, // Optional - default is false providerId: "YOUR_PROVIDER_ID", // Optional - required if autoRegister is true providerName: "YOUR_PROVIDER_NAME", // Optional - required if autoRegister is true providerOrgId: "YOUR_PROVIDER_ORG_ID", // Optional - required if autoRegister is true providerSpecialty: "YOUR_PROVIDER_SPECIALTY", // Optional - required if autoRegister is true }); const dictationClient = new DictationClient({ authManager }); // Example markup for in-field: //

// await dictationClient.show({ mode: "in-field", fieldId: "clinical-notes", // same string as id="clinical-notes" on your textarea rootElement: document.getElementById("clinical-notes-dictation-root"), initialText: document.getElementById("clinical-notes")?.value ?? "", onSubmit: ({ fieldId, text }) => { const el = document.getElementById(fieldId); if (el) el.value = text; }, onCancel: ({ fieldId, text }) => { // Optional: user cancelled without committing }, onDraft: ({ fieldId, text }) => { // Optional: e.g. user switched fields without submit; persist draft in your app if needed }, }); ``` Calling **`show()`** again **replaces** the active session; you do not need to call **`hide()`** between fields for that pattern. Wrap `show()` in `try` / `catch` if you want to log configuration or auth failures. Refer to the [Error handling](/dictation-sdk/guides/error-handling) guide for more details. For more on imperative `show()` and one client per page scope, refer to the [JavaScript integration](/dictation-sdk/javaScript-integration/javaScript) guide for more details. Pass the same three handlers as **props** on **``**. Build **`DictationClient`** once (with `SukiAuthManager`), wrap your tree with **``**, then render `Dictation` where dictation should be active. When `Dictation` **unmounts**, the SDK calls **`hide()`** for you. ```jsx React theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}} import { useMemo, useState } from "react"; import { SukiAuthManager } from "@suki-sdk/core"; import { DictationClient } from "@suki-sdk/dictation"; import { DictationProvider, Dictation } from "@suki-sdk/dictation-react"; function NotesApp() { const client = useMemo(() => { const authManager = new SukiAuthManager({ partnerId: "YOUR_PARTNER_ID", // Required partnerToken: "YOUR_PARTNER_TOKEN", // Required environment: "staging", // Optional loginOnInitialize: true, autoRegister: false, // Optional - default is false providerId: "YOUR_PROVIDER_ID", // Optional - required if autoRegister is true providerName: "YOUR_PROVIDER_NAME", // Optional - required if autoRegister is true providerOrgId: "YOUR_PROVIDER_ORG_ID", // Optional - required if autoRegister is true providerSpecialty: "YOUR_PROVIDER_SPECIALTY", // Optional - required if autoRegister is true }); return new DictationClient({ authManager }); }, []); const [notes, setNotes] = useState(""); // Drive from your UI: e.g. setActiveField("clinical-notes") when this field owns dictation. const [activeField, setActiveField] = useState(null); const handleSubmit = ({ fieldId, text }) => { // fieldId matches id="clinical-notes" below if you use that pattern setNotes(text); }; const handleCancel = ({ fieldId, text }) => { // Optional }; const handleDraft = ({ fieldId, text }) => { // Optional: e.g. save unstaged text when user leaves without submit }; return (

setNotes(e.target.value)}
        />
        {activeField === "clinical-notes" && (
          <Dictation
            fieldId="clinical-notes"
            mode="in-field"
            initialText={notes}
            onSubmit={handleSubmit}
            onCancel={handleCancel}
            onDraft={handleDraft}
          />
        )}
      </DictationProvider>
    );
  }
  ```

<Note>
    If you already create `client` higher in the tree, pass it into `DictationProvider` the same way. Use state such as **`activeField`** so only **one** field owns the session.

Refer to [React integration](/dictation-sdk/react-integration/react) guide for more details.
  </Note>
</View>

## Next steps

<Icon icon="file-lines" /> Refer to [Dictation modes](/dictation-sdk/guides/in-field-mode) and [Scratchpad mode](/dictation-sdk/guides/scratchpad-mode) guides to learn more about the different modes and how to use them.

# Configuration
Source: https://developer.suki.ai/dictation-sdk/guides/configuration

Learn how to configure the Suki Dictation SDK by configuring AuthConfig and ShowOptions

<span>Quick summary</span>
  </div>

<div>
    Configuration has two parts. First, `AuthConfig`: the object you pass to `new SukiAuthManager({ ... })` from `@suki-sdk/core`. That step covers sign-in, tokens, and optional provider registration before dictation can run.

<br />

Second, `ShowOptions`: what you pass to `DictationClient.show()` or as props on `Dictation` in React. That step sets mode and field, anchors the iframe in your layout, seeds text, and registers callbacks for each dictation session.
  </div>

<span>Last updated:</span>
    <span>May 2026</span>
  </div>
</div>

Dictation configuration has two steps: authenticate with **Suki for Partners**, then define how each dictation session is shown in your app.

<Steps>
  <Step title="Authenticate with the Suki for Partners">
    Build an **`AuthConfig`** object and pass it to **`new SukiAuthManager({ ... })`** from **`@suki-sdk/core`**. The manager handles your connection to the platform. Configure:

* **Partner ID and partner token:** Credentials Suki issues for your integration.
    * **Provider:** Optional fields that identify the clinician (for example **`providerId`**, **`providerName`**).
    * **Environment:** Target deployment (**`"staging"`** or **`"production"`**).
    * **Login behavior:** Whether the manager signs in when it is created (**`loginOnInitialize`**) or you call **`login()`** later.

**`SukiAuthManager`** signs in and refreshes tokens from these settings. Authentication must succeed before the hosted dictation iframe can open.
  </Step>

<Step title="Define session options">
    Pass a **`ShowOptions`** object whenever you start a session. In JavaScript, pass it to **`DictationClient.show()`**. In React, pass the same fields as props on **`Dictation`**.

Typical **`ShowOptions`** fields include:

* **Mode:** How the dictation UI is presented (for example in-field vs scratchpad).
    * **Field:** Stable field identifiers the SDK uses for callbacks.
    * **Mounting:** Where the iframe attaches in your DOM (**`rootElement`**).
    * **Seed text:** Optional starting text for the session.
    * **Callbacks:** Handlers for submit, cancel, and draft events.
  </Step>
</Steps>

<Tip>
  Modes control where the iframe lives. Read [In-field mode](/dictation-sdk/guides/in-field-mode) and [Scratchpad mode](/dictation-sdk/guides/scratchpad-mode) for UX and layout. For when each callback runs, see [Callbacks](/dictation-sdk/guides/callbacks).
</Tip>

## AuthConfig

**`AuthConfig`** is the object you pass to **`new SukiAuthManager({ ... })`**. It is used to configure the Suki Auth Manager.

**`SukiAuthManager`** runs first in the lifecycle: it validates this configuration, signs in to the **Suki platform** with your partner credentials, and refreshes tokens so the hosted dictation iframe can open. Until auth succeeds, dictation does not start.

### AuthConfig properties

<Expandable title="AuthConfig fields">
  <ResponseField name="partnerId" type="string">
    Partner identifier from Suki. Without a valid value, the iframe cannot initialize.
  </ResponseField>

<ResponseField name="partnerToken" type="string">
    Partner auth token from Suki. Invalid credentials block the hosted dictation UI.
  </ResponseField>

<ResponseField name="environment" type="string">
    **Optional**. Use **`"staging"`** or **`"production"`** so the SDK targets the right environment.
  </ResponseField>

<ResponseField name="autoRegister" type="boolean">
    **Optional**. When **`true`**, enables provider auto-registration. Provider metadata may be required; confirm with your package README or Suki contact.
  </ResponseField>

<ResponseField name="loginOnInitialize" type="boolean">
    **Optional**. When **`true`**, the SDK logs in during **`SukiAuthManager`** construction. You can instead construct the manager and call **`login()`** later when your app is ready.
  </ResponseField>

<ResponseField name="providerId" type="string">
    **Optional**. Identifier for the provider in your system.
  </ResponseField>

<ResponseField name="providerName" type="string">
    **Optional**. Full provider display name (for example, first, middle, and last name separated by spaces). It is **required** when **`autoRegister`** is **`true`**.
  </ResponseField>

<ResponseField name="providerOrgId" type="string">
    **Optional**. Organization identifier for the provider in your system. It is **required** when **`autoRegister`** is **`true`**.
  </ResponseField>

<ResponseField name="providerSpecialty" type="string">
    **Optional**. Clinical specialty (for example, **`FAMILY_MEDICINE`**). Refer to [Specialties](/documentation/specialties) for values your integration may use.
  </ResponseField>
</Expandable>

<Note>
  If **`autoRegister`** is enabled, **provider metadata** may be required in addition to the fields above.
</Note>

## ShowOptions

**`ShowOptions`** is what you pass to **`await dictationClient.show({ ... })`**. It is used to configure the Suki Dictation Client using the JavaScript package.

In React, **`Dictation`** accepts the same fields as props wherever the shipped types expose them (**`mode`**, **`fieldId`**, **`rootElement`**, **`initialText`**, **`onSubmit`**, **`onCancel`**, **`onDraft`**, and so on). Think of it as one contract: **imperative** object vs **declarative** props.

### ShowOptions properties

<Expandable title="ShowOptions fields">
  <ResponseField name="mode" type="string">
    **`"in-field"`** overlays dictation on a container you own (next to or over a field). **`"scratchpad"`** uses a standalone floating surface. See [In-field mode](/dictation-sdk/guides/in-field-mode) and [Scratchpad mode](/dictation-sdk/guides/scratchpad-mode).
  </ResponseField>

<ResponseField name="fieldId" type="string">
    A **stable**, **unique** string that names this dictation instance. The SDK echoes it on every callback as `{ fieldId, text }`. See [Field IDs in practice](#field-ids-in-practice) below for naming patterns.
  </ResponseField>

<ResponseField name="rootElement" type="HTMLElement">
    **Recommended**. DOM node that hosts the dictation iframe. The iframe sizes to this container. A collapsed or zero-height parent produces a blank area. For layout patterns, refer to [Wrapper layout](#wrapper-layout).
  </ResponseField>

<ResponseField name="initialText" type="string">
    **Optional**. Seed text shown when the session opens (for example the current value of your textarea).
  </ResponseField>

<ResponseField name="onSubmit" type="function">
    Runs when the user **commits** the transcript. You receive `{ fieldId, text }`. Always implement this callback; without it, dictation often closes immediately after the user acts. Details: [Callbacks](/dictation-sdk/guides/callbacks).
  </ResponseField>

<ResponseField name="onCancel" type="function">
    **Optional**. Runs when the user leaves without committing. Same payload shape as other callbacks.
  </ResponseField>

<ResponseField name="onDraft" type="function">
    **Optional**. May run when the user does not submit and switches context (for example, another field). Not fired on each live transcript edit. Same payload shape. See [Callbacks](/dictation-sdk/guides/callbacks).
  </ResponseField>
</Expandable>

<Warning>
  If **`onSubmit`** is missing, dictation often **closes immediately** after the user acts. Treat it as required in real integrations.
</Warning>

## Field IDs in practice

**`fieldId`** is a **stable string you choose** to identify which note field or dictation target this session is for. The SDK includes it on every callback together with **`text`**, so you can match each transcript to the correct field in your app.

You can use any stable string. A common shortcut is to use the **same value** as the target control's HTML **`id`**: then in **`onSubmit`** you can run **`document.getElementById(fieldId)`** and assign **`text`** to that element. If you prefer another naming scheme, **`fieldId`** does not have to match a DOM **`id`**; just route **`text`** in your handler using the **`fieldId`** you chose.

For structured notes, common examples are **`soap.subjective`**, **`soap.objective`**, **`soap.assessment`**, and **`soap.plan`**. For a scratchpad or floating session, a dedicated id such as **`scratchpad`** (or a namespaced value if you run more than one) keeps callbacks unambiguous.

<Note>
  * Each **active** dictation instance should have its own stable id. If you call **`show()`** again, you **replace** the active session; you do not need **`hide()`** between fields for that pattern.

* The object every callback receives is documented in [Callback contract payload shape](/dictation-sdk/guides/callbacks#callback-contract-payload-shape) in the Callbacks guide.
</Note>

## Callback argument shape

For the callback argument payload shape, refer to [Callback argument shape](/dictation-sdk/guides/callbacks#callback-contract-payload-shape).

## Wrapper layout

A **wrapper layout** is the layout where **`rootElement`** is a **dedicated container** (usually a **`div`**) with **stable width and height**, not the raw **`<textarea>`** or **`<input>`** you dictate into. Note fields grow and reflow with content; the iframe needs a host whose dimensions **you** control.

Set **`rootElement`** to that container. The SDK inserts the dictation UI there and sizes it to that element’s width and height.

When that element is **too small**, has **no height**, or **resizes often** (for example when a flex or grid parent collapses), the UI may show a **blank** area, look **clipped**, or **jump** when the page reflows.

To create a wrapper layout, follow these best practices:

* Add that **`div`** where the iframe should live, often **beside or over** the note field.
* Give it a **real height** (**`height`**, **`min-height`**, or a parent that already has height) so the iframe has room to draw.
* Use **`position: relative`** on the wrapper when you need the overlay to align with the rest of your layout.

### Recommended wrapper CSS

```css CSS theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
/* Class on the element you pass as rootElement, or on an outer host that sizes the region */
.wrapper {
  position: relative;
  height: 100%;
}
```

If problems persist, check parent **`overflow`**, flex or grid **shrink rules**, container **`position`**, and **CSP** rules that block the iframe.

## Best practices

<Accordion title="For callbacks">
  For callbacks, you should always implement the `onSubmit` callback. If you do not, dictation will often close immediately after the user acts.

```javascript theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
  onSubmit: ({ fieldId, text }) => {
    // Your code to handle the submitted text
  }
  ```
</Accordion>

<Accordion title="For layout">
  For layout, you should use a dedicated wrapper container instead of attaching directly to inputs.

```html theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
  <div class="wrapper">
    <textarea id="clinical-notes">

``` ```css theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}} .wrapper { position: relative; height: 100%; } ``` For mode usage, you should use the `in-field` mode when dictation is tied to a specific text field or editor, and the `scratchpad` mode when dictation is not tied to a specific text field or editor. ```javascript theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}} mode: "in-field", ``` ```javascript theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}} mode: "scratchpad", ``` ## Next steps Refer to the [Error handling](/dictation-sdk/guides/error-handling) guide for more details on common issues and how to troubleshoot them. # Dictation SDK Error Handling Source: https://developer.suki.ai/dictation-sdk/guides/error-handling Learn to fix common Dictation SDK issues: auth, CSP, layout, missing callbacks, and client-only runtime requirements The Dictation SDK does not return one consistent error code for every problem. Instead, several systems have to work together: the **Suki platform** handles **authentication**, the hosted UI runs inside an **iframe**, and your app passes **`rootElement`** and **callbacks**. When one piece is wrong, you often only see a vague symptom, such as **no UI**, **dictation closing immediately**, or **broken layout**. Work through this page in this order: **runtime** (browser and timing), **layout** (**`rootElement`** and CSS), **auth and CSP**, then **configuration and callbacks**. That order usually finds the cause fastest. For every field on **`AuthConfig`** and **`ShowOptions`**, use [Configuration](/dictation-sdk/guides/configuration). The **wrapper** pattern for **`rootElement`** (stable height, **`position: relative`**) is documented on [Configuration guide wrapper layout](/dictation-sdk/guides/configuration#wrapper-layout). Refer to that page if you are not sure how to structure your DOM. ## Runtime requirements The Dictation SDK is built for **in-browser** embedding. It is **not** a Node-only or server-rendered iframe product. Browser environments where you can create an `HTMLIFrameElement`, use `postMessage`, and measure a DOM container Using Node.js as the environment that hosts `DictationClient` or the dictation iframe Relying on **SSR** alone to render dictation; initialize and call `show()` on the client after the document (and your `rootElement`) exist * A real `HTMLIFrameElement` (the SDK creates and manages it inside your container) * `postMessage` between your page and the hosted UI * Layout information so the iframe can size to `rootElement` Dictation runs in the **browser** only. The iframe is not created during **SSR** or on the server. Call **`show()`** only after **`rootElement`** points at an element that **already exists** in the DOM and has been laid out (so it has a real size). If you call too early, **`rootElement`** may be **`null`** or zero height. * [React integration](/dictation-sdk/react-integration/react) for **`DictationProvider`** and **`Dictation`** * [Configuration examples](/dictation-sdk/guides/examples/configuration-examples) for sample **`rootElement`** wiring ## Layout and root element related issues The iframe **fills the layout box** of the element you pass as **`rootElement`**. Common mistakes are as follows: * A **zero-height** parent * A flex or grid child that **shrinks to zero** * **`overflow: hidden`** on a parent that clips the overlay ### Recommended approach * Use a dedicated **wrapper** around the dictation region, not the raw **`

`** as **`rootElement`**, unless you are sure that node has a stable box.
* Give the wrapper a **defined height** or **`min-height`**, and usually **`position: relative`**.

<Expandable title="Recommended wrapper CSS">
  ```css CSS theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
  .wrapper {
    position: relative;
    height: 100%;
  }
  ```
</Expandable>

For a longer explanation, refer to [Wrapper layout section](/dictation-sdk/guides/configuration#wrapper-layout) on the Configuration guide.

<Tip>
  If **`rootElement`** is **`null`** (wrong id, node not mounted yet, or **`show()`** before layout), **`show()`** can fail or show a blank area.
  Resolve the DOM first, then retry. Use the [try / catch section](/dictation-sdk/guides/error-handling#wrap-show-in-try-/-catch) below to log or surface that error.
</Tip>

## Authentication and CSP related issues

<Expandable title="Error sources">
  <ResponseField name="SukiAuthManager" type="Auth">
    **Invalid** **`partnerId`**, **`partnerToken`**, or wrong **`environment`** can block sign-in. The iframe will not initialize until auth succeeds. Start with [Authentication](/dictation-sdk/guides/authentication) and confirm credentials with your Suki contact.
  </ResponseField>

<ResponseField name="Iframe / CSP" type="Iframe">
    The hosted dictation UI loads in an iframe. If your **CSP** blocks that frame source, or the host URL is not allowlisted for your program, the UI will not appear or will fail silently in the network panel. Check frame ancestors, **`frame-src`** / **`child-src`**, and any partner-specific allowlist docs you were given.
  </ResponseField>
</Expandable>

## Configuration related issues

<Expandable title="Error sources">
  <ResponseField name="Configuration" type="Config">
    A missing **`onSubmit`** callback often makes dictation **close immediately** after the user acts. Other required fields (**`mode`**, **`fieldId`**) must also be set; refer to [Configuration](/dictation-sdk/guides/configuration) guide for more details.
  </ResponseField>
</Expandable>

### Wrap show() in try / catch

`DictationClient.show()` can **throw** or reject when configuration or auth fails before the session is usable. Wrapping the call helps you **log** and **surface** errors in your own UI.

```javascript JavaScript expandable theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
try {
  await client.show({
    mode: "in-field",
    fieldId: "notes",
    rootElement: document.getElementById("dictation-root"),
    onSubmit: ({ text }) => applyText(text),
  });
} catch (err) {
  console.error(err);
}
```

## Troubleshooting

Below are some other common issues and how to troubleshoot them.

<Accordion title="Dictation UI not visible">
  Check, in roughly this order:

* **Container height** and **`position`** on **`rootElement`** and parents ([Wrapper layout](/dictation-sdk/guides/configuration#wrapper-layout))
  * **Browser devtools** for blocked iframe requests or CSP violations
  * That **`rootElement`** is **not** **`null`** and matches the node you intend
  * **Authentication**: failed login or bad tokens (refer to [Authentication](/dictation-sdk/guides/authentication) guide)
</Accordion>

<Accordion title="Dictation closes immediately">
  This usually means **`onSubmit`** is **missing** or not wired correctly. The hosted UI expects a handler when the user commits. Refer to [Callbacks](/dictation-sdk/guides/callbacks) and [Configuration](/dictation-sdk/guides/configuration) guides for more details.
</Accordion>

<Accordion title="Multiple overlays or duplicate sessions">
  Create **one** **`DictationClient`** (with one **`SukiAuthManager`**) per **page scope**, and drive which field is active with your own state (for example a single **`activeFieldId`**). Multiple clients can each try to mount dictation. Refer to [JavaScript integration](/dictation-sdk/javaScript-integration/javaScript) and [React integration](/dictation-sdk/react-integration/react) guides for more details.
</Accordion>

# Configuration examples
Source: https://developer.suki.ai/dictation-sdk/guides/examples/configuration-examples

JavaScript and React code samples for SukiAuthManager AuthConfig and DictationClient ShowOptions

The code snippets below show JavaScript and React integrations to configure the SukiAuthManager and DictationClient. Replace placeholder values with your partner credentials and DOM nodes.

<Tabs>
  <Tab title="JavaScript">
    ```javascript JavaScript theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
    import { SukiAuthManager } from "@suki-sdk/core";
    import { DictationClient } from "@suki-sdk/dictation";

const authManager = new SukiAuthManager({
      partnerId: "YOUR_PARTNER_ID", // Required
      partnerToken: "YOUR_PARTNER_TOKEN", // Required
      environment: "staging", // Optional
      loginOnInitialize: true, // Optional
      providerName: "John doe", // Optional
      providerOrgId: "1234", // Optional
      providerId: "1234567890", // Optional
      providerSpecialty: "FAMILY_MEDICINE", // Optional
    });

const dictationClient = new DictationClient({ authManager });

await dictationClient.show({
      mode: "in-field",
      fieldId: "clinical-notes",
      rootElement: document.getElementById("clinical-notes-field-root-element-id"),
      initialText: "",
      onSubmit: ({ fieldId, text }) => {
        const el = document.getElementById(fieldId);
        if (el) el.value = text;
      },
      onCancel: ({ fieldId }) => {
        console.log("Cancelled", fieldId);
      },
      onDraft: ({ fieldId, text }) => {
        // Optional: e.g. user left without submit; persist draft in your app if needed
        console.log("Draft", fieldId, text);
      },
    });
    ```
  </Tab>

<Tab title="React">
    ```jsx React theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
    import { SukiAuthManager } from "@suki-sdk/core";
    import { DictationClient } from "@suki-sdk/dictation";
    import { DictationProvider, Dictation } from "@suki-sdk/dictation-react";

const client = new DictationClient({ authManager });

export function NotesWithDictation() {
      return (
        <DictationProvider client={client}>
          <Dictation
            mode="in-field"
            fieldId="clinical-notes"
            rootElement={document.getElementById("dictation-root")}
            initialText=""
            onSubmit={({ fieldId, text }) => {
              console.log(fieldId, text);
            }}
            onCancel={({ fieldId }) => {
              console.log("Cancelled", fieldId);
            }}
            onDraft={({ fieldId, text }) => {
              // Optional: e.g. user left without submit; persist draft in your app if needed
              console.log("Draft", fieldId, text);
            }}
          />
        </DictationProvider>
      );
    }
    ```
  </Tab>
</Tabs>

<Note>
  In a real React app, obtain **`rootElement`** with **`useRef`** and a **`useEffect`** (or render the wrapper in the same tree) so you do not call **`document.getElementById`** during SSR. See [React integration](/dictation-sdk/react-integration/react) for patterns that match your app.
</Note>

## Next steps

<Icon icon="file-lines" /> [Configuration](/dictation-sdk/guides/configuration) for the full **`AuthConfig`** and **`ShowOptions`** tables, [field IDs](/dictation-sdk/guides/configuration#field-ids-in-practice), and [Wrapper layout](/dictation-sdk/guides/configuration#wrapper-layout)
<Icon icon="file-lines" /> [Callbacks](/dictation-sdk/guides/callbacks) for callback behavior and edge cases

# In-field Mode
Source: https://developer.suki.ai/dictation-sdk/guides/in-field-mode

Learn how to embed Suki Dictation on a text field with in-field mode: your UI to start dictation, rootElement, fieldId, callbacks, and Suki's hosted overlay

<span>Quick summary</span>
  </div>

<div>
    In-field mode is how you embed the Suki Dictation SDK on a text field in an existing web application, so dictation stays tied to that one control instead of floating on its own. You decide how users start dictation in your app and receive the transcript text through callbacks.
  </div>

<span>Last updated:</span>
    <span>May 2026</span>
  </div>
</div>

**In-field mode** allows you to embed the Suki Dictation SDK directly into a text field within your application. This ensures dictation remains tied to a specific control rather than floating independently. You choose the entry point for starting dictation based on your application's user interface.

**Launching dictation**

The entry point is entirely part of your UI. You can use a button, an icon, a menu item, or a keyboard shortcut. To launch the session for a specific field, your code must call `show()` in **JavaScript** or mount the Dictation component in **React**.

**Managing the dictation interface**

Once the session is open, the Suki Dictation SDK provides the dictation surface. This includes the **microphone**, **Submit**, and **Cancel** controls. The interface appears as a hosted iframe inside the rootElement you provide.

Keep the following requirements in mind to ensure the interface displays correctly:

* **Container sizing**: The iframe sizes itself to the container you provide.

* **Dimensions**: You must provide a **specific height** and **width** for the interface to appear correctly.

* **Data handling**: You receive transcript text through defined callbacks.

* **Troubleshooting**: If the interface does not appear, check your layout and Content Security Policy (CSP) settings.

The diagram below is a simple **healthcare-style form** with **several text areas**. Only **one** field shows a **Dictate** control in the **top right** of that field; the rest are plain.

<Note>
  You can place the button or icon anywhere in your application that fits your design. These screens are only examples.
</Note>

## When to choose in-field mode

Use **in-field mode** when:

* You embed dictation for a **specific text field** (or editor) and you design the **entry point** yourself (for example a **Dictation** button, icon, or toolbar action that calls `show()` or mounts `<Dictation>`).
* You want Suki's dictation overlay on the **field's container** (`rootElement`), so mic, submit, and cancel sit with that target instead of a standalone floating panel.

<Note>
  For dictation that is **not** bound to a single input, use [Scratchpad mode](/dictation-sdk/guides/scratchpad-mode) instead.
</Note>

## How to configure in-field mode

For in-field dictation you configure **three** things: **`mode`**, **`rootElement`**, and **`fieldId`**. Together they tell the SDK **which layout to use**, **where to put the iframe**, and **how to label this session** in callbacks.

### Mode

Set `mode` to the string **`"in-field"`** so the SDK uses the overlay-on-container layout instead of scratchpad.

* **JavaScript:** include `mode: "in-field"` in the object you pass to `DictationClient.show()`.
* **React:** set `mode="in-field"` on `<Dictation>`.

```javascript Mode configuration theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
mode: "in-field",
```

### Root element

Set `rootElement` to know which element on your page should contain the dictation iframe. The SDK inserts the iframe **inside** that element. It is **not** the
answer to *“which input gets the text”*; you apply transcript text in **callbacks** (and often target your field by `fieldId` or your own state).

**Recommended pattern:**

Use a **parent `<div>`** that wraps the notes area, and pass **that div** as `rootElement`. Pass **`document.getElementById("…")`** (or a ref in React) for that wrapper, **not** for the `<textarea>` or `<input>` alone.

Example markup and how it maps to `rootElement`:

```html theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}

<div id="clinical-notes-dictation-root"></div>
<textarea id="clinical-notes">

``` The wrapper and textarea can be structured however your layout needs; the important part is that **`rootElement`** points at the **element that should host the iframe**, not at the textarea node. | Do this | So that | | :------------------------------------------------------------------------- | :---------------------------------------------------------------------------------------------------------- | | Give the host element a **visible height and width** | The iframe fills its parent. A parent with no height often produces a blank area where dictation should be. | | Set **`position: relative`** on the host when you use overlays or stacking | The dictation layer stays aligned with the field region in typical layouts. | Refer to [Configuration](/dictation-sdk/guides/configuration) for every `ShowOptions` field and matching React props. ### Field ID `fieldId` is a **string you invent** to name this dictation session. Every callback sends it back with `text`, so you know **which field** the result belongs to if you have several on the page. It does not have to match a DOM `id`, but using the same value as your input's `id` is a simple pattern. Each open dictation instance should use a **stable**, **unique** `fieldId`. Examples for SOAP-style sections: **`soap.subjective`**, **`soap.objective`**, **`soap.assessment`**, **`soap.plan`**. Refer to [Callback contract payload shape](/dictation-sdk/guides/callbacks#callback-contract-payload-shape) for more details. ## How to use in-field mode **You** build how users **start** dictation: a **Dictation** button, a link, an icon, or any control that calls `show()` or mounts ``. After they start, **Suki** draws the dictation UI inside the iframe: **microphone**, **submit**, **cancel**, and the rest. You do not rebuild those controls yourself. You receive text and events through **`onSubmit`**, **`onCancel`**, and optionally **`onDraft`**. ## Quick reference | Item | In-field behavior | | :--------------- | :------------------------------------------------------------------------ | | **Layout** | Dictation sits over the **input container** you target with `rootElement` | | **Mode** | `"in-field"` | | **Root element** | Recommended: element that wraps the field | ## Next steps Refer to [Scratchpad mode](/dictation-sdk/guides/scratchpad-mode) for floating dictation off a single field. # Scratchpad Mode Source: https://developer.suki.ai/dictation-sdk/guides/scratchpad-mode Learn about when to use scratchpad mode for the Suki Dictation SDK and how to configure it

Quick summary

Scratchpad mode opens dictation in a floating surface that is not tied to a single text field. You choose how users open it, and you still receive committed (and optional draft) text through callbacks.

Last updated: May 2026

**Scratchpad mode** allows you to run the Suki Dictation SDK in a standalone area of your web application. Dictation does not attach to one specific input the way [In-field mode](/dictation-sdk/guides/in-field-mode) does. **Launching dictation** The entry point is entirely part of your UI. You can use a toolbar action, header button, floating launcher, menu item, keyboard shortcut, or any pattern you prefer. To launch scratchpad dictation, your code must call `show()` with **mode: "scratchpad"** in **JavaScript** or mount the **Dictation** component in **React** with **mode: "scratchpad"**. **Managing the dictation interface** Once the session is open, the Suki Dictation SDK provides the dictation surface. This includes the **microphone**, **Close**, **copy-to-clipboard**, and related controls. The interface appears as a hosted iframe in the layout you configure. Keep the following requirements in mind to ensure the interface displays correctly: * **Layout**: You control where the scratchpad appears (for example, a floating panel anchored to a launcher). * **Mode**: You must pass **scratchpad** in `show()` or on `` so the SDK uses the floating surface. * **Data handling**: You receive transcript text through defined callbacks. The diagram below is a **clinical-style form** (for example, SOAP note sections) with a **floating Open dictation** launcher in the corner. After the user opens it, the **scratchpad** appears **above** that launcher as a tall panel on the right, with the transcript area and **Mic**, **Close**, and **Copy**. You can place the launcher anywhere in your application that fits your design. Your real layout might use a portal, column, or different spacing. These screens are only examples.

New SOAP Note interface with Subjective, Objective, and Assessment sections and a patient sidebar; floating Suki Dictate button in the bottom-right corner with an arrow and label reading Floating Scratchpad for dictation.

## When to choose scratchpad mode Use **scratchpad mode** when: * Dictation should live in its **own** area (side panel, overlay region, or similar), not overlaid on one field’s container. * Users need to **capture speech first** and then paste or apply text elsewhere, or you want **quick dictation** without binding the session to a single `textarea`. When dictation should stay tied to **one** text field and your **Dictate** control sits with that field, use [In-field mode](/dictation-sdk/guides/in-field-mode) instead. ## How to configure scratchpad mode For scratchpad dictation you set **`mode`**, **`fieldId`**, and usually consider **`rootElement`** (and other [`ShowOptions`](/dictation-sdk/guides/configuration)) so the SDK knows **which layout to use**, **where the iframe mounts**, and **how to label the session** in callbacks. ### Mode Set `mode` to the string **`"scratchpad"`** so the SDK uses the **floating standalone** dictation UI instead of in-field overlay. * **JavaScript:** include `mode: "scratchpad"` in the object you pass to `DictationClient.show()`. * **React:** set `mode="scratchpad"` on ``. ```javascript Mode configuration theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}} mode: "scratchpad", ``` ### Root element For scratchpad, **`rootElement`** is still the DOM node where the SDK **mounts** the dictation iframe. It is usually a **dedicated region** of your layout (panel, column, or modal body), **not** a wrapper around a single clinical line item. The hosted UI still **measures the same layout box** as in-field mode: **`rootElement`** should be an element with **real width and height** so the floating surface has room to render. If the host **collapses** (for example **zero height** in a flex or grid row, a hidden parent, or no **`min-height`**), you will usually see a **blank** or **clipped** area even though scratchpad is “floating.” When the scratchpad region **sits on top of** or **beside** other UI, set **`position: relative`** on that host (unless you already have another positioning context) so stacking and alignment stay predictable. For wrapper sizing patterns and CSS, refer to [Wrapper layout best practices](/dictation-sdk/guides/configuration#wrapper-layout) on [Configuration](/dictation-sdk/guides/configuration). ### Field ID **`fieldId`** is a **string you invent** to name this scratchpad session. Every callback sends it back with `text`, which helps if you run **multiple** scratchpads or mix scratchpad with in-field flows. It does not have to match a DOM `id`. Use a **stable**, **unique** id per scratchpad instance; a common choice is **`scratchpad`**, or a namespaced value such as **`scratchpad.draft`** if you run more than one. ## How to use scratchpad mode **You** build how users **open** scratchpad dictation. After they start, **Suki** draws the dictation UI in the iframe: **microphone**, **close**, **copy**, and the rest. You do not recreate those controls yourself. You receive text and events through **`onSubmit`**, **`onCancel`**, and optionally **`onDraft`**. ## Quick reference | Item | Scratchpad behavior | | :--------------- | :-------------------------------------------------------------------- | | **Layout** | **Floating** standalone dictation UI, not tied to one input container | | **Mode** | `"scratchpad"` | | **Root element** | Host region for the iframe | ## Next steps Refer to [In-field mode](/dictation-sdk/guides/in-field-mode) when dictation should attach to a specific field. Read [Callbacks](/dictation-sdk/guides/callbacks) for handlers and payload shape, and the [Configuration](/dictation-sdk/guides/configuration) reference for all options. # Dictation SDK Installation Source: https://developer.suki.ai/dictation-sdk/installation Install Suki Dictation SDK in your JavaScript or React application We have modularized the Suki Dictation SDK into **framework-specific packages** plus shared **`@suki-sdk/core`** for **`SukiAuthManager`**, so you install **`core`** in every setup and add either **`@suki-sdk/dictation`** or **`@suki-sdk/dictation-react`** depending on your environment. The Dictation SDK is built for browser applications and requires **`HTMLIFrameElement`** and **`postMessage`** (refer to [Prerequisites](/dictation-sdk/prerequisites) guide for more details). ## Prerequisites For the rest of this documentation, we will assume you have completed the [Partner onboarding](/documentation/partner-onboarding) process. Refer to the [Prerequisites](/dictation-sdk/prerequisites) guide for more information. ## Install the package ### For vanilla JavaScript Use **`@suki-sdk/dictation`** with **`@suki-sdk/core`** for plain JavaScript or frameworks other than React. To install the packages, run one of the following commands: ```shell pnpm theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}} pnpm add @suki-sdk/core @suki-sdk/dictation ``` ```shell npm theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}} npm install @suki-sdk/core @suki-sdk/dictation ``` ```shell yarn theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}} yarn add @suki-sdk/core @suki-sdk/dictation ``` ### For React For React applications, use **`@suki-sdk/dictation-react`** with **`@suki-sdk/core`**. It includes **`DictationProvider`** and **`Dictation`** so you can wire dictation declaratively. To install the packages, run one of the following commands: ```shell pnpm theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}} pnpm add @suki-sdk/core @suki-sdk/dictation-react @suki-sdk/dictation ``` ```shell npm theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}} npm install @suki-sdk/core @suki-sdk/dictation-react @suki-sdk/dictation ``` ```shell yarn theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}} yarn add @suki-sdk/core @suki-sdk/dictation-react @suki-sdk/dictation ``` ## Next steps Read the [Authentication](/dictation-sdk/guides/authentication) guide to learn how to authenticate yourself to use the Dictation SDK. # Dictation SDK Overview Source: https://developer.suki.ai/dictation-sdk/introduction Overview of the Suki Dictation SDK and how it works The Suki Dictation SDK is a JavaScript and React library for dictation in the browser. Use Dictation SDK to add speech-to-text capabilities to your web application. If you use our **Headed Web SDK** `v3.X.X+`, you can use audio dictation capabilities out of the box. Refer to the [Web SDK for audio dictation](/web-sdk/dictation-overview) guide for more details. You can implement the Suki Dictation SDK in two modes: **In-field** and **Scratchpad**. Use this mode for dictation over a target field. Commonly used for notes and forms. Use this mode for a floating dictation panel, not tied to one input. Commonly used for dictation in a separate area of the page. When the user starts the dictation session: 1. Recording begins automatically 2. Transcription appears inside the text field and the scratchpad UI 3. When the user finishes dictation and confirms, the SDK calls the handler functions you registered and passes the final transcript into your app so you can update fields, save data, or run your own logic The Dictation SDK is different from integrating directly with the [Dictation APIs](/api-reference/audio-transcription/create-session). The SDK manages authentication through `SukiAuthManager`, iframe lifecycle, and transcript callbacks for you. If you need a custom or server-side integration without the hosted iframe experience, use the APIs described in [Dictation basic usage](/documentation/dictation-basic-usage). ## Supported packages The Dictation SDK is available in the following packages: Use `@suki-sdk/dictation-react` for React web applications. Install the Dictation SDK for React:

Use `@suki-sdk/dictation` for vanilla JavaScript applications. Install the Dictation SDK for JavaScript:

Both require shared authentication through **`@suki-sdk/core`** (Refer to the [Dictation SDK Quickstart](/dictation-sdk/quickstart) for more information). ## When to use Dictation SDK Choose the Dictation SDK when: * You want **real-time speech-to-text** in the browser with Suki's hosted iframe experience * You need **in-field** overlays on inputs or a **scratchpad** workflow for dictation mechanics * You prefer **callback-driven** commit of the transcription result over owning REST and WebSocket dictation calls yourself ## Recommended integration pattern Follow the below pattern to integrate the Dictation SDK into your application: ```mermaid actions={false} theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}} %%{init: {'theme':'base', 'themeVariables': { 'primaryColor':'#FFE148','primaryTextColor':'#111827','lineColor':'#6B7280','fontSize':'14px','edgeLabelBackground':'#FFFFFF','tertiaryColor':'#F9FAFB','tertiaryTextColor':'#111827','tertiaryBorderColor':'#D1D5DB'}}}%% graph TB SM["SukiAuthManager
@suki-sdk/core
Once, after partner token is available"] DC["DictationClient
new DictationClient({ authManager })
One instance per page · reuse for every target"] DP["DictationProvider
@suki-sdk/dictation-react
React only · wrap your tree"] F1["In-field · field A
show() or Dictation when this field is active"] F2["In-field · field B
Same pattern · switch active field"] SP["Scratchpad
mode: scratchpad · still one client"] SM -->|auth| DC DC -.->|optional · pass same client| DP DC --> F1 DC --> F2 DC --> SP ``` ## How it works The following diagram illustrates the Dictation SDK architecture and workflow: ```mermaid actions={false} theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}} %%{init: {'theme':'base', 'themeVariables': { 'primaryColor':'#FFE148','primaryTextColor':'#111827','lineColor':'#6B7280','fontSize':'14px','edgeLabelBackground':'#FFFFFF','tertiaryColor':'#F9FAFB','tertiaryTextColor':'#111827','tertiaryBorderColor':'#D1D5DB'}}}%% graph TB subgraph client["Your web application"] direction TB A["Application code
React / JavaScript / Other frameworks"] B["Dictation SDK
@suki-sdk/dictation or dictation-react + core"] C["Your layout + callbacks
Container • onSubmit • optional onDraft"] A --> B B --> C end subgraph platform["Suki"] direction TB D["Authentication
SukiAuthManager"] E["Dictation iframe
Speech UI + transcription"] end B -->|Authenticate / tokens| D B -->|Hosted dictation session| E E -->|Transcript / draft to your app| C style client fill:#FFFADE,stroke:#D1D5DB,stroke-width:2px,color:#111827 style platform fill:#FFF394,stroke:#FFE148,stroke-width:2px,color:#111827 style A fill:#ffffff,stroke:#9CA3AF,stroke-width:2px,color:#111827 style B fill:#FFE148,stroke:#111827,stroke-width:3px,color:#111827 style C fill:#ffffff,stroke:#9CA3AF,stroke-width:2px,color:#111827 style D fill:#ffffff,stroke:#9CA3AF,stroke-width:2px,color:#111827 style E fill:#ffffff,stroke:#9CA3AF,stroke-width:2px,color:#111827 ``` ### Architecture workflow * **You** choose when dictation should open and where it should appear on the page (for example over one input, or as a separate floating area). * **Your code** starts dictation and listens for results from the SDK. When the user finishes, you receive the final text. * **Your UI** decides what to do with that text (fill a field, save a draft, discard, and so on). * **Sign-in:** Suki checks your configuration, signs in with the partner account details you provide, keeps access fresh, and hands the hosted dictation experience what it needs to run securely. * **Hosted dictation:** The microphone experience and transcription run in an embedded view that Suki hosts. That way the dictation screen looks and behaves the same in every app, and it does not inherit your site’s fonts, colors, or layout. 1. Set up sign-in once using the partner details Suki gives you. 2. Add the dictation SDK to your app and connect it to that sign-in. 3. When the user asks to dictate, open dictation in the place you picked (over a field or as a scratchpad-style area). 4. The user speaks and confirms. Your app receives the text so you can put it where it belongs in your workflow. 5. When dictation should stop, close it from your app so the session ends. Refer to the [Architecture guide](/dictation-sdk/guides/architecture) for more details. ## Next steps Get started by following these steps: Refer to the [Installation guide](/dictation-sdk/installation) to add the packages to your project Refer to the [Prerequisites](/dictation-sdk/prerequisites) guide to confirm browser, CSP, and layout requirements Refer to the [Quickstart](/dictation-sdk/quickstart) for JavaScript and React examples through your first `show()` call # Dictation SDK JavaScript Integration Source: https://developer.suki.ai/dictation-sdk/javaScript-integration/javaScript Learn how to integrate the Dictation SDK in a JavaScript application (browser-based) using the JavaScript package provided by Suki This guide walks you through the process of integrating the Dictation SDK in a JavaScript application (browser-based) using the JavaScript package provided by Suki. You will create **Auth Manager** and **Dictation Client**, then start dictation by calling **`await dictationClient.show({ ... })`** from your own code when the user is ready. Let's get started! ## Prerequisites Before you begin, you must have the following requirements met: * **Packages:** Install `@suki-sdk/dictation` and `@suki-sdk/core` packages. * **Partner credentials:** Obtain `partnerId` and `partnerToken` from Suki after [Partner onboarding](/documentation/partner-onboarding). * **Browser and layout:** Your app runs in a **browser**, with a real DOM and a dictation **container** that has height. Refer to [Prerequisites](/dictation-sdk/prerequisites) guide for more details. ## Install the packages Add both packages to the same project you load in the browser: ```shell pnpm theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}} pnpm add @suki-sdk/core @suki-sdk/dictation ``` ```shell npm theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}} npm install @suki-sdk/core @suki-sdk/dictation ``` ```shell yarn theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}} yarn add @suki-sdk/core @suki-sdk/dictation ``` After you install, pull the SDK into your files with **`import`**, the same way as in the examples below. Use whatever approach your project already uses for other npm libraries. ## Step 1: Add container and field HTML For this example we will assume you are using **`in-field`** mode as your preferred mode. In **`in-field`** mode you need **two** nodes in the page: a **`div`** (or similar) that you pass as **`rootElement`**, where the dictation controls show up, and a **textarea** (or input) that **`onSubmit`** will update when the user finishes. The dictation layer **matches the size of** **`rootElement`**, so that node should have a **height** you control. Refer to [Wrapper layout](/dictation-sdk/guides/configuration#wrapper-layout) guide for recommended markup and CSS. ```html HTML theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}

Clinical notes ``` ## Step 2: Create auth manager Now you need to create the **Auth Manager** for your application. In order to create the Auth Manager, you must have the `partnerId` and `partnerToken` credentials from Suki. Refer to [Partner onboarding](/documentation/partner-onboarding) guide to learn how to get these credentials. Once you have all the required credentials, create **one** auth manager for the page (or app shell). **Code example for creating auth manager** ```js JavaScript theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}} import { SukiAuthManager } from "@suki-sdk/core"; const authManager = new SukiAuthManager({ partnerId: "YOUR_PARTNER_ID", // replace with your partner ID - required partnerToken: "YOUR_PARTNER_TOKEN", // replace with your partner token - required environment: "staging", // optional: "staging" | "production" loginOnInitialize: true, // optional: sign in as soon as this runs autoRegister: false, // optional: enable provider auto-registration providerId: "YOUR_PROVIDER_ID", // optional: provider identifier in your system providerName: "YOUR_PROVIDER_NAME", // optional: full provider display name providerOrgId: "YOUR_PROVIDER_ORG_ID", // optional: organization identifier for the provider in your system providerSpecialty: "YOUR_PROVIDER_SPECIALTY", // optional: clinical specialty }); ``` ## Step 3: Create dictation client After you have created the auth manager, you can create the **dictation client** for your application. The Dictation Client is the object that will be used to start the dictation session. Create **one** dictation client and reuse it for every **`show()`** call on that page. **Code example for creating dictation client** ```js JavaScript theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}} import { DictationClient } from "@suki-sdk/dictation"; const dictationClient = new DictationClient({ authManager }); ``` ## Step 4: Call show() to start dictation Now you can start the dictation session by calling the **`show()`** method on the dictation client. Call **`await dictationClient.show({ ... })`** from a click handler (or similar) when the DOM is ready. Pass **`mode`**, **`fieldId`**, **`rootElement`**, **`onSubmit`**, and any optional fields you need. Refer to [Configuration](/dictation-sdk/guides/configuration) guide for more details on the available options and how to use them. **Code example for starting dictation** ```javascript JavaScript expandable theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}} async function startDictation() { const root = document.getElementById("dictation-root"); const notes = document.getElementById("clinical-notes"); if (!root || !notes) { console.error("Missing dictation-root or clinical-notes in the DOM"); return; } try { await dictationClient.show({ mode: "in-field", // replace with your preferred mode - required fieldId: "clinical-notes", // often the same string as the textarea id rootElement: root, // replace with the DOM element where the dictation controls will be shown - required initialText: notes.value ?? "", // replace with the initial text for the dictation session - optional onSubmit: ({ fieldId, text }) => { const el = document.getElementById(fieldId); if (el) el.value = text; }, onCancel: ({ fieldId }) => { console.log("Dictation cancelled", fieldId); }, onDraft: ({ fieldId, text }) => { const el = document.getElementById(fieldId); if (el) el.value = text; // optional live preview while dictating }, }); } catch (err) { console.error("Dictation show() failed", err); } } document.getElementById("start-dictation")?.addEventListener("click", () => { void startDictation(); }); ``` **`onSubmit`** is required for a good user experience. If you omit it, dictation often **closes immediately** after the user acts. ## Callbacks Every callback receives the same shape as shown in the code example below: ```javascript JavaScript theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}} { fieldId: string, text: string } ``` Refer to [Callbacks](/dictation-sdk/guides/callbacks) guide for more details on the available callbacks and how to use them. ## Switching fields Calling **`show()`** again **replaces** the active session. You do **not** need to call **`hide()`** manually just to move from one field to another: ```js JavaScript theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}} await dictationClient.show({ /* field A options */ }); await dictationClient.show({ /* field B options */ }); ``` ## Complete code example Below is a complete code example in JavaScript for in-field mode with a single field. ```js JavaScript theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}} import { SukiAuthManager } from "@suki-sdk/core"; import { DictationClient } from "@suki-sdk/dictation"; const authManager = new SukiAuthManager({ partnerId: "YOUR_PARTNER_ID", // replace with your partner ID - required partnerToken: "YOUR_PARTNER_TOKEN", // replace with your partner token - required environment: "staging", // optional: "staging" | "production" loginOnInitialize: true, // optional: sign in as soon as this runs autoRegister: false, // optional: enable provider auto-registration providerId: "YOUR_PROVIDER_ID", // optional: provider identifier in your system providerName: "YOUR_PROVIDER_NAME", // optional: full provider display name providerOrgId: "YOUR_PROVIDER_ORG_ID", // optional: organization identifier for the provider in your system providerSpecialty: "YOUR_PROVIDER_SPECIALTY", // optional: clinical specialty }); const dictationClient = new DictationClient({ authManager }); async function startClinicalNotesDictation() { const root = document.getElementById("dictation-root"); const notes = document.getElementById("clinical-notes"); if (!root || !notes) return; try { await dictationClient.show({ mode: "in-field", fieldId: "clinical-notes", rootElement: root, initialText: notes.value ?? "", onSubmit: ({ fieldId, text }) => { const el = document.getElementById(fieldId); if (el) el.value = text; }, onCancel: ({ fieldId }) => { console.log("Cancelled", fieldId); }, }); } catch (e) { console.error(e); } } document.addEventListener("DOMContentLoaded", () => { document .getElementById("start-dictation") ?.addEventListener("click", () => void startClinicalNotesDictation()); }); ``` This page focuses on **`in-field`** dictation next to a specific input. If you want a **floating dictation panel** instead, set **`mode`** to **`"scratchpad"`** and follow [Scratchpad mode](/dictation-sdk/guides/scratchpad-mode) guide. ## Best practices * **Reuse one dictation client.** Build a single **DictationClient** for the page or shell and call it again for each dictation session. Creating a new client on every click or for every field often resets the hosted UI and feels flaky. * **Reuse one auth manager.** Create **SukiAuthManager** once and pass that same instance into the client, the same pattern as in the steps above. * **Handle when the user commits.** You must supply a submit handler so the SDK can deliver the final text. Without it, dictation often closes right after the user tries to finish. * **Pick a clear field label.** Each session needs a stable, unique **fieldId** in callbacks. Using the same value as the target input's **id** is a simple way to know which element to update. Refer to [Field IDs](/dictation-sdk/guides/configuration#field-ids-in-practice) guide for more details. * **Open dictation only when the host is ready.** The DOM node you use as the dictation host should exist and have real height before you open. Otherwise the dictation area can look blank. Refer to [Error handling](/dictation-sdk/guides/error-handling) and [In-field mode](/dictation-sdk/guides/in-field-mode) guides for more details. * **Catch failures when opening dictation.** Wrap the open call so auth or setup errors show up in your logs instead of disappearing. * **Move to another field by opening again.** A new open call replaces the active session. You usually do not need a separate hide step when you are only switching which field is dictating. ## Next steps Refer to the following guides for more information. [Configuration](/dictation-sdk/guides/configuration) to learn about the available options and how to use them. [React integration](/dictation-sdk/react-integration/react) to learn how to integrate the Dictation SDK with React. # Dictation SDK Prerequisites Source: https://developer.suki.ai/dictation-sdk/prerequisites Browser, layout, authentication, and partner setup required before you integrate the Suki Dictation SDK This guide outlines technical requirements you need to meet before you integrate the Dictation SDK. ## Technical requirements The following is required before you integrate the Dictation SDK: ### Browser and runtime * Your app runs in a **browser**. Dictation SDK does not support **Node.js** or **SSR** for iframe rendering. * The hosted dictation iframe is not something **SSR** alone covers; you still need **`HTMLIFrameElement`**, **`postMessage`**, and **DOM layout** on the client so the SDK can mount and size the iframe. ### Layout * Give dictation a **container** (**`rootElement`**) with **real height** and a stable layout box. ### Authentication requirements * The Dictation SDK needs `partnerId` and `partnerToken`. Refer to [Partner onboarding](/documentation/partner-onboarding) guide to learn how to get these credentials. Invalid credentials **block iframe initialization** . ## Information you will receive from Suki After you complete [Partner onboarding](/documentation/partner-onboarding), your Suki contact will provide you with `partnerId` and `partnerToken`. ## Next steps Refer to [Quickstart](/dictation-sdk/quickstart) guide to get started with the Dictation SDK. # Dictation SDK Quickstart Source: https://developer.suki.ai/dictation-sdk/quickstart Get started with the Dictation SDK by installing the packages, creating the auth manager and client, and opening a dictation session This guide walks you through the steps to integrate the Dictation SDK into your application. **What will you do** 1. Install the Dictation SDK package for your framework (JavaScript or React) 2. Create a `SukiAuthManager` from `@suki-sdk/core` with your partner token and provider fields 3. Create a `DictationClient` from `@suki-sdk/dictation` with your auth manager 4. Mount the Dictation UI into your application using the `encounter` object. **Using an AI coding tool?** Copy the following prompt to add the Suki developer documentation as a skill and [MCP server](/documentation/mcp) to your tool for better AI-assisted coding during the integration process. For all AI options (contextual menu, `llms.txt`, and `skill.md`), refer to [AI-optimized documentation](/documentation/ai-optimized-documentation). Install the Suki developer docs as skill to get context on Suki's developer tools, APIs, and SDKs. npx skills add [https://developer.suki.ai](https://developer.suki.ai) Then add the Suki developer docs MCP server for access to documentation search. Follow the MCP instructions at [https://developer.suki.ai/documentation/mcp](https://developer.suki.ai/documentation/mcp). ## Prerequisites Before you start, ensure you have the following: * You have received your **`partnerId`** and **`partnerToken`** from Suki. * Your app meets **browser**, **CSP**, and host requirements for the dictation iframe Refer to [Prerequisites](/dictation-sdk/prerequisites) for more details. ## Recommended integration pattern The Dictation SDK works best when you treat authentication and the dictation client as **long-lived objects** for a page or session. You should only change the specific field or surface receiving the dictation. This approach ensures that token refreshes and iframe setups remain predictable while avoiding duplicate overlays. A common mistake is to build a new **`DictationClient`** on every React render (for example, in the component body without **`useMemo`**) or to use a separate client for each text field. The SDK assumes **one client per page scope**. If you do not follow this pattern, the session and iframe will frequently tear down and restart. This creates an unstable experience for the user. Initialize **once per session** and reuse: Create **`SukiAuthManager`** from **`@suki-sdk/core`** after the **partner token** is available. Create **`DictationClient`** with that **`authManager`**. **Reuse** this client **across** dictation fields. In React, wrap components with **`DictationProvider`** from **`@suki-sdk/dictation-react`**. Show the dictation UI **per field** or **scratchpad**. Avoid recreating **`DictationClient`** on every render or **per field**. The **JavaScript** and **React** tabs under **Your first dictation session** below mirror this pattern: one auth manager, one client, then **`show()`** or **``** for the active target only. ## Field IDs Each dictation instance needs a **stable**, **unique** **`fieldId`**. The SDK sends it back on every callback with **`text`**, so you can route results to the right control. A common pattern is to match the target input's HTML **`id`**. Refer to [Field IDs](/dictation-sdk/guides/configuration#field-ids-in-practice) section in [Configuration](/dictation-sdk/guides/configuration) guide for more details. ## Install the packages ```shell pnpm theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}} pnpm add @suki-sdk/dictation @suki-sdk/core ``` ```shell npm theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}} npm install @suki-sdk/dictation @suki-sdk/core ``` ```shell yarn theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}} yarn add @suki-sdk/dictation @suki-sdk/core ``` More detail: [Installation](/dictation-sdk/installation). ```shell pnpm theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}} pnpm add @suki-sdk/dictation-react @suki-sdk/core ``` ```shell npm theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}} npm install @suki-sdk/dictation-react @suki-sdk/core ``` ```shell yarn theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}} yarn add @suki-sdk/dictation-react @suki-sdk/core ``` More detail: [Installation](/dictation-sdk/installation). ## Create your first dictation session Apply **Recommended integration pattern** above: build **`SukiAuthManager`** and **`DictationClient`** once, then open dictation only for the target that should be active. For **JavaScript**, give dictation a **container** (**`rootElement`**) with real height. Example markup: ```html theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}

``` Create the auth manager and client **once**, then call **`show()`** when the user should dictate (for example after a button click). Use **`try`** / **`catch`** so configuration or auth errors surface in your logs. ```javascript JavaScript expandable theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}} import { SukiAuthManager } from "@suki-sdk/core"; // Step 1: Create the auth manager import { DictationClient } from "@suki-sdk/dictation"; // Step 2: Create the client const authManager = new SukiAuthManager({ partnerId: "YOUR_PARTNER_ID", // replace with your partner ID - required partnerToken: "YOUR_PARTNER_TOKEN", // replace with your partner token - required environment: "staging", // optional - default is "production" loginOnInitialize: true, // optional - default is false providerName: "John doe", // optional - default is empty providerOrgId: "1234", // optional - default is empty providerId: "1234567890", // optional - default is empty providerSpecialty: "FAMILY_MEDICINE", // optional - default is empty }); const client = new DictationClient({ authManager }); // Step 3: Create the client async function startDictation() { try { await client.show({ mode: "in-field", // required - you must set this as per your use case fieldId: "clinical-notes", // required - you must set this to the ID of the textarea you want to dictate rootElement: document.getElementById("dictation-root"), // required - you must set this to the ID of the div you want to contain the dictation iframe initialText: document.getElementById("clinical-notes")?.value ?? "", // optional - you can set this to the initial text of the textarea onSubmit: ({ fieldId, text }) => { const el = document.getElementById(fieldId); if (el) el.value = text; }, onCancel: ({ fieldId }) => { console.log("Cancelled", fieldId); }, }); } catch (err) { console.error(err); } } // Call startDictation() from your UI when ready. ``` Your integration is working when the dictation UI appears inside **`dictation-root`**, you can dictate, and text you commit is written to the textarea in **`onSubmit`**. For optional settings and callbacks (**`onDraft`**, **`initialText`**, scratchpad **`mode`**, and more), refer to [Configuration](/dictation-sdk/guides/configuration). For iframe or layout problems, refer to [Error handling](/dictation-sdk/guides/error-handling) guide for more details. Create **`DictationClient`** once (**`useMemo`**), wrap the tree with **`DictationProvider`**, and render **``** only when that field should own the session. Unmounting **``** calls **`hide()`** for you. ```jsx React expandable theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}} import { useMemo, useState } from "react"; import { SukiAuthManager } from "@suki-sdk/core"; // Step 1: Create the auth manager import { DictationClient } from "@suki-sdk/dictation"; // Step 2: Create the client import { DictationProvider, Dictation } from "@suki-sdk/dictation-react"; // Step 3: Wrap the tree with DictationProvider export function NotesWithDictation() { const client = useMemo(() => { const authManager = new SukiAuthManager({ partnerId: "YOUR_PARTNER_ID", // replace with your partner ID - required partnerToken: "YOUR_PARTNER_TOKEN", // replace with your partner token - required environment: "staging", // optional - default is "production" loginOnInitialize: true, // optional - default is false providerName: "John doe", // optional - default is empty providerOrgId: "1234", // optional - default is empty providerId: "1234567890", // optional - default is empty providerSpecialty: "FAMILY_MEDICINE", // optional - default is empty }); return new DictationClient({ authManager }); // Step 4: Create the client }, []); // Step 5: Create the client once and reuse it across fields const [notes, setNotes] = useState(""); const [dictationActive, setDictationActive] = useState(false); return (

setNotes(e.target.value)}
          />
          <button
            type="button"
            onClick={() => setDictationActive((v) => !v)}
          >
            {dictationActive ? "Stop dictation UI" : "Start dictation"}
          </button>
          {dictationActive && (
            <Dictation
              fieldId="clinical-notes"
              mode="in-field" // required - you must set this as per your use case
              initialText={notes} // optional - you can set this to the initial text of the textarea
              onSubmit={({ text }) => setNotes(text)}
              onCancel={() => setDictationActive(false)}
            />
          )}
        </DictationProvider>
      );
    }
    ```

Your integration is working when turning dictation on shows the hosted UI, committed text updates **`notes`** through **`onSubmit`**, and **only one** **`<Dictation>`** is mounted at a time for that shared **`client`**.

<Tip>
      To wire **`rootElement`** with a ref (instead of **`document.getElementById`**),
      refer to [Configuration examples](/dictation-sdk/guides/examples/configuration-examples) and [React integration](/dictation-sdk/react-integration/react) guides for more details.
    </Tip>
  </Tab>
</Tabs>

## Next steps

<Icon icon="file-lines" /> Refer to the [Configuration](/dictation-sdk/guides/configuration) guide for more details on the available options and how to use them.

# Dictation SDK React Integration
Source: https://developer.suki.ai/dictation-sdk/react-integration/react

Learn how to integrate the Dictation SDK in a React application (browser-based) using the React package provided by Suki

This guide walks you through the process of integrating the Dictation SDK in a React application (browser-based) using the React package provided by Suki.

You will create **Auth Manager** and **Dictation Client** (typically inside **`useMemo`** so they are not recreated every render), wrap your tree with **Dictation Provider**, and render **Dictation** when the user should dictate.

Let's get started!

## Prerequisites

Before you begin, you must have the following requirements met:

* **Packages:** Install **`@suki-sdk/dictation-react`**, **`@suki-sdk/dictation`**, and **`@suki-sdk/core`**.
* **Partner credentials:** Obtain **`partnerId`** and **`partnerToken`** from Suki after [Partner onboarding](/documentation/partner-onboarding).
* **Browser and layout:** Your app runs in a **browser**, with a real DOM and enough layout for the dictation UI.

Refer to [Prerequisites](/dictation-sdk/prerequisites) guide for more details.

## Install the packages

Add all three packages to the same project you load in the browser:

<CodeGroup title="Install @suki-sdk/dictation-react, @suki-sdk/dictation, @suki-sdk/core">
  ```shell pnpm theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
  pnpm add @suki-sdk/core @suki-sdk/dictation-react @suki-sdk/dictation 
  ```

```shell yarn theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
  yarn add @suki-sdk/core @suki-sdk/dictation-react @suki-sdk/dictation 
  ```

```shell npm theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
  npm install @suki-sdk/core @suki-sdk/dictation-react @suki-sdk/dictation 
  ```
</CodeGroup>

<Tip>
  After you install, pull the SDK into your files with **`import`**, the same way as in the examples below. Use whatever approach your project already uses for other npm libraries.
</Tip>

## Step 1: Add container and field layout

For this example we will assume you are using **`in-field`** mode as your preferred mode.

In **`in-field`** mode you need **two** parts in the UI: a **`div`** (or similar) that you can pass as **`rootElement`**, where the dictation controls show up, and a **textarea** (or input) that **`onSubmit`** will update when the user finishes.

The dictation layer **matches the size of** **`rootElement`** when you set it, so that node should have a **height** you control. Refer to [Wrapper layout](/dictation-sdk/guides/configuration#wrapper-layout) guide for recommended markup and CSS.

**Code example for container and field layout**

```jsx React  theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
<div id="clinical-notes-dictation-root" style={{ minHeight: 120 }} />
<label htmlFor="clinical-notes">Clinical notes</label>
<textarea id="clinical-notes" rows={8} />
```

Wire **`value`**, **`onChange`**, and your start button in the same component (see Step 5).

## Step 2: Create auth manager

Now you need to create the **Auth Manager** for your application. In order to create the Auth Manager, you must have the **`partnerId`** and **`partnerToken`** credentials from Suki.

Refer to [Partner onboarding](/documentation/partner-onboarding) guide to learn how to get these credentials.

In React you usually create the auth manager **inside** the same **`useMemo`** as the dictation client (see Step 3), so both exist once per page or shell. The snippet below shows only the auth piece for clarity.

**Code example for creating auth manager**

```jsx React theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
import { SukiAuthManager } from "@suki-sdk/core";

const authManager = new SukiAuthManager({
  partnerId: "YOUR_PARTNER_ID", // replace with your partner ID - required
  partnerToken: "YOUR_PARTNER_TOKEN", // replace with your partner token - required
  environment: "staging", // optional: "staging" | "production"
  loginOnInitialize: true, // optional: sign in as soon as this runs
  autoRegister: false, // optional: enable provider auto-registration
  providerId: "YOUR_PROVIDER_ID", // optional: provider identifier in your system
  providerName: "YOUR_PROVIDER_NAME", // optional: full provider display name
  providerOrgId: "YOUR_PROVIDER_ORG_ID", // optional: organization identifier for the provider in your system
  providerSpecialty: "YOUR_PROVIDER_SPECIALTY", // optional: clinical specialty
});
```

## Step 3: Create dictation client

After you have created the auth manager, you can create the **dictation client** for your application. The Dictation Client is the object the React components use under the hood.

Create **one** dictation client and reuse it for the whole tree under **`DictationProvider`**. Use **`useMemo`** with an empty dependency array so you do **not** run **`new DictationClient(...)`** on every render.

**Code example for creating dictation client in React**

```jsx React expandable theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
import { useMemo } from "react";
import { SukiAuthManager } from "@suki-sdk/core";
import { DictationClient } from "@suki-sdk/dictation";

## Step 4: Wrap with DictationProvider

Pass the **`client`** from Step 3 into **`DictationProvider`**. Every component that renders **`<Dictation>`** must be a **child** of that provider.

**Code example for wrapping with DictationProvider**

```jsx React expandable theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
import { DictationProvider } from "@suki-sdk/dictation-react";

export function App() {
  const client = useMemo(/* ... Step 3 ... */, []);

return (
    <DictationProvider client={client}>
      {/* children that render <Dictation /> */}
    </DictationProvider>
  );
}
```

You can put **`DictationProvider`** at app root or only around the screen that needs dictation.

## Step 5: Render Dictation

Render **`<Dictation>`** only while that field should own the session (for example when the user clicked "Start dictation"). When **`<Dictation>`** unmounts, the SDK calls **`hide()`** for you.

Pass **`mode`**, **`fieldId`**, **`initialText`**, **`onSubmit`**, and any optional props you need. Refer to [Configuration](/dictation-sdk/guides/configuration) guide for more details on the available options and how to use them.

**Code example for rendering Dictation in React**

```jsx React expandable theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
import { useState } from "react";
import { Dictation } from "@suki-sdk/dictation-react";

function NotesEditor() {
  const [notes, setNotes] = useState("");
  const [dictationActive, setDictationActive] = useState(false);

return (
    <>
      <textarea
        id="clinical-notes"
        value={notes}
        onChange={(e) => setNotes(e.target.value)}
      />
      <button
        type="button"
        onClick={() => setDictationActive((v) => !v)}
      >
        {dictationActive ? "Stop dictation" : "Start dictation"}
      </button>
      {dictationActive && (
        <Dictation
          fieldId="clinical-notes"
          mode="in-field"
          initialText={notes}
          onSubmit={({ text }) => setNotes(text)}
          onCancel={() => setDictationActive(false)}
        />
      )}
    </>
  );
}
```

<Tip>
  You can also drive dictation with a single **`activeFieldId`** string and render one **`<Dictation>`** when it matches, which scales to multiple fields.
</Tip>

<Note>
  **`onSubmit`** is required for a good user experience. If you omit it, dictation often **closes immediately** after the user acts.
</Note>

## Callbacks

Props such as **`onSubmit`**, **`onCancel`**, and **`onDraft`** receive the same shape as in the JavaScript API:

```jsx React  theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
{ fieldId: string, 
text: string 
}
```

Refer to [Callbacks](/dictation-sdk/guides/callbacks) guide for more details on the available callbacks and how to use them.

<Note>
  You do not poll for text; the SDK calls your functions when the user commits or cancels, and may call **`onDraft`** when they move on without submitting (refer to [Callbacks](/dictation-sdk/guides/callbacks) guide for more details).
</Note>

## Switching fields

Use the same **`client`** and **`DictationProvider`**. Change which field is active by updating state (for example **`activeFieldId`**) so only one **`<Dictation>`** is mounted, or swap **`fieldId`** / **`initialText`** on the next mount. You do **not** need to call **`hide()`** yourself just to move from one field to another when unmounting one **`<Dictation>`** and mounting another is how your UI switches.

## Unmounting and hiding

When **`<Dictation>`** unmounts, the SDK **automatically** calls **`hide()`**. You do not need to call **`hide()`** yourself for normal React flows.

## Complete code example

Below is a complete code example in React for in-field mode with **`DictationProvider`**, a toggle button, and one field.

```jsx React theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
import { useMemo, useState } from "react";
import { SukiAuthManager } from "@suki-sdk/core";
import { DictationClient } from "@suki-sdk/dictation";
import { DictationProvider, Dictation } from "@suki-sdk/dictation-react";

export function NotesWithDictation() {
  const client = useMemo(() => {
    const authManager = new SukiAuthManager({
      partnerId: "YOUR_PARTNER_ID", // replace with your partner ID - required
      partnerToken: "YOUR_PARTNER_TOKEN", // replace with your partner token - required
      environment: "staging", // optional: "staging" | "production"
      loginOnInitialize: true, // optional: sign in as soon as this runs
      autoRegister: false, // optional: enable provider auto-registration
      providerId: "YOUR_PROVIDER_ID", // optional: provider identifier in your system
      providerName: "YOUR_PROVIDER_NAME", // optional: full provider display name
      providerOrgId: "YOUR_PROVIDER_ORG_ID", // optional: organization identifier for the provider in your system
      providerSpecialty: "YOUR_PROVIDER_SPECIALTY", // optional: clinical specialty
    });
    return new DictationClient({ authManager });
  }, []);

const [notes, setNotes] = useState("");
  const [dictationActive, setDictationActive] = useState(false);

return (
    <DictationProvider client={client}>
      <textarea
        id="clinical-notes"
        value={notes}
        onChange={(e) => setNotes(e.target.value)}
      />
      <button
        type="button"
        onClick={() => setDictationActive((v) => !v)}
      >
        {dictationActive ? "Stop dictation" : "Start dictation"}
      </button>
      {dictationActive && (
        <Dictation
          fieldId="clinical-notes"
          mode="in-field"
          initialText={notes}
          onSubmit={({ text }) => setNotes(text)}
          onCancel={() => setDictationActive(false)}
        />
      )}
    </DictationProvider>
  );
}
```

## Best practices

<Tip>
  * **Reuse one dictation client.** Build a single **DictationClient** inside **`useMemo`** (or equivalent) for the page or shell. Creating a new client on every render breaks that pattern and often resets the hosted UI.

* **Reuse one auth manager.** Create **SukiAuthManager** once inside the same **`useMemo`** as the client, as in the steps above.

* **Handle when the user commits.** You must pass **`onSubmit`** so the SDK can deliver the final text. Without it, dictation often closes right after the user tries to finish.

* **Pick a clear field label.** Each session needs a stable, unique **fieldId** in callbacks. Using the same value as the target input's **id** is a simple way to know which element to update. Refer to [Field IDs](/dictation-sdk/guides/configuration#field-ids-in-practice) guide for more details.

* **Give the dictation host real height.** The node you use for **`rootElement`** (when you set it) should have height you control. Otherwise the dictation area can look blank. Refer to [Error handling](/dictation-sdk/guides/error-handling) and [In-field mode](/dictation-sdk/guides/in-field-mode) guides for more details.

* **One active Dictation at a time.** Use boolean state or **`activeFieldId`** so you do not mount multiple dictation surfaces against the same **`client`** at once.

* **Rely on unmount for hide.** Removing **`<Dictation>`** is the normal way to tear down the UI; you usually do not call **`hide()`** yourself in React.
</Tip>

## Next steps

Refer to the following guides for more information.

<Icon icon="file-lines" /> [Configuration](/dictation-sdk/guides/configuration) to learn about the available options and how to use them.
<Icon icon="file-lines" /> [JavaScript integration](/dictation-sdk/javaScript-integration/javaScript) to learn how to integrate the Dictation SDK with plain JavaScript.

# AI-Optimized Documentation
Source: https://developer.suki.ai/documentation/ai-optimized-documentation

Use the contextual menu on any Suki developer documentation page to copy content, open pages in AI tools, or connect the documentation MCP server

Every page on this site includes a contextual menu for AI workflows. Use it to copy the current page as Markdown, open the page in supported AI assistants, or connect the documentation MCP server to your editor.

For MCP server setup, tools, and troubleshooting, refer to [Documentation MCP](/documentation/mcp).

## Context menu access

On any documentation page, open the contextual menu in the **table of contents (TOC) sidebar**.

The screenshot below shows the options available from that menu:

The menu includes **Copy page**, and one-click options to open the page in Perplexity, Grok, Devin, Google AI Studio, or Cursor.

You can also use the **Documentation MCP** control in the top navigation bar to copy setup snippets for Cursor, VS Code, Claude, and Claude Code.

## Page content options

**Copy page**

Copies the current page as Markdown. Use this when you want to paste page content into a chat or share it with your team.

## Open in AI tools

The contextual menu includes one-click options to open the current page in a supported AI assistant with the page content pre-loaded:

* **Open in Perplexity**
* **Open in Grok**
* **Connect to Cursor**
* **Open in Devin**
* **Open in Google AI Studio**

Use these when you want quick answers about the page you are reading without copying MCP server URL manually.

## MCP server options

**Copy MCP server URL**

Copies `https://developer.suki.ai/mcp` for manual MCP configuration in your AI tool or editor.

**Connect to Cursor**

Installs the Suki developer documentation MCP server in Cursor in one step.

For copy-ready JSON snippets and setup steps for Cursor, VS Code, Claude, and Claude Code, use the **Documentation MCP** dropdown in the top navigation bar, or refer to [Documentation MCP](/documentation/mcp).

<Note>
  The documentation MCP server provides **search** and **get page** tools only. It does not execute Suki API calls on your behalf.
</Note>

## Additional context for AI tools

Use these URLs when an AI tool needs broader context than a single page:

| Resource            | URL                                                        | Use when                                                                             |
| ------------------- | ---------------------------------------------------------- | ------------------------------------------------------------------------------------ |
| Documentation index | [`llms.txt`](https://developer.suki.ai/llms.txt)           | You need a list of all documentation pages with titles and descriptions              |
| Full documentation  | [`llms-full.txt`](https://developer.suki.ai/llms-full.txt) | Your question spans multiple products (APIs, SDKs, webhooks, form filling, and more) |
| Integration skill   | [`skill.md`](https://developer.suki.ai/skill.md)           | You are building an agent or assistant that integrates Suki APIs or SDKs             |

Install the Suki developer documentation skill from your project:

```bash npm theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
npx skills add https://developer.suki.ai
```

## How to use

<Steps>
  <Step title="Copy a page for a quick question" icon="copy">
    Open the contextual menu in the TOC sidebar and select **Copy page**. Paste the content into your AI tool and ask your question.
  </Step>

<Step title="Open the page in an AI assistant" icon="sparkles">
    Open the contextual menu and select **Open in Perplexity**, **Open in Grok**, **Connect to Cursor**, **Open in Devin**, or **Open in Google AI Studio**.
  </Step>

<Step title="Connect the MCP server for ongoing work" icon="plug">
    Select **Connect to Cursor** or **Copy MCP server URL** from the contextual menu, or use the **Documentation MCP** dropdown in the top navigation bar. Refer to [Documentation MCP](/documentation/mcp) for full setup steps.
  </Step>

<Step title="Load broader context when needed" icon="book">
    Use [`llms-full.txt`](https://developer.suki.ai/llms-full.txt) or [`skill.md`](https://developer.suki.ai/skill.md) when your question spans multiple integration paths or products.
  </Step>
</Steps>

<Tip>
  Click **Ask AI** in the bottom-right of the page for in-docs help while you browse. For project-level work in Cursor or VS Code, connect the documentation MCP server so your editor can search docs automatically.
</Tip>

## Next steps

<Icon icon="file-lines" /> Refer to [Documentation MCP](/documentation/mcp) for server URL, tools, editor setup, and troubleshooting.

<Icon icon="file-lines" /> Refer to [Quickstart](/documentation/getting-started) for the **Using an AI coding tool?** prompt that installs `skill.md` and the MCP server.

<Icon icon="file-lines" /> Refer to [Support](/documentation/support) for FAQs, the in-docs assistant, and Suki support channels.

# Ambient Audio Streaming
Source: https://developer.suki.ai/documentation/ambient-audio-streaming

Learn how to stream ambient audio over WebSocket and retrieve final results with REST APIs

Use this guide when you already have an **Ambient session** and need to stream live audio to **`GET /ws/stream`**.

The WebSocket is only for sending live audio and control messages for the active stream. After streaming, use the Ambient REST APIs to end the session, poll status, and retrieve transcripts, notes, and structured data.

For endpoint details and code examples, refer to the [Audio streaming API](/api-reference/ambient-sessions/audio-stream).

## How Ambient streaming works

Suki for Partners Ambient streaming works as follows:

1. Create an [Ambient session](/api-reference/ambient-sessions/create)
2. Open a WebSocket connection to **`GET /ws/stream`**.
3. Send one **`START_TIME`** message for the stream segment.
4. Send one JSON message per audio chunk.
5. Optionally send **`EVENT`** messages, such as **`PAUSE`**, **`RESUME`**, or **`KEEP_ALIVE`**, when control is needed.
6. Send the ambient end marker as the final **`AUDIO`** message.
7. Close the socket, then use [End Ambient session](/api-reference/ambient-sessions/end) to end the session and retrieve results.

<Warning>
  Ambient streaming uses JSON text frames. Do not send raw binary audio frames to this endpoint.
</Warning>

## Send JSON text frames

Every message you send on **`/ws/stream`** must be a UTF-8 JSON text frame.

* Each WebSocket frame must contain **exactly one JSON object**.
* Each client **`send`** should contain **one logical message**.
* Audio bytes go inside a JSON string field, not in a binary WebSocket frame.

<Warning>
  Do not:

* Send binary WebSocket frames.
  * Send multiple JSON objects in one frame.
  * Stream raw audio through HTTP, for example with **`Content-Type: application/json`**.

<Note>
    If the server receives non-JSON payloads, it returns parsing errors, such as invalid character or null byte errors.
  </Note>
</Warning>

## Message format

Each outbound message is a JSON object with a **`type`** field. For messages that carry a payload, use the **`data`** field.

The **`data`** value must be:

* Standard Base64 ([RFC 4648](https://datatracker.ietf.org/doc/html/rfc4648))
* An encoding of the raw bytes you intend to send
* Sent as a JSON string, regardless of the programming language you use

<Warning>
  Do not use:

* Hex encoding
  * URL-safe Base64
  * Raw binary inside JSON strings
</Warning>

### Start the stream segment

Send one **`START_TIME`** message before the audio chunks for a stream segment:

```json theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
{ "type": "START_TIME", "data": "<base64>" }
```

* **`data`**: Base64 of UTF-8 bytes of an RFC 3339 timestamp
* **Example timestamp**: **`2026-04-25T12:34:56Z`**

### Send audio chunks

Send audio with **`type`** set to **`AUDIO`**:

```json theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
{ "type": "AUDIO", "data": "<base64>" }
```

* **`data`**: Base64 of raw PCM audio bytes

### Send control events

Send control events with **`type`** set to **`EVENT`**:

```json theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
{ "type": "EVENT", "event": "PAUSE" }
```

Use the **`event`** field, not **`data`**. Supported values are **`PAUSE`**, **`RESUME`**, **`KEEP_ALIVE`**, **`CANCEL`**, and **`ABORT`**.

**Common use cases**:

* Pause or resume audio.
* Keep the connection alive.
* Cancel or abort a stream.

`EVENT` messages can appear at any point in the stream where control is needed.

### End the stream segment

Send the final **`AUDIO`** message with **`data`** set to **`RU9G`**:

```json theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
{ "type": "AUDIO", "data": "RU9G" }
```

<Note>
  **`RU9G`** is Base64 for ASCII **`EOF`** (**`0x45 0x4F 0x46`**).
</Note>

<Warning>
  Do not:

* Send **`EOF`** as plain text.
  * Use custom types like **`end_of_stream`**.
  * Use binary EOF signaling.
</Warning>

## Required message order

For each stream segment:

1. Send one **`START_TIME`** message.
2. Send one or more **`AUDIO`** messages with Base64 PCM audio.
3. Send any **`EVENT`** messages when control is needed.
4. Send a final **`AUDIO`** message with **`data`** set to **`RU9G`**.

## Complete the session after streaming

After sending the final **`RU9G`** message, close the WebSocket connection and complete the ambient session with REST.

<Steps>
  <Step title="Close the WebSocket Connection">
    Close the WebSocket connection from the client when you are done sending audio for that segment.
  </Step>

<Step title="End the Session Using REST">
    End the session using [End ambient session](/api-reference/ambient-sessions/end).
  </Step>

<Step title="Retrieve Results Using REST">
    Poll session status and fetch transcript and structured data using these REST APIs:

* [Poll session status](/api-reference/ambient-content/status)
    * [Fetch transcript](/api-reference/ambient-content/transcript)
    * [Fetch structured data](/api-reference/ambient-content/content)
  </Step>
</Steps>

<Note>
  Final transcripts and notes are not guaranteed to arrive over WebSocket. Treat REST APIs as the source of truth.
</Note>

## Audio format and chunking

Use raw PCM audio chunks in each **`data`** message after Base64 decode.

### PCM vs WAV

Raw PCM is audio data without a file container. **`.wav`** is a container format and includes headers.

If your source is WAV, remove the **44-byte** RIFF header, or decode the file to raw PCM before sending. Sending WAV headers as PCM reduces recognition quality and makes debugging harder.

### Recommended audio format

* **Encoding**: LINEAR16, PCM signed 16-bit little-endian
* **Channels**: Mono
* **Sample rate**: **16 kHz**

### Chunk size

Send audio in small chunks during streaming. For **16 kHz**, mono, **16-bit** audio, about **3200 bytes** per chunk is a common choice. For optimal performance, chunk the audio into **100 ms** packets.

### Encode each chunk

For every **`AUDIO`** message:

1. Take raw PCM bytes.
2. Encode the bytes using standard Base64 ([RFC 4648](https://datatracker.ietf.org/doc/html/rfc4648)).
3. Send the encoded string as **`data`**.

## Example flow

This example shows the outbound message sequence for one ambient stream segment: one **`START_TIME`** message, multiple **`AUDIO`** chunks, an optional **`EVENT`**, and the final **`RU9G`** end marker.

```json theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
{ "type": "START_TIME", "data": "<base64(timestamp)>" }

{ "type": "AUDIO", "data": "<base64(pcm chunk 1)>" }
{ "type": "AUDIO", "data": "<base64(pcm chunk 2)>" }

{ "type": "EVENT", "event": "PAUSE" }

{ "type": "AUDIO", "data": "<base64(pcm chunk 3)>" }

{ "type": "AUDIO", "data": "RU9G" }
```

## Troubleshooting

<AccordionGroup>
  <Accordion title="Sending WAV instead of PCM">
    **Symptom**: Poor transcription or failures

**Fix**: Strip the WAV header or decode to raw PCM.
  </Accordion>

<Accordion title="Incorrect Base64 encoding">
    **Symptom**: Server parse errors

**Fix**: Use standard Base64 (RFC 4648), not URL-safe Base64 or hex.
  </Accordion>

<Accordion title="Sending multiple JSON objects in one frame">
    **Symptom**: Server parse errors

**Fix**: Send one JSON object per WebSocket frame.
  </Accordion>

<Accordion title="Missing or incorrect EOF marker">
    **Symptom**: Stream does not finalize

**Fix**: Send **`RU9G`** as the final **`AUDIO`** message.
  </Accordion>

<Accordion title="Using data for EVENT messages">
    **Symptom**: Ignored or invalid control messages

**Fix**: Use the **`event`** field.
  </Accordion>

<Accordion title="Skipping REST after streaming">
    **Symptom**: Missing final transcript

**Fix**: Always fetch results through REST APIs.
  </Accordion>
</AccordionGroup>

# Ambient Clinical Documentation
Source: https://developer.suki.ai/documentation/ambient-documentation

How Suki's AI automatically generates clinical notes from patient-provider conversations

<span>Quick summary</span>
  </div>

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

<span>Last updated:</span>
    <span>May 2026</span>
  </div>
</div>

<Info>
  **Ambient documentation is supported by:** APIs, Web SDK, Mobile SDK, Headless Web SDK
</Info>

Ambient documentation automatically creates <Tooltip href="/Glossary/c">clinical notes</Tooltip> from patient-provider conversations.

Instead of typing notes during or after a visit of a patient, <Tooltip href="/Glossary/p">providers</Tooltip> can focus entirely on the patient while Suki listens, transcribes, and organizes the conversation into structured clinical documentation.

Ambient documentation helps providers to:

* **Save time**: No more typing notes during or after visits
* **Better patient care**: Providers focus on patients, not screens
* **Accurate documentation**: AI captures details that might be missed
* **Consistent format**: Notes follow standard clinical structures
* **EHR ready**: Generated notes integrate directly with EHR systems

## Use cases

<CardGroup>
  <Card title="In-person visits" icon="user">
    Capture patient conversations during in-person visits and generate structured clinical notes.
  </Card>

<Card title="Virtual visits" icon="phone">
    Capture patient conversations during virtual visits and generate structured clinical notes.
  </Card>

<Card title="Telehealth visits" icon="camera">
    Capture patient conversations during telehealth visits and generate structured clinical notes.
  </Card>

<Card title="Ambulatory care visits" icon="ambulance">
    Capture patient conversations during ambulatory care visits and generate structured clinical notes.
  </Card>
</CardGroup>

## How it works

Ambient documentation works in four main steps:

<Steps>
  <Step title="Create session">
    Start a new <Tooltip href="/Glossary/a">ambient session</Tooltip> for a patient visit. Provide basic information like:

* Patient details (name, date of birth, etc.)
    * Which note sections you want (e.g., History, Physical Exam, Assessment)
    * <Tooltip href="/Glossary/p">Provider</Tooltip> information

Suki returns a session ID that tracks everything for this visit.

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

<Step title="Record conversation">
    Start recording when the visit begins. Audio streams to Suki in real-time, where it's automatically converted to text using speech recognition.

**What happens:**

* Audio is captured from the conversation
    * Speech is converted to text automatically
    * Everything happens in real-time
  </Step>

<Step title="AI processing">
    After the conversation ends, Suki's AI analyzes the <Tooltip href="/Glossary/t">transcript</Tooltip>:

* Identifies clinically important information
    * Organizes content into the sections you requested
    * Structures it like a professional <Tooltip href="/Glossary/c">clinical note</Tooltip>

**Example:** The AI might extract "chest pain for 3 days" and put it in the "History of Present Illness" section.
  </Step>

<Step title="Get generated clinical note">
    Once processing is complete, retrieve the finished clinical note. The note includes:

* **Structured sections**: Content organized by <Tooltip href="/Glossary/l">LOINC</Tooltip> codes (e.g., History, Assessment, Plan)
    * **<Tooltip href="/Glossary/s">Structured data</Tooltip>**: Diagnoses, medications, and other coded information
    * **Full transcript**: Complete conversation transcript if needed

The note is ready to integrate directly into your EHR system.
  </Step>
</Steps>

## Key features

<CardGroup>
  <Card title="Accurate Speech Recognition" icon="microphone">
    Converts speech to text accurately, even with complex medical terminology.
  </Card>

<Card title="Multilingual Support" icon="language" href="/api-reference/capabilities/multilingual">
    Works with over 80 languages. Patients can speak in their preferred language, and notes are generated in English.
  </Card>

<Card title="Customizable Note Sections" icon="note" href="/documentation/note-sections">
    Choose which sections to include in your notes using standard LOINC codes. Match your EHR's expected format.
  </Card>

<Card title="Works in Background" icon="clock">
    Processes everything automatically. Handles interruptions gracefully so providers can focus on patients.
  </Card>

<Card title="Secure and HIPAA-Compliant" icon="lock">
    All audio and data are encrypted. Built to meet healthcare privacy and security requirements.
  </Card>
</CardGroup>

## Getting started

To use Ambient documentation in your application:

<Steps>
  <Step title="Get access" icon="user">
    Contact our [Partnership team](/documentation/partner-onboarding) to get onboarded and receive your credentials.
  </Step>

<Step title="Choose integration method" icon="code">
    Select how you want to integrate:

* **APIs**: Direct API integration for maximum control
    * **Web SDK**: Pre-built components for web applications
    * **Mobile SDK**: Native iOS integration for mobile apps
    * **Headless Web SDK**: React hooks for custom UI integration

Refer to the [Quickstart guide](/documentation/getting-started) to get started quickly.
  </Step>

<Step title="Test and deploy" icon="cloud">
    Test your integration thoroughly before deploying to production. Start with development or staging environments.
  </Step>
</Steps>

# Audio Streaming Overview
Source: https://developer.suki.ai/documentation/audio-stream

Learn the handshake, wire format, and message order for ambient and dictation WebSockets to stream audio

After you create an ambient session and seed the session context, you can stream audio to the session using the `GET /ws/stream` endpoint for ambient sessions or the `GET /ws/transcribe` endpoint for dictation sessions.

Both endpoints use WebSocket to stream audio.

<Info>
  **This guide applies to:** Direct HTTP and WebSocket integrations with Suki for Partner Ambient, Form Filling, and Dictation APIs.
</Info>

| Endpoint                 | Purpose                                                                                                            | API reference                                                                                         |
| :----------------------- | :----------------------------------------------------------------------------------------------------------------- | :---------------------------------------------------------------------------------------------------- |
| `GET` **ws/stream**      | Stream **PCM** audio into an **ambient** and a **form filling** session for note generation and related processing | [Audio streaming for ambient and form filling sessions](/api-reference/ambient-sessions/audio-stream) |
| `GET` **/ws/transcribe** | Stream **PCM\_S16LE** audio into a **dictation (transcription) session** for real-time text                        | [Stream audio to dictation session](/api-reference/audio-transcription/stream-transcription)          |

Use the **same base host** for REST and WebSocket calls in a given environment (for example staging **`https://sdp.suki-stage.com`** and **`wss://sdp.suki-stage.com`**). Your partnership team confirms which host and credentials apply.

<CardGroup>
  <Card title="Ambient Streaming" icon="waveform" href="/documentation/ambient-audio-streaming">
    Stream **PCM** audio into an **ambient session** for note generation and related processing. Use this endpoint when you already have an **ambient session** and want to push live audio for that session.
  </Card>

<Card title="Dictation Streaming" icon="waveform" href="/documentation/dictation-streaming">
    Stream **PCM\_S16LE** audio into a **dictation (transcription) session** for real-time text. Use this endpoint when you have a **dictation session** and want to push audio for that session.
  </Card>
</CardGroup>

<Tip>
  **Do not** send raw audio as **binary** WebSocket frames on **`/ws/stream`**. On **`/ws/transcribe`**, outbound audio is also sent as **JSON text** frames with Base64 payloads, not raw binary PCM frames.
</Tip>

## Side-by-side comparison

***

## Next steps

<Icon icon="file-lines" /> Learn more about the [Audio Streaming API reference](/api-reference/ambient-sessions/audio-stream)

<Icon icon="file-lines" /> Learn more about the [Dictation Streaming API reference](/api-reference/audio-transcription/stream-transcription)

<Icon icon="file-lines" /> Learn more about the [Audio Capture & Streaming FAQs](/api-reference/faqs/audio-capture-streaming)

# Download Ambient Session Audio
Source: https://developer.suki.ai/documentation/audio-streaming-download

Learn how to download the original audio recording from an ambient session for playback, verification, and compliance

<span>Quick summary</span>
  </div>

<div>
    Get secure, temporary access to the original audio from <Tooltip href="/Glossary/a">ambient sessions</Tooltip>. Use it to play back recordings in your app, verify notes against the conversation, or save files for compliance.
  </div>

<span>Last updated:</span>
    <span>May 2026</span>
  </div>
</div>

<Info>
  **Download session audio is supported by:** Ambient APIs
</Info>

In an ambient workflow, you can use the [Get session recording API](/api-reference/ambient-content/recording) to download the original audio from a session. This recording is the raw conversation captured during the visit.

Ambient sessions already generate <Tooltip href="/Glossary/t">transcripts</Tooltip>, notes, and <Tooltip href="/Glossary/s">structured data</Tooltip>. This API gives you access to the source audio so you can play it in your app, verify AI-generated outputs, or store it for compliance.

Use this capability when you need to:

* **Let physicians listen back**: Add a playback feature so providers can review the conversation.
* **Verify AI output**: Let providers compare a note to the actual conversation when they question it.
* **Meet compliance needs**: Save audio files for legal or regulatory requirements.

You request a recording URL from the Audio Streaming & Download API. The URL lets you either **stream** the audio (for playback with seeking) or **download** the full file.

<Warning>
  URLs are temporary and expire after a short time for security.
</Warning>

## Benefits

<CardGroup>
  <Card title="Stream for Playback" icon="microphone">
    Stream audio in your app. Supports seeking and scrubbing so users can jump to any part of the recording.
  </Card>

<Card title="Download for Storage" icon="download">
    Download the full audio file when you need to keep it for archival or compliance.
  </Card>

<Card title="Works for All Sessions" icon="globe">
    Available for both real-time streamed sessions and sessions where audio was uploaded after the visit.
  </Card>

<Card title="Time-Limited Access" icon="lock">
    Streaming URLs last 15 minutes for short sessions, or session length plus 10 minutes for long sessions. Download URLs last 1 hour.
  </Card>

<Card title="7-Day Availability" icon="clock">
    Recordings are available for 7 days after the session. After that, they are no longer accessible.
  </Card>

<Card title="Access Logging" icon="file-text">
    Each access is logged for compliance and security.
  </Card>

<Card title="WAV Format" icon="file">
    Recordings are returned in WAV format, ready for playback in standard media players.
  </Card>
</CardGroup>

## How it works

1. **Finish an ambient session**: Create a session, stream or upload audio, and end it. The recording is ready once the session is complete.
2. **Request a recording URL**: Call the recording API with your `session ID`. Choose streaming (for playback) or download (for saving the file). Some sessions may return multiple recordings; use the one you need.
3. **Use the URL**: Stream or download the audio in WAV format. If the response indicates streaming is not supported, use download mode instead. If the URL expires while someone is listening, request a **new one**.

### Workflow

```mermaid actions={false} theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
flowchart TD
    A[Ambient session complete] --> B[Request recording URL]
    B --> C{Need to play or save?}
    C -->|Play in app| D[Streaming]
    C -->|Save file| E[Download]
    D --> F[Get URL]
    E --> F
    F --> G[Stream/Download audio]
    G --> H[URL expires]
    
    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
    style G fill:#FFF394,stroke:#333,color:#000
    style H fill:#FFF394,stroke:#333,color:#000
```

## How to use the Download API

<Steps>
  <Step title="Complete an Ambient session">
    Create an ambient session, stream or upload audio, and end the session. The recording is available after the session is complete.

Use the [Create ambient session API](/api-reference/ambient-sessions/create) to create an ambient session.
  </Step>

<Step title="Request the Recording URL">
    Call the [Recording API endpoint](/api-reference/ambient-content/recording) with your ambient `session ID`. Use the `download` parameter: `false` for streaming (playback) or `true` for full file download.
  </Step>

<Step title="Stream or Download">
    Use the returned URL to stream or download the audio (WAV format).

<Warning title="URL Expiration">
      **URL Expiration**:

The recording URL is available for a limited time. You need to request a new URL when it expires.

* **Streaming**: The URL lasts 15 minutes for short sessions. For sessions longer than 15 minutes, it lasts long enough to play the full recording (session length plus 10 minutes).
      * **Download**: The URL lasts 1 hour.
    </Warning>

<Note title="Recording availability">
      **How long are recordings kept?**

**7 days** from the session date. After that, the recording is no longer available.
    </Note>
  </Step>

<Step title="Request a new URL when needed">
    If the URL expires during playback, call the recording endpoint again to get a fresh URL.
  </Step>
</Steps>

## Response structure for Download API

When the request succeeds, the API returns a `recordings` array. Each item in the array represents one recording chunk for the session.

<ResponseField name="recordings" type="array">
  List of recordings for the session. Each item contains a presigned URL and metadata.

<Expandable title="recording item fields">
    <ResponseField name="recording_id" type="string">
      Unique identifier for the recording.
    </ResponseField>

<ResponseField name="presigned_url" type="string">
      Temporary URL to stream or download the recording. This URL expires; see expiry times in the steps above.
    </ResponseField>

<ResponseField name="expires_at" type="integer">
      Unix timestamp when the presigned URL expires. Use this to know when to request a new URL.
    </ResponseField>

<ResponseField name="sequence_number" type="integer">
      The order of this recording chunk within the session. Sessions can have multiple recordings; use `sequence_number` to play or assemble them in the correct order.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="is_streamable" type="boolean">
  Whether the returned URLs support streaming with Range requests. If `false`, use `download=true` to get a download URL instead.
</ResponseField>

## Best practices

<Tip>
  * **Stream for playback**: Use streaming when building a player so users can seek to any part of the recording
  * **Download for archival**: Use download when you need to store the file long-term
  * **Handle 404 on uploaded sessions**: If you get 404 for a session where audio was uploaded, the recording may still be processing. Wait and retry
  * **Do not retry on 410**: When you get 410, the recording is permanently unavailable
  * **Refresh URLs when needed**: For streaming, the URL lasts 15 minutes or session duration plus 10 minutes for long sessions. Request a new URL when it expires
  * **Use access responsibly**: All access is logged; ensure your use meets your compliance requirements
</Tip>

## FAQs

<Accordion title="Why does the streaming URL last longer for long sessions?">
  For sessions longer than 15 minutes, the streaming URL is valid for the full session length plus 10 minutes. This lets you play the entire recording without the URL expiring mid-playback.
</Accordion>

<Accordion title="What audio format is returned?">
  Recordings are returned in WAV format. Use them in standard media players or HTML5 audio elements for playback.
</Accordion>

<Accordion title="Can a session have multiple recordings?">
  Yes. Some sessions may return multiple recordings. The API returns a list; use the recording that matches your needs. If the response indicates streaming is not supported for a recording, use download mode instead.
</Accordion>

<Accordion title="How long are recordings available?">
  Recordings are available for 7 days from the session date. After that, the recording is no longer accessible. If you need to keep the audio longer, download it within the 7-day window and store it in your own system.
</Accordion>

<Accordion title="What if I get 404 when requesting a recording?">
  For sessions where audio was uploaded (not streamed in real time), the recording may still be processing. Wait a moment and try again. If the session is older than 7 days, you will get 410 instead, which means the recording is permanently unavailable.
</Accordion>

# Available Core Workflows
Source: https://developer.suki.ai/documentation/core-workflows

Available core workflows for the Suki for Partners platform like Ambient, Dictation, and Form Filling

Suki for Partners offers different integration workflows depending on your use case and technical requirements. The two main workflows are ambient workflows and form filling workflows.

Ambient have their own set of APIs, SDKs, and documentation to help you get started while Form Filling have their own set of APIs,
SDKs (coming soon), and documentation to help you get started.

## How to choose the right workflow?

To help you choose the right workflow, we have created a [Decision guide](/documentation/workflows) that outlines the different workflows and their use cases.

In short, you need to consider the following factors:

* Your use case
* Your technical requirements
* Your team's expertise
* Your development environment

Based on your requirements, you can choose the right workflow from the following options:

<CardGroup>
  <Card title="Ambient" icon="waveform" href="/documentation/ambient-documentation">
    Choose ambient workflows to add ambient clinical intelligence to your application for doctor-patient conversations and other clinical workflows.
  </Card>

<Card title="Form Filling" icon="file-lines" href="/documentation/form-filling-overview">
    Choose form filling workflows to integrate with the Suki for Partners form filling capabilities for nursing and other clinical workflows.
  </Card>

<Card title="Dictation" icon="microphone" href="/documentation/dictation-overview">
    Choose dictation workflows to integrate with the Suki for Partners dictation capabilities for real-time audio transcription.
  </Card>
</CardGroup>

# Audio Dictation
Source: https://developer.suki.ai/documentation/dictation

Learn about the capabilities, common use cases, and how to choose Partner APIs, Web SDK, or Dictation SDK for Audio Dictation

<span>Quick summary</span>
  </div>

<div>
    Audio Dictation converts spoken conversations into text in real time. Use Partner APIs for full control, the Web SDK for browser apps with Suki dictation components, or the Dictation SDK for a hosted iframe experience with in-field and scratchpad modes.
  </div>

<span>Last updated:</span>
    <span>May 2026</span>
  </div>
</div>

<Info>
  **Audio Dictation is supported by:** Ambient Partner APIs, Web SDK, Dictation SDK
</Info>

<Note>
  * For **standalone** transcription with your own UI and server logic, use the REST-based [Dictation APIs](/api-reference/audio-transcription/create-session) and follow [Basic usage](/documentation/dictation-basic-usage).
  * For **browser** apps with Suki Web SDK packages, use the [Web SDK for audio dictation](/web-sdk/dictation-overview).
  * To embed dictation through a **Suki-hosted iframe**, use the [Dictation SDK](/dictation-sdk/introduction) <Badge icon="sparkles">Beta</Badge>.
</Note>

Audio Dictation lets providers speak naturally and receive transcribed text in real time. You can use it to capture clinical conversations, dictate notes, or populate fields in your application without manual transcription.

The Audio Dictation workflow focuses only on speech-to-text transcription. Unlike ambient documentation workflows, it does not generate structured clinical notes or summaries. This makes it a good fit when you need fast, lightweight transcription that integrates directly into your own workflows and user experience.

You can use Audio Dictation in both in-person and virtual care scenarios. Stream audio through the SDKs or APIs, receive intermediate and final transcripts, and manage dictation sessions in your application. The APIs and SDKs give you control over audio capture, session lifecycle, transcript handling, and downstream processing.

## Common use cases

<CardGroup>
  <Card title="Support in-person clinical dictation" icon="user">
    Capture provider dictation during in-person clinical encounters and retrieve transcribed text for downstream documentation workflows.
  </Card>

<Card title="Support telehealth dictation workflows" icon="video">
    Capture provider dictation during virtual visits and return transcribed text for use in telehealth or remote care workflows.
  </Card>

<Card title="Populate fields in your application" icon="input-text">
    Stream dictation into note fields, forms, or scratchpad areas in a web application using Web SDK or Dictation SDK patterns.
  </Card>

<Card title="Build custom transcription pipelines" icon="code">
    Own session lifecycle, audio capture, and transcript handling end to end with Partner REST and WebSocket APIs.
  </Card>
</CardGroup>

## Key features

<CardGroup>
  <Card title="Real-time Transcription" icon="microphone">
    See text appear as people speak, no waiting for the conversation to end.
  </Card>

<Card title="Multiple Sessions" icon="layer-group">
    Run multiple dictation sessions under one parent session for complex workflows.
  </Card>

<Card title="WebSocket Streaming" icon="wifi">
    Low-latency audio streaming for fast, responsive dictation.
  </Card>

<Card title="Clean Transcripts" icon="file-lines">
    Automatically formatted with proper punctuation, capitalization, and filler words removed.
  </Card>

<Card title="Intermediate and Final Texts" icon="align-left">
    Receive both intermediate (partial) transcripts as speech is processed and final transcripts when segments are complete.
  </Card>
</CardGroup>

## How it works

If you use the **REST-based Partner APIs**, the dictation workflow has three steps:

1. **Create a session** -
   Create a dictation session and receive a transcription\_session\_id.

2. **Stream audio** -
   Open a WebSocket connection and stream audio data to the session.

3. **Receive transcripts** -
   Receive transcribed text in real time as audio is processed.

**Handling multiple audio streams**

You can connect multiple WebSocket streams to the same dictation session by using the same transcription\_session\_id.

This allows you to:

* Stream audio from multiple sources
* Reconnect dropped WebSocket connections
* Support complex audio workflows

<Note>
  Transcripts from all streams are combined into a single dictation session.
</Note>

### Workflow for Partner APIs

```mermaid actions={false} theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
flowchart TD
    A[Create session] --> B[Get parent session ID]
    B --> C[Stream audio]
    C --> D[Get transcripts]
    D --> E{More audio?}
    E -->|Yes| C
    E -->|No| F[End session]
    
    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
```

## Available integrations

<Tabs>
  <Tab title="Partner APIs" icon="code">
    Use Partner APIs to build custom dictation workflows with direct control over audio streaming, session management, and transcript handling.

Partner APIs are best for server-side integrations or applications that manage their own UI and workflow orchestration.

With Partner APIs, you can:

* [Create Audio Dictation sessions](/api-reference/audio-transcription/create-session)
    * [Stream audio through WebSocket connections](/api-reference/audio-transcription/stream-transcription)
    * [End Audio Dictation sessions](/api-reference/audio-transcription/end-session)

<Note>
      For WebSocket handshake and wire format details, refer to the [Dictation streaming](/documentation/dictation-streaming) guide.
    </Note>
  </Tab>

<Tab title="Web SDK" icon="js">
    Use the Web SDK to add dictation to browser-based JavaScript or React applications.

The Web SDK provides prebuilt dictation components and shared authentication through `@suki-sdk/core`. You can launch dictation with `dictationClient.show({ ... })` or render the React `Dictation` component.

To get started, refer to the [Web SDK for Audio Dictation](/web-sdk/dictation-overview) guide, then follow the [JavaScript](/web-sdk/guides/dictation-javascript) or [React](/web-sdk/guides/dictation-react) integration guides.
  </Tab>

<Tab title="Dictation SDK" icon="window">
    Use the Dictation SDK to add hosted real-time speech-to-text experiences to browser applications.

The Dictation SDK supports in-field dictation and scratchpad workflows without requiring you to manage REST APIs or WebSocket connections directly.

The SDK manages authentication, iframe lifecycle, and transcript callbacks for you.

To learn more, refer to the following guides:

* [Dictation SDK overview](/dictation-sdk/introduction)
    * [Quickstart](/dictation-sdk/quickstart)
    * [In-field mode](/dictation-sdk/guides/in-field-mode)
    * [Scratchpad mode](/dictation-sdk/guides/scratchpad-mode)

<Note>
      The Dictation SDK is separate from the Headless Web SDK and direct Audio Dictation API integrations.
    </Note>
  </Tab>
</Tabs>

## Usage scenarios

If you're not sure which integration fits your use case, use the following table to map your scenario to the recommended integration. Best fit indicates the integration we recommend for that scenario.

## Next steps

<Icon icon="file-lines" /> Refer to the [Basic usage](/documentation/dictation-basic-usage) guide to get started with dictation using our Partner APIs.

# Dictation Basic Usage
Source: https://developer.suki.ai/documentation/dictation-basic-usage

Learn how to create a transcription session, stream audio, receive transcripts, and end the session when capture is finished

<Info>
  **This guide covers:** Audio Dictation [REST and WebSocket APIs](/api-reference/audio-transcription/create-session).

* For a **browser** app, use the [Web SDK for Audio Dictation](/web-sdk/dictation-overview) or the [Dictation SDK](/dictation-sdk/introduction) <Badge icon="sparkles">Beta</Badge> instead of building this REST and WebSocket flow yourself.
  * For wire format, handshake rules, and troubleshooting, refer to the [Dictation streaming](/documentation/dictation-streaming) guide.
</Info>

This guide walks you through how to build a standalone Audio Dictation workflow with the Audio Dictation REST APIs. In this workflow, you:

* Create an Audio Dictation session
* Stream audio over WebSocket
* Receive transcript updates
* End the session when Dictation is complete

Before you start, register the provider and get an **`sdp_suki_token`**. Refer to [Provider authentication](/api-reference/provider-authentication) and [Partner authentication](/documentation/partner-authentication) for more information.

## How the Audio Dictation works

The dictation workflow uses both REST APIs and a WebSocket connection.

1. Authenticate and create a session with the REST API.
2. Stream audio to the session over WebSocket and process transcript updates.
3. End the session.

## Create a Dictation session

Create a parent transcription session before you open the WebSocket connection. The response includes a **`transcription_session_id`**, which identifies the session across the workflow.

Use the **`transcription_session_id`** when you:

* Connect to **`/ws/transcribe`**
* End the dictation session with [End dictation session](/api-reference/audio-transcription/end-session)

Call <Badge>POST</Badge> [Create dictation session](/api-reference/audio-transcription/create-session):

```bash theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
curl --request POST \
  --url https://sdp.suki-stage.com/api/v1/transcription/session/create \
  --header 'Content-Type: application/json' \
  --header 'sdp_suki_token: <sdp_suki_token>' \
  --header 'sdp_provider_id: <sdp_provider_id>' \
  --data '{
    "audio_config": {
      "audio_encoding": "LINEAR16",
      "audio_language": "en-US",
      "sample_rate_hertz": 16000
    }
  }'
```

Example response:

```json theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
{
  "transcription_session_id": "123dfg-456dfg-789dfg-012dfg"
}
```

The API returns **`201 Created`** when the session is created successfully.

### Request details

* Include **`sdp_suki_token`** in every REST request and during the WebSocket handshake.
* **`transcription_session_id`** is optional in the create request. If you omit it, Suki generates one.
* **`audio_config`** is optional.
* **`audio_encoding`** must be **`LINEAR16`**.

## Stream audio over WebSocket

After you create the session, connect to <Badge>GET</Badge> **`wss://sdp.suki-stage.com/ws/transcribe`** when the session is **`READY`** or **`IDLE`**.

If the session is already **`RUNNING`**, **`COMPLETED`**, or in another state, the WebSocket handshake fails with **`FailedPrecondition`**.
For push-to-talk workflows that use multiple speech sessions with the same transcription\_session\_id, refer to [Dictation streaming](/documentation/dictation-streaming) for more information.

<Tip>
  Authenticate during the WebSocket handshake instead of sending credentials with each message.
</Tip>

### Authentication

For non-browser clients, send these headers during the upgrade request:

* `sdp_suki_token`
* `transcription_session_id`

For browser clients, use **`Sec-WebSocket-Protocol`**:

```bash theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
Sec-WebSocket-Protocol: SukiAmbientAuth,<sdp_suki_token>,<transcription_session_id>
```

### Send audio messages

Send audio data as JSON text frames.

Example audio message:

```json theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
{ "type": "AUDIO", "audioData": "<base64-encoded PCM_S16LE bytes>" }
```

After you finish streaming audio on the connection, send:

```json theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
{ "type": "EVENT", "event": "AUDIO_END" }
```

### Streaming requirements

* Send one JSON object per WebSocket **`send`**.
* Do not send raw binary frames.
* Use **`audioData`** for dictation audio payloads.
* Base64-encode **PCM\_S16LE** audio bytes in **`audioData`**.
* Do not use ambient streaming fields such as **`data`** or **`RU9G`**.

For wire format details, refer to [Dictation streaming](/documentation/dictation-streaming).

### Receive transcript events

Parse transcript messages from **`event.data`** in your WebSocket **`onmessage`** handler. Refer to [Stream audio to dictation session](/api-reference/audio-transcription/stream-transcription) for Python and TypeScript code examples, and [Dictation streaming](/documentation/dictation-streaming) for partial and final frames, **`EOF`**, and filtering rules.

Example partial frame:

```json theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
{
  "transcript": {
    "transcript": "the recognized text so far",
    "words": []
  },
  "is_final": false,
  "transcript_id": "01J9XABCDEFGHJKMNPQRSTVWXYZ" // example transcript_id
}
```

Example final frame:

```json theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
{
  "transcript": {
    "transcript": "The patient reports feeling better today",
    "words": [
      { "word": "The", "speaker": { "id": "S1" } },
      { "word": "patient", "speaker": { "id": "S1" } }
    ]
  },
  "is_final": true,
  "transcript_id": "01J9XWXYZABCDEFGHJKMNPQRSTUV" // example transcript_id
}
```

* **`is_final: false`**: partial (interim) text that may change in later messages.
* **`is_final: true`**: final text for that segment; the recognizer will not revise it.
* After the speech stream ends, the server sends **`{ "transcript": { "transcript": "EOF" } }`**. Treat that as end-of-results for that WebSocket; the connection closes shortly after.

<Note>
  Do not dedupe messages by **`transcript_id`**. The server assigns a new ID per frame, including partials.
</Note>

## End the Dictation session

When Dictation is complete:

1. Send **`AUDIO_END`**
2. Close the WebSocket connection
3. End the session with the REST API

Call <Badge>POST</Badge> [End Dictation session](/api-reference/audio-transcription/end-session):

Example response:

```json theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
{
  "transcription_session_id": "123dfg-456dfg-789dfg-012dfg",
  "status": "completed",
  "final_transcript": "The patient reports feeling better today. Blood pressure is stable at 120/80.",
  "duration": 300,
  "ended_at": "2024-11-26T10:35:00Z"
}
```

The API returns **`200 OK`** on success.

Possible **`status`** values include:

* **`completed`**
* **`cancelled`**
* **`failed`**

Use **`final_transcript`** as the complete transcript for the session.

## Common integration patterns

### Pattern 1: Standard Audio Dictation flow

A typical Audio Dictation workflow follows these steps:

<Steps>
  <Step title="Authenticate">
    Obtain an **`sdp_suki_token`** for the provider.
  </Step>

<Step title="Create the session">
    Call [Create dictation session](/api-reference/audio-transcription/create-session) and save the **`transcription_session_id`**.
  </Step>

<Step title="Stream audio">
    Open a WebSocket connection to **`/ws/transcribe`** when the session is **`READY`** or **`IDLE`**. Send **`AUDIO`** messages, handle partial and final inbound frames, and finish with **`AUDIO_END`**.
  </Step>

<Step title="Process transcripts">
    Update the UI with partial and final transcript updates from incoming WebSocket messages.
  </Step>

<Step title="End the session">
    Call [End dictation session](/api-reference/audio-transcription/end-session) and store the final transcript output.
  </Step>
</Steps>

### Pattern 2: Push-to-talk or reconnect

For push-to-talk, open **`/ws/transcribe`** when the session is **`READY`** or **`IDLE`**, stream one utterance, send **`AUDIO_END`**, wait for **`EOF`**, then close the WebSocket. When the session is **`READY`** or **`IDLE`** again, open a new WebSocket on the same **`transcription_session_id`** for the next utterance.

If a connection drops mid-utterance, open a new WebSocket with the same **`transcription_session_id`** and **`sdp_suki_token`** only when the session accepts a new speech session. End the parent session with REST only when the full dictation workflow is complete.

### Pattern 3: Configure audio settings

Pass **`audio_config`** in the create request when you need to specify:

* Audio encoding
* Language
* Sample rate

Ensure that the streamed audio format matches the configuration you provide.

### Pattern 4: Stream audio in chunks

For lower latency, send smaller **`AUDIO`** messages as audio becomes available instead of buffering the entire recording.

After the final audio chunk, send **`AUDIO_END`**.

## What you can build

<CardGroup>
  <Card title="Live Dictation Experiences" icon="microphone">
    Display partial and final transcript updates in real time while the provider speaks.
  </Card>

<Card title="Server-side Transcription Pipelines" icon="server">
    Capture audio on a backend service, stream it through **`/ws/transcribe`**, and store the final transcript output.
  </Card>

<Card title="Telehealth and In-person Workflows" icon="video">
    Add transcription workflows to virtual or in-person clinical experiences without ambient note generation.
  </Card>

<Card title="EHR and Form Integrations" icon="file-lines">
    Send transcript output into forms, notes, or downstream clinical systems after the session ends.
  </Card>
</CardGroup>

## Related API references

<CardGroup>
  <Card title="Create Dictation Session" icon="code" href="/api-reference/audio-transcription/create-session">
    Create a transcription session
  </Card>

<Card title="Stream Audio for Dictation" icon="wifi" href="/api-reference/audio-transcription/stream-transcription">
    Connect and stream audio over WebSocket
  </Card>

<Card title="End Dictation Session" icon="circle-xmark" href="/api-reference/audio-transcription/end-session">
    End a Dictation session
  </Card>
</CardGroup>

## Best practices

<Tip>
  * **Stream audio in small chunks** to reduce latency.
  * **Reuse the same `transcription_session_id`** when reconnecting WebSocket sessions.
  * **End sessions** after dictation completes to release resources.
  * **Match streamed audio settings** to your configured sample rate and encoding.
  * **Validate audio quality** before production deployment.
</Tip>

## FAQs

<Accordion title="What's the difference between Audio Dictation and Clinical Documentation?">
  | Feature                        | Description                                                                                  |
  | :----------------------------- | :------------------------------------------------------------------------------------------- |
  | Audio Dictation                | Converts speech into transcript text with formatting such as punctuation and capitalization. |
  | Ambient clinical documentation | Transcribes conversations and generates structured clinical documentation outputs.           |
</Accordion>

<Accordion title="How is /ws/transcribe different from ambient /ws/stream?">
  Dictation uses **`/ws/transcribe`** with **`audioData`** payloads and **`AUDIO_END`** events.

Ambient clinical documentation uses **`/ws/stream`** with different authentication flows and message formats.

For more information, refer to [Audio streaming](/documentation/audio-stream) and [Dictation streaming](/documentation/dictation-streaming).
</Accordion>

# Audio Dictation Overview
Source: https://developer.suki.ai/documentation/dictation-overview

Learn about Audio Dictation, when to use it, and how to integrate it into your application

Audio Dictation converts provider speech into text while a session is active. Providers can dictate during a visit or into a field in your application while your product receives partial and final transcript text.

Audio Dictation is different from **Clinical documentation (Ambient)**, which transcribes the visit and generates structured clinical notes, LOINC-based sections, and related outputs. Audio Dictation gives you **speech-to-text** you can route into your own UI, EHR fields, or downstream workflows.

## When to use Audio Dictation

Choose Audio Dictation when you need:

* Real-time transcription without generating a full ambient clinical note
* Transcript text you control in your application (display, edit, save, or send elsewhere)
* Browser-based dictation with Suki-managed UI (Web SDK or Dictation SDK), or full control with REST and WebSocket APIs

<Tip>
  Choose [Ambient clinical documentation](/documentation/ambient-documentation) when you need visit capture, note generation, structured clinical data, and related ambient outputs.
</Tip>

## Related topics

<CardGroup>
  <Card title="Audio Dictation" icon="microphone" href="/documentation/dictation">
    Capabilities, common use cases, how dictation works, and how to choose APIs, Web SDK, or Dictation SDK.
  </Card>

<Card title="Basic Usage" icon="code" href="/documentation/dictation-basic-usage">
    Step-by-step Partner API workflow: create a session, stream audio, receive transcripts, and end the session.
  </Card>

<Card title="Dictation Audio Streaming" icon="wifi" href="/documentation/dictation-streaming">
    WebSocket handshake, wire format, and message order for `GET /ws/transcribe`.
  </Card>
</CardGroup>

## Related SDKs and APIs documentation

Refer to these guides when you already know your integration path and want to dive deeper:

<CardGroup>
  <Card title="Dictation API References" icon="code" href="/api-reference/audio-transcription/create-session">
    REST and WebSocket references for transcription sessions.
  </Card>

<Card title="Web SDK for Audio Dictation" icon="js" href="/web-sdk/dictation-overview">
    JavaScript and React dictation with Suki Web SDK packages.
  </Card>

<Card title="Dictation SDK" icon="window" href="/dictation-sdk/introduction">
    Hosted iframe dictation with Suki Dictation SDK packages.

<Note>
      This SDK is in <Badge icon="sparkles">Beta</Badge> phase of development.
    </Note>
  </Card>
</CardGroup>

## Next steps

<Icon icon="file-lines" /> Complete the [Partner onboarding](/documentation/partner-onboarding) process and get your credentials.

# Dictation Audio Streaming
Source: https://developer.suki.ai/documentation/dictation-streaming

Learn how to stream dictation audio over WebSocket and handle real-time transcript results

Use this guide when you already have a **Dictation session** and need to stream live audio to **`GET /ws/transcribe`** for real-time transcription.

The WebSocket is only for the live audio stream and the real-time transcript frames that come back from the server. You still use the Dictation REST APIs to create the session before streaming, end the session after streaming, and retrieve final or cumulative results.

For endpoint details and code examples, refer to the [Stream audio to dictation session](/api-reference/audio-transcription/stream-transcription). For the full REST workflow, refer to [Audio dictation](/documentation/dictation).

## How Dictation streaming works

Suki for Partners dictation streaming works as follows:

1. Create or reuse a [Dictation session](/api-reference/audio-transcription/create-session).
2. Open a WebSocket connection to **`GET /ws/transcribe`**.
3. Send one JSON message per audio chunk.
4. Send an explicit end-of-audio message when the user stops speaking.
5. Read partial and final transcript messages from the socket.
6. Close the socket, then use [End dictation session](/api-reference/audio-transcription/end-session) to end the Dictation session and retrieve results.

<Warning>
  Dictation streaming uses JSON text frames. Do not send raw binary audio frames to this endpoint.
</Warning>

## Before you connect (Prerequisites)

Open **`GET /ws/transcribe`** only when the dictation session is **`READY`** or **`IDLE`**.

If the session is **`RUNNING`** because another audio stream is active, **`COMPLETED`**, or in another state that cannot accept speech, the WebSocket handshake **fails**. The server returns **`FailedPrecondition`** with a message such as **transcript session is not accepting new speech sessions**.

<Note>
  One dictation session can support **multiple speech sessions over time**, such as push-to-talk. After you send **`AUDIO_END`** and the server finishes processing that stream, wait until the session returns to **`READY`** or **`IDLE`** before opening another WebSocket for the next utterance.
</Note>

## Send JSON text frames

Every message you send on **`/ws/transcribe`** must be a UTF-8 JSON text frame.

<Warning>
  Do not:

* Send binary WebSocket frames for audio data on this JSON-based protocol.
  * Send more than one JSON object in a single frame.
  * Use HTTP endpoints to stream raw audio.

<Note>
    If the server receives a non-JSON payload where JSON is expected, parsing can fail with errors such as invalid character or null byte errors.
  </Note>
</Warning>

## Message format

Each outbound message is a JSON object with a **`type`** field. For audio chunks, the payload field is **`audioData`**.

### Audio chunks

Send audio with **`type`** set to **`AUDIO`**:

```json theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
{ "type": "AUDIO", "audioData": "<base64-encoded PCM_S16LE audio>" }
```

The **`audioData`** value must be:

* Standard Base64 ([RFC 4648](https://datatracker.ietf.org/doc/html/rfc4648))
* An encoding of the raw **PCM\_S16LE** bytes you intend to send
* Sent as a JSON string, regardless of the programming language you use

<Warning>
  Do not use:

* Hex encoding
  * URL-safe Base64
  * Raw binary inside JSON strings
</Warning>

### End-of-audio message

When you finish sending audio on the WebSocket, send one **`EVENT`** message with **`event`** set to **`AUDIO_END`**:

```json theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
{ "type": "EVENT", "event": "AUDIO_END" }
```

This message tells the server that no more audio chunks are coming for that stream.

<Warning>
  Do not:

* End dictation audio with **`{ "type": "AUDIO", "data": "RU9G" }`**. That is the ambient **`/ws/stream`** pattern.
  * Use custom end markers instead of **`AUDIO_END`** or the inbound **`EOF`**. See [Read transcript frames](#read-transcript-frames).
  * Use binary signaling in place of the JSON **`AUDIO_END`** message.
</Warning>

<Note>
  Dictation **`/ws/transcribe`** does **not** use **`START_TIME`**, does **not** use ambient-style **`AUDIO`** messages with a **`data`** field, and does **not** use the ambient end marker **`RU9G`**. Use **`audioData`** for chunks and **`EVENT`** with **`event`**: **`AUDIO_END`** when you are done sending audio.
</Note>

## Required message order

For each logical stream of audio on the socket:

1. Send one or more **`AUDIO`** messages. Each message includes one **`audioData`** chunk.
2. Send one **`EVENT`** message with **`event`**: **`AUDIO_END`** after the last audio chunk you intend to send on that connection.

There is **no** **`START_TIME`** step and **no** ambient **`RU9G`** end marker on this endpoint.

## Read transcript frames

For each upstream ASR result, the gateway sends a JSON text frame on the WebSocket. Parse **`event.data`** in **`onmessage`**, or use the equivalent message handler in your WebSocket stack.

For code samples, see [Stream audio to dictation session](/api-reference/audio-transcription/stream-transcription#code-examples).

### Partial and final transcripts

Use **`is_final`** to decide whether the text should be shown as draft text or committed to the transcript.

| `is_final`  | Meaning                                                                                                      |
| :---------- | :----------------------------------------------------------------------------------------------------------- |
| **`false`** | Partial, or interim, transcript. The text may change in later messages as the recognizer refines its result. |
| **`true`**  | Final transcript for that segment. The recognizer has committed to this text, and it will not be revised.    |

Example partial frame:

Example final frame:

### End of results

After the upstream stream ends, the server sends one terminal frame:

```json theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
{
  "transcript": {
    "transcript": "EOF"
  }
}
```

Treat **`transcript.transcript`** equal to **`EOF`** as the canonical end-of-results signal for that speech session. The WebSocket closes shortly after.

### Handle transcript frames in your UI

* **Empty transcripts are dropped server-side.** You only receive frames where **`transcript.transcript`** is non-empty, except the terminal **`EOF`** frame.
* **`words`** is most useful on final frames. Partial frames typically include an empty **`words`** array.
* **`transcript_id`** is generated for each emission, including partial frames. Two messages for the same spoken utterance can have different IDs. Do not dedupe by **`transcript_id`**. Use it to order messages and to distinguish separate final segments from each other.
* Append or replace UI text based on **`is_final`**. Treat partials as draft text that may change, and commit finals to your transcript buffer.

## Complete the session after streaming

After you send **`AUDIO_END`** and finish reading results from the WebSocket, close the connection and complete the session with REST.

<Steps>
  <Step title="Close the WebSocket Connection">
    Close the WebSocket connection from the client when you are done sending audio on that connection.
  </Step>

<Step title="End the Dictation Session Using REST">
    End the transcription session using [End dictation session](/api-reference/audio-transcription/end-session).
  </Step>

<Step title="Retrieve Results Using REST">
    Follow [Audio dictation](/documentation/dictation) to retrieve final or cumulative transcripts and clean up the session. Use the same **`transcription_session_id`** and **`sdp_suki_token`** patterns as the rest of the Dictation APIs.
  </Step>
</Steps>

<Note>
  End the session and retrieve transcripts using the REST flows linked in the steps above. The outbound WebSocket contract in this guide does not replace those APIs.
</Note>

## Audio format and chunking

Use raw **PCM\_S16LE** audio chunks in each **`audioData`** message after Base64 decode.

### PCM vs WAV

**PCM\_S16LE** is raw audio data. **`.wav`** is a container format and usually includes a header before the audio data.

If your source is WAV, skip the **44-byte** header before chunking, or decode the file to raw PCM before sending. Use **`0`** as the offset if your buffer is already raw PCM. Sending WAV headers as PCM reduces recognition quality and makes debugging harder.

### Recommended audio format

* **Encoding**: PCM\_S16LE, PCM signed 16-bit little-endian, same family as **LINEAR16** at **16 kHz** mono in typical capture pipelines
* **Channels**: Mono
* **Sample rate**: **16 kHz**, aligned with what your integration expects

### Chunk size

Send audio in small chunks during streaming. For **16 kHz**, mono, **16-bit** audio, about **3200 bytes** per chunk is a common choice, which is about **100 ms** per message. Size chunks to your capture pipeline if your encoder differs.

### Encode each chunk

For every **`AUDIO`** message:

1. Take raw **PCM\_S16LE** bytes.
2. Encode the bytes using standard Base64 ([RFC 4648](https://datatracker.ietf.org/doc/html/rfc4648)).
3. Send the encoded string as **`audioData`**.

## Example flow

This example shows the outbound message sequence for one stream: multiple **`AUDIO`** chunks, followed by **`AUDIO_END`**.

```json theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
{ "type": "AUDIO", "audioData": "<base64(pcm_s16le chunk 1)>" }
{ "type": "AUDIO", "audioData": "<base64(pcm_s16le chunk 2)>" }

{ "type": "EVENT", "event": "AUDIO_END" }
```

## Troubleshooting

<AccordionGroup>
  <Accordion title="Sending WAV instead of PCM">
    **Symptom**: Poor transcription or failures

**Fix**: Strip the WAV header, for example **44** bytes, or decode to raw **PCM\_S16LE** before Base64 encoding.
  </Accordion>

<Accordion title="Incorrect Base64 encoding">
    **Symptom**: Server parse errors

**Fix**: Use standard Base64 (RFC 4648), not URL-safe Base64 or hex.
  </Accordion>

<Accordion title="Sending multiple JSON objects in one frame">
    **Symptom**: Parsing errors

**Fix**: Send one JSON object per WebSocket frame.
  </Accordion>

<Accordion title="Missing or incorrect AUDIO_END">
    **Symptom**: Stream does not finalize, or the server does not know audio is complete

**Fix**: Send `{ "type": "EVENT", "event": "AUDIO_END" }` after your last **`AUDIO`** message.
  </Accordion>

<Accordion title="Using data instead of audioData for AUDIO messages">
    **Symptom**: Ignored or invalid audio payloads

**Fix**: Use **`audioData`** for Base64 **PCM\_S16LE** chunks on **`/ws/transcribe`**.
  </Accordion>

<Accordion title="Wrong Sec-WebSocket-Protocol in the browser">
    **Symptom**: **401** on handshake or immediate disconnect

**Fix**: Use **`SukiAmbientAuth,<sdp_suki_token>,<transcription_session_id>`**, not **`SukiTranscriptionAuth`**, and not the ambient **session ID, token** order.
  </Accordion>

<Accordion title="Skipping REST after streaming">
    **Symptom**: Missing final transcript or session left open

**Fix**: Always call [End dictation session](/api-reference/audio-transcription/end-session) to ensure the session is closed and the transcript is generated.
  </Accordion>

<Accordion title="WebSocket fails to open with FailedPrecondition">
    **Symptom**: Handshake fails with **transcript session is not accepting new speech sessions**

**Fix**: Open **`/ws/transcribe`** only when the dictation session is **`READY`** or **`IDLE`**. Wait until the previous speech session on that **`transcription_session_id`** has finished, you sent **`AUDIO_END`**, received **`EOF`**, and the session returned to **`READY`** or **`IDLE`**, before you connect again.
  </Accordion>

<Accordion title="UI flicker or missing word-level detail">
    **Symptom**: Partial text jumps unpredictably, or **`words`** is always empty

**Fix**: Update the UI from **`is_final: false`** frames as draft text. Use **`words`** on **`is_final: true`** frames for word-level or speaker-aware display. Do not treat **`transcript_id`** as a stable key for the same utterance across partials.
  </Accordion>
</AccordionGroup>

# Suki for Partners executive summary
Source: https://developer.suki.ai/documentation/executive-summary

Executive summary for leaders evaluating Suki SDKs and APIs, including Web, Headless, Mobile, Dictation, ambient REST, and Form Filling: strategic value, partner proof points, integration options, business benefits, and next steps.

<div>
  <section>
    <div>
      <div>
        <div>
          <p>Executive summary</p>

<div />

<h1>Suki SDKs & APIs</h1>
          <p>Suki for partners · Enterprise integration</p>

<p>
            Bring clinical AI into your healthcare product with SDKs and APIs built for enterprise integration, product flexibility, and clinical scale.
          </p>
        </div>

<div>
    <div>
      <h2>Summary</h2>

<div>
        <p>
          This guide is written for executive, product, and engineering leaders who are deciding whether Suki should become part of their platform strategy. It explains the business problem, the product opportunity, the integration choices, and the operating model behind a Suki partnership. Use it to align leadership teams on customer value, technical feasibility, rollout approach, and the next decisions required to move forward.
        </p>

<p>
          Detailed implementation planning, including architecture, team responsibilities, technical requirements, and a sample timeline, is covered on the

<a href="/documentation/technical-execution">
            Technical execution
          </a>

page for engineering leaders, solution architects, and delivery teams.
        </p>
      </div>
    </div>

<div>
      <h2>Problem we solve</h2>

<div />

<p><strong>For clinicians and care teams:</strong> Clinical documentation can take <strong>5-6 hours every day</strong>, creating work that follows clinicians beyond the visit. The impact reaches far beyond note-taking: less time with patients, higher burnout risk, slower billing, and weaker retention. For healthcare platforms, documentation is now a strategic workflow that directly affects adoption, satisfaction, and operational performance.</p>
        </div>

<p><strong>For our partners:</strong> Building clinical AI in house requires sustained investment in model performance, clinical quality, security, compliance, infrastructure, and support. Suki gives partner teams a faster path to market while preserving focus for the product, engineering, and customer commitments that differentiate their own platform.</p>
        </div>
      </div>
    </div>

<section>
      <h2>Case studies</h2>

<div />

<p>Partner examples that show Suki moving from integration decision to deployed clinical capability.</p>

<div>
        <div>
          <h3>Zoom Healthcare Partnership</h3>
          <p>Zoom recognized that virtual care needs more than a reliable video connection. By integrating Suki's AI engine, Zoom can connect telehealth visits with clinical documentation that supports <strong>user experience and patient outcomes</strong>. For leaders, the partnership shows how clinical AI can expand platform value without forcing clinicians into a separate workflow.</p>

Read Case Study
            </a>
          </div>
        </div>

<div>
          <h3>WellSky Integration</h3>
          <p>WellSky's Ambient Listening solution brings AI-assisted documentation into behavioral health, long-term acute care, and rehabilitation settings. The integration helps reduce documentation load, supports specialty workflows, and gives WellSky a stronger clinician experience story across care settings where documentation complexity can slow adoption.</p>

Read Case Study
            </a>
          </div>
        </div>

<div>
          <h3>athenahealth Partnership</h3>
          <p><strong>Over 60,000 clinical encounters completed in 3 months</strong>, and counting. athenahealth integrated Suki's ambient technology into its clinical platform, giving clinicians a documentation workflow inside the tools they already use. The deployment demonstrates how ambient documentation can move from early adoption to a scaled platform capability.</p>

Read Case Study
            </a>
          </div>
        </div>
      </div>
    </section>

<section>
      <h2>Solution</h2>

<div />

<p>Suki SDKs and platform APIs give partners an enterprise integration layer for clinical AI inside their own products.</p>

<p>
        Suki is one platform for <a href="/Glossary/a">Ambient</a> capture and structured

<a href="/Glossary/c">
          Clinical notes
        </a>

Partners choose the integration model that matches their product strategy, user experience, and architecture: pre-built browser UI with the <strong>Web SDK</strong>, custom React with the <strong>Headless Web SDK</strong>, native <strong>iOS</strong> with the <strong>Mobile SDK</strong>, or <strong>Suki REST APIs</strong> when your backend or custom client should own orchestration, sessions, and content without Suki's pre-built UI. For <strong>clinical dictation</strong> in the browser, the <strong>Dictation SDK</strong> provides a hosted experience with clear auth and lifecycle hooks. For <strong>structured medical forms</strong>, <strong>Form Filling APIs</strong> provide OAuth-secured REST, streaming visit audio, and structured output aligned to Suki templates. Technical details for each path live in the respective SDK and

<a href="/api-reference/overview">
          API documentation
        </a>
      </p>

<div>
        <div>
          <div>
            <p>Clinicians can complete an encounter and leave with a draft note or structured form output that fits the partner workflow, often without manual typing. Product and engineering teams can deliver that outcome through web apps, native <strong>iOS</strong> apps, dictation embeds, form-filling sessions, or backend systems connected over HTTPS.</p>
            <p>What this means for partners</p>

<span><strong>Web, your way:</strong> Use the pre-built UI with <code>@suki-sdk/react</code> or <code>@suki-sdk/js</code>, or own the product surface with the Headless Web SDK (<code>@suki-sdk/platform-react</code>) while Suki provides the ambient and auth patterns for React.</span>
              </li>

<span><strong>Native iOS:</strong> The <strong>Mobile SDK</strong> brings ambient documentation into native iOS applications your users already rely on, using implementation patterns that fit Apple client stacks.</span>
              </li>

<span><strong>Suki REST APIs:</strong> Use OAuth-secured HTTPS to register users, manage ambient sessions, retrieve transcripts and note content, and connect Suki outputs to your EHR, data platform, or internal services when a server-side model is the right architecture.</span>
              </li>

<span><strong>Dictation and structured forms:</strong> The <strong>Dictation SDK</strong> adds browser dictation through a hosted surface your team can connect to fields or scratchpad workflows. <strong>Form Filling APIs</strong> support AI-assisted medical forms with sessions, audio streaming, and structured template output when the product deliverable is a completed form, not only an ambient note.</span>
              </li>

<span><strong>Faster than building in house:</strong> Your team integrates proven surfaces and contracts instead of staffing model development, clinical tuning, compliance scope, and production operations from scratch.</span>
              </li>

<span><strong>Production-ready at scale:</strong> The same clinical quality, specialty coverage, and security posture support Web, Headless, Mobile, Dictation, Form Filling, and ambient API integrations across large partner deployments.</span>
              </li>
            </ul>
          </div>

<text>
                Listening
              </text>

<text>
                Ambient capture
              </text>

<text>
                Live levels (partner UI stays yours)
              </text>

<text>
                Draft note ready to review
              </text>

<text>
                Send to workflow
              </text>

<figcaption>Example of a Suki-powered documentation experience embedded in a partner application.</figcaption>
        </figure>
      </div>
    </section>

<div />

<p>
        Partners can adopt one or more integration surfaces based on product ownership, desired user experience, and backend architecture. Each surface has dedicated documentation. Ambient and platform API contracts are in the

<a href="/api-reference/overview">
          API reference
        </a>

<a href="/form-filling-api-reference/overview">
          Form Filling API reference
        </a>
      </p>

<div>
        <div>
          <div><h3>Web SDK</h3></div>
          <p>Pre-built browser UI through <code>@suki-sdk/react</code> and <code>@suki-sdk/js</code>. Use it when your team wants to add ambient capture and note review quickly without owning the full clinical documentation interface.</p>

Learn More
            </a>
          </div>
        </div>

<div>
          <div><h3>Headless Web SDK</h3></div>
          <p>Custom React with platform hooks (<code>@suki-sdk/platform-react</code>) for teams that want to own the interface while using Suki for browser-based ambient workflows.</p>

Learn More
            </a>
          </div>
        </div>

<div>
          <div><h3>Mobile SDK</h3></div>
          <p>Native iOS support for partners bringing ambient documentation into mobile clinical workflows.</p>

Learn More
            </a>
          </div>
        </div>

<div>
          <div><h3>Suki REST APIs</h3></div>
          <p>OAuth-secured HTTPS APIs for sessions, notes, ambient content, and related operations when your backend or custom client should own orchestration.</p>

Learn More
            </a>
          </div>
        </div>

<div>
          <div><h3>Dictation SDK</h3></div>
          <p>Browser dictation with a hosted experience, auth, and callbacks. Use <code>@suki-sdk/core</code> and <code>@suki-sdk/dictation</code> (or React wrappers) when clinicians need dictation inside your application and your team should not build the speech UI from scratch.</p>

Learn More
            </a>
          </div>
        </div>

<div>
          <div><h3>Form Filling APIs</h3></div>
          <p>OAuth-secured REST, WebSocket visit audio, webhooks, and structured medical-form output for products that need AI-assisted forms and templates in addition to ambient notes.</p>

Learn More
            </a>
          </div>
        </div>
      </div>
    </div>

<section>
      <h2>Potential use cases</h2>

<div />

<h3>Clinical and partner workflows</h3>
          </div>

<p>Embed ambient documentation directly into your product so users can stay in one workflow. Notes can move into the encounter, chart, or handoff path in a format aligned to your data model.</p>
        </div>

<h3>Telehealth platforms</h3>
          </div>

<p>Extend virtual care beyond the video visit by pairing the encounter with documentation capture and draft note generation. Clinicians can close visits with less after-call documentation, and product teams can strengthen the telehealth experience.</p>
        </div>

<h3>Specialty care systems</h3>
          </div>

<p>Support specialty-specific workflows where documentation requirements vary by care setting. Suki helps generate notes that reflect clinical context, so specialty products do not have to rely on generic documentation patterns.</p>
        </div>

<h3>Care management platforms</h3>
          </div>

<p>Help care coordinators focus on outreach, follow-up, and patient support instead of manual documentation. Captured interactions can become structured records that keep programs, teams, and handoffs aligned.</p>
        </div>
      </div>
    </section>

<section>
      <h2>Business benefits</h2>

<div />

<div>
        <div>
          <div><svg><path /></svg><span>Faster Time-to-Market</span></div>
          <div><p><strong>Weeks, not months.</strong> Partner teams can integrate production-ready components in 2-4 weeks instead of spending 6-12 months building AI infrastructure, clinical workflows, and operational support in house. That accelerates market entry while keeping engineering capacity focused on the product areas only your team can build.</p></div>
        </div>

<div>
          <div><svg><path /></svg><span>Cost Savings</span></div>
          <div><p>When clinicians reclaim <strong>2-3 hours per day</strong> from documentation, organizations can improve capacity, reduce after-hours work, and support retention. Timely note completion can also shorten billing cycles and reduce administrative friction across downstream teams.</p></div>
        </div>

<div>
          <div><svg><path /></svg><span>Competitive Differentiation</span></div>
          <div><p>AI-powered documentation can become a visible product differentiator in a crowded healthcare technology market. It gives product and commercial teams a high-value workflow to package, sell, and expand while helping the platform meet rising clinician expectations for intelligent automation.</p></div>
        </div>

<div>
          <div><svg><path /></svg><span>Improved Quality of Care</span></div>
          <div><p>When clinicians spend less time documenting and more time with patients, visits can become more focused and complete. Timely notes support care continuity, reduce information gaps, and help care teams make decisions with better clinical context.</p></div>
        </div>

<div>
          <div><svg><path /></svg><span>Security & Compliance</span></div>
          <div><p>Suki supports enterprise healthcare requirements, including HIPAA compliance, SOC 2 Type II certification, and encryption. Partners can integrate clinical AI into their product experience while relying on Suki's established security and compliance posture.</p></div>
        </div>
      </div>
    </section>

<section>
      <h2>What partners get</h2>

<div />

<p>Partners get one clinical documentation platform with several ways to integrate. Whether your roadmap calls for pre-built browser UI, custom React, native iOS, dictation embeds, Form Filling APIs, or server-side ambient API flows, Suki provides production-ready surfaces, shared clinical depth, and documentation matched to the path you choose.</p>

<div>
        <div><div><h3>Web, Headless, Mobile, Dictation, and APIs</h3></div><p>Use the <strong>Web SDK</strong> (<code>@suki-sdk/react</code>, <code>@suki-sdk/js</code>) for ready-made UI, the <strong>Headless Web SDK</strong> (<code>@suki-sdk/platform-react</code>) when you own the browser experience, the <strong>Mobile SDK</strong> for native iOS, the <strong>Dictation SDK</strong> for hosted browser dictation, <strong>Form Filling APIs</strong> for structured form sessions, or <strong>Suki REST APIs</strong> when orchestration, sessions, and content should live in your backend or custom client.</p></div>
        <div><div><h3>Production-Ready SDKs and APIs</h3></div><p>Packages and HTTPS APIs built for clinical workloads, enterprise expectations, and partner deployments. The operating model stays consistent whether you embed UI, use platform hooks, or integrate over OAuth-secured APIs.</p></div>

<div>
          <div><h3>Documentation per surface</h3></div>

<p>
            Each integration path has its own guides and reference material. Ambient platform API contracts, endpoints, and auth patterns live in the

<a href="/api-reference/overview">
              API reference
            </a>

<a href="/form-filling-api-reference/overview">
              Form Filling API reference
            </a>

SDK behavior and samples live in the Web, Headless, Mobile, and Dictation documentation.
          </p>
        </div>

<div><div><h3>Specialty optimization</h3></div><p>Optimized for <strong>100+ medical specialties</strong> across the platform. Cardiology notes should differ from behavioral health notes, and that clinical specificity carries across the surface you choose to ship.</p></div>
        <div><div><h3>Multilingual support</h3></div><p>Supports <strong>80+ languages</strong> for conversation capture with automatic English note generation. Patients can speak in their preferred language while clinicians and care teams receive formatted English documentation across web, mobile, or API-driven integrations.</p></div>
        <div><div><h3>UX and branding you control</h3></div><p>Customize the pre-built Web SDK UI to match your design system, own every screen with Headless, connect hosted dictation with the Dictation SDK, use your own client over APIs, or follow native iOS patterns with the Mobile SDK. You decide how much Suki chrome appears in the product.</p></div>
      </div>
    </section>

<h2>Next steps</h2>

<div />

<p>A partnership starts by aligning product goals, technical architecture, success criteria, and rollout strategy. Here's how we work together:</p>

<h3>Schedule a demo</h3>

<p>
              <strong>See it in action.</strong> Review how Suki SDKs and APIs fit a live clinical workflow. Our team tailors the discussion to your product, users, roadmap, and systems.
            </p>
          </div>
        </li>

<h3>Technical assessment</h3>

<p>
              <strong>We'll map the path.</strong> Solutions Engineering reviews your environment and defines the integration scope, dependencies, ownership model, and timeline.
            </p>
          </div>
        </li>

<h3>Pilot program</h3>

<p>
              <strong>Prove it works.</strong> Start with a focused user group, gather feedback, and validate clinical, product, operational, and adoption outcomes before expanding.
            </p>
          </div>
        </li>

<h3>Full deployment</h3>

<p>
              <strong>Scale with confidence.</strong> Roll out broadly with ongoing support so the integration can keep pace with your product roadmap, user base, and volume.
            </p>
          </div>
        </li>
      </ol>
    </div>

Technical Execution
      </a>

Contact Partnership Team
      </a>
    </div>
  </div>

<footer>
    <p>Suki for Partners</p>

<p>
      <a href="/documentation/technical-execution">Technical Execution →</a>
      <span> · </span>
      <a href="https://www.suki.ai/contact-us/">Contact Partnership Team →</a>
    </p>
  </footer>
</div>

# Authentication
Source: https://developer.suki.ai/documentation/faqs/authentication

Authentication mechanisms and security questions for Suki platform integration

<Accordion title="What is the authentication mechanism used by Suki Platform?">
  We support

* OAuth 2.0 ID token for public clients such as browsers, mobile devices etc.
  * Access token for confidential clients such as backend systems.
</Accordion>

<Accordion title="What is the webhook authentication mechanism?">
  We support HMAC

<a href="https://www.okta.com/identity-101/hmac/">
    (Hash-based message authentication code)
  </a>

for <Tooltip href="/Glossary/w">webhook</Tooltip> authentication (Details can be shared)
</Accordion>

<Accordion title="How will errors be handled during JWT token failures?">
  Client systems cannot authenticate with Suki's platform when a <Tooltip href="/Glossary/j">JWT</Tooltip> token fails. Suki returns standard HTTPS error codes. Refer to the
  <a href="/api-reference/authentication/login">login API</a>.
</Accordion>

# General
Source: https://developer.suki.ai/documentation/faqs/general

Frequently asked questions about the Suki Developer Platform and integration benefits

<Accordion title="What types of organizations can benefit from using the Suki for Partners?">
  Healthcare solutions, including electronic health records (<Tooltip href="/Glossary/e">EHR</Tooltip>s), telehealth applications, medical devices, and more, can now easily incorporate AI voice features directly into their offerings using the Suki APIs and <Tooltip href="/Glossary/s">SDK</Tooltip>s.

**Best for:**

* Electronic Health Record (EHR) systems
  * Telehealth platforms
  * Medical device manufacturers
  * Healthcare mobile app developers
  * Clinical workflow software providers
</Accordion>

<Accordion title="What kind of analytics and reporting capabilities does the Suki Platform provide?">
  Currently, the Suki platform does not offer built-in analytics and reporting capabilities. However, this is planned for an upcoming release. Stay tuned!

**Coming soon:**

* Usage analytics and insights
  * Integration performance metrics
  * Clinical documentation quality reports
</Accordion>

<Accordion title="What kind of support does Suki offer during the implementation process?">
  Suki offers 24/7 support for critical issues and is available to assist in any way we can. During the initial phase, we will hold regular check-in meetings to ensure any blockers are addressed promptly.

**Support includes:**

* 24/7 critical issue support
  * Regular implementation check-ins
  * Technical integration assistance
  * Documentation and training resources
</Accordion>

<Accordion title="What is the typical implementation timeline for the platform?">
  Overall, the typical implementation timeline ranges from 4 to 6 weeks.
  However, this can vary based on specific project requirements and resource
  availability. For a more accurate timeline tailored to your project, please
  contact our [support team](/documentation/support).
</Accordion>

# Security & Compliance
Source: https://developer.suki.ai/documentation/faqs/security

Security, compliance, and data retention policies for the Suki Developer Platform

<Accordion title="How long will you maintain the data related to ambient_session_id?">
  Suki retains and deletes your data for each <Tooltip href="/Glossary/a">ambient session</Tooltip> according to the following schedule:

* **Audio input**: The original audio recording is permanently deleted after **30** days.

* **Transcript**: The <Tooltip href="/Glossary/t">transcript</Tooltip> generated from the audio is permanently deleted after **30** days.

* **Clinical note**: The final <Tooltip href="/Glossary/c">clinical note</Tooltip> is retained for the duration of your **service contract**.
</Accordion>

<Accordion title="How is data security handled within the Suki platform?">
  To protect your data and comply with HIPAA, Suki uses multiple layers of technical, administrative, and physical security. Key measures include:

* **Encryption in transit**: All data transmitted to and from the Suki platform is encrypted using **TLS 1.2**.

* **Encryption at Rest**: Data at rest is encrypted using **AES-256** with Google Cloud services, such as Cloud SQL and Google Cloud Storage.

* **Edge protection**: Suki uses a Web Application Firewall (WAF) from **Akamai** to protect all edge traffic.

* **Data de-identification**: Suki uses de-identified and anonymized data for model training purposes. Any data that is used for ML training and improving the product is de-identified. For audio, we use a de-identification algorithm that breaks audio into chunks and isolates them such that the original audio cannot be re-constructed. We de-identify the transcript by removing all PII.
</Accordion>

<Accordion title="What measures are in place to protect patient privacy?">
  Suki uses comprehensive technical, administrative, and physical safeguards to protect patient privacy and secure data.

Before your integration sends personal data to the platform, the <Tooltip href="/Glossary/c">clinician</Tooltip> is **responsible for obtaining patient consent**. This responsibility includes:

* Maintaining their own consent policies that govern the collection, use, and disclosure of personal data.

* Obtaining all necessary authorizations from a patient before any personal data is made available to Suki.

**Additional privacy protections:**

* We do not identify the clinician or the patient in the voice recordings.

* Suki does not create or retain any voice signatures. We use voice only for transcription and summarization of the notes.

* We de-identify voice recordings by chunking files. We remove <Tooltip href="/Glossary/p">PHI</Tooltip> from text transcripts to prevent individual identification.

For complete details on how Suki handles data, please read the [**Suki Privacy Policy**](https://www.suki.ai/privacy-policy/).
</Accordion>

<Accordion title="How does the Suki platform ensure compliance with relevant healthcare regulations?">
  Suki complies with **HIPAA requirements**, which ensure data privacy laws are met. We sign Business Associate Agreements (BAA) for patient data handling with our customers.
</Accordion>

<Accordion title="Does Suki offer reseller agreements?">
  Through the Suki Reseller Program, you can embed the Suki Platform's core technology directly into your own solution. This allows you to sell your application powered by Suki's assistive technology.
</Accordion>

# Form Filling
Source: https://developer.suki.ai/documentation/form-filling

Learn about Form filling capabilities, common use cases, and how to integrate with Form Filling Partner APIs

<span>Quick summary</span>
  </div>

<div>
    Form filling converts visit conversation into structured medical form output using Suki templates. Use Form filling Partner APIs for full control over session lifecycle, audio streaming, and structured data retrieval in your own UI and workflows.
  </div>

<span>Last updated:</span>
    <span>May 2026</span>
  </div>
</div>

<Info>
  **Form filling is supported by:** Form filling APIs
</Info>

<Note>
  * For **standalone** form filling with your own UI and server logic, use the [Form filling APIs](/form-filling-api-reference/overview) and follow [Basic usage](/documentation/form-filling-basic-usage).
  * Stream visit audio on the shared Partner WebSocket **`GET /ws/stream`**. Use your **form-filling** **`ambient_session_id`**, not an Ambient clinical note session ID. Refer to [Ambient audio streaming](/documentation/ambient-audio-streaming).
</Note>

Form filling lets providers complete structured medical forms using natural conversation during a visit. You can use it for nursing workflows, intake and assessments, medication reviews, and other template-based capture without manual re-entry in your application.

The form filling workflow focuses on structured output for Suki medical form templates. Unlike ambient documentation workflows, it does not generate a full clinical note or LOINC-based note sections. This makes it a good fit when you need template-driven forms that integrate directly into your own workflows and user experience.

You can use form filling in both in-person and virtual care scenarios. Create a session, stream audio through the Partner WebSocket, and retrieve structured form data when processing completes. The APIs give you control over session lifecycle, context, audio capture, and downstream save logic.

## Common use cases

<CardGroup>
  <Card title="Support in-person clinical form capture" icon="user">
    Capture visit conversation during in-person encounters and retrieve structured form output for nursing and clinical workflows.
  </Card>

<Card title="Support telehealth form workflows" icon="video">
    Capture conversation during virtual visits and return structured form data for telehealth or remote care workflows.
  </Card>

<Card title="Run template-driven sessions" icon="list">
    List templates, bind **`form_template_id`** values in session context, and retrieve **generated\_values** after processing.
  </Card>

<Card title="Build custom form-filling pipelines" icon="code">
    Own session lifecycle, audio streaming, structured data retrieval, and EHR handoff end to end with Partner APIs.
  </Card>
</CardGroup>

## Key features

<CardGroup>
  <Card title="Voice-driven form capture" icon="microphone">
    Stream visit audio so Suki can populate structured form fields from conversation.
  </Card>

<Card title="Session lifecycle" icon="waveform">
    Create sessions, seed or update context, end visits, and track status until completion.
  </Card>

<Card title="Medical form templates" icon="list">
    Use Suki-defined templates with field definitions in each template **schema**.
  </Card>

<Card title="Structured retrieval" icon="table">
    Retrieve **generated\_values** and **non\_generated\_values** when processing finishes.
  </Card>

<Card title="Webhooks and polling" icon="bell">
    Poll session status and structured data, or use partner webhooks when configured for your account.
  </Card>
</CardGroup>

## How it works

If you use the **Form filling Partner APIs**, the workflow has these steps:

1. **Create a session** -
   Create a form-filling session and receive an **`ambient_session_id`**.

2. **Seed or update context** -
   Provide **`form_template_id`** values for the templates in scope for the visit.

3. **Stream audio** -
   Connect to **`/ws/stream`** and stream visit audio with that session ID.

4. **End the session** -
   End the session when visit capture is complete.

5. **Retrieve structured data** -
   Poll status and retrieve structured form output when processing finishes.

<Note>
  The form-filling **`ambient_session_id`** is not the same value as an [Ambient clinical note session](/api-reference/ambient-sessions/create). Use only the ID returned from [Create form filling session](/form-filling-api-reference/form-filling-sessions/create).
</Note>

### Workflow

```mermaid actions={false} theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
flowchart TD
    A[Create session] --> B[Get ambient_session_id]
    B --> C[Seed or update context]
    C --> D[Stream audio]
    D --> E[End session]
    E --> F[Poll status or webhook]
    F --> G[Get structured data]

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
    style G fill:#FFF394,stroke:#333,color:#000
```

## Next steps

<Icon icon="file-lines" /> Refer to the [Basic usage](/documentation/form-filling-basic-usage) guide to get started with form filling using our Partner APIs.

# Form Filling Basic Usage
Source: https://developer.suki.ai/documentation/form-filling-basic-usage

Learn how to create a form-filling session, seed context, stream audio, end the session, and retrieve structured form data

<Info>
  **This guide covers:** [Form filling Partner APIs](/form-filling-api-reference/overview).

* Stream visit audio on the shared Partner WebSocket **`GET /ws/stream`**. Refer to [Ambient audio streaming](/documentation/ambient-audio-streaming) for handshake, PCM format, message order, and **`EVENT`** controls.
</Info>

This guide walks you through how to build a standalone form-filling workflow with the Form filling Partner APIs. In this workflow, you:

* Create a Form filling session
* Seed session context with template metadata
* Stream visit audio over WebSocket
* End the session when capture is complete
* Retrieve structured form output when processing finishes

Before you start, register the provider and get an **`sdp_suki_token`**. Refer to [Partner authentication](/documentation/partner-authentication) and [Form filling authentication](/form-filling-api-reference/authentication).

## How the Form filling workflow works

The Form filling workflow uses Form filling REST APIs and the shared Partner WebSocket.

1. Create a session with the REST API.
2. Seed context with **`form_template_id`** values when needed.
3. Stream audio to the session over **`/ws/stream`**.
4. End the session with the REST API.
5. Poll status and retrieve structured data.

<Note>
  Both Form filling and [Ambient clinical note sessions](/api-reference/ambient-sessions/create) use the parameter name **`ambient_session_id`** in the API reference. Those identifiers refer to **different** sessions. Use only the ID returned from form-filling [Create form filling session](/form-filling-api-reference/form-filling-sessions/create) for form-filling REST calls and for **`/ws/stream`**.
</Note>

## Create a Form filling session

Create a Form filling session before you seed context or open the WebSocket. The response includes an **`ambient_session_id`** that you use for the rest of the workflow.

Call <Badge>POST</Badge> [Create Form filling session](/form-filling-api-reference/form-filling-sessions/create):

Example response:

```json theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
{
  "ambient_session_id": "123dfg-456dfg-789dfg-012dfg"
}
```

The API returns **`201 Created`** when the session is created successfully.

### Request details

* Include **`sdp_suki_token`** in every REST request and during the WebSocket handshake.
* The request body is optional. You may send **`correlation_id`** when your integration needs it.
* Save **`ambient_session_id`** for context, **`/ws/stream`**, end session, status, and structured-data calls.

## Seed session context

After you create the session, you can provide form template metadata for the visit. Context helps Suki generate structured output for the templates you select.

Call <Badge>POST</Badge> [Seed form filling session context](/form-filling-api-reference/form-filling-sessions/context):

```bash theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
curl --request POST \
  --url https://sdp.suki-stage.com/api/v1/form-filling/session/<ambient_session_id>/context \
  --header 'Content-Type: application/json' \
  --header 'sdp_suki_token: <sdp_suki_token>' \
  --header 'sdp_provider_id: <sdp_provider_id>' \
  --data '{
    "form_filling": {
      "values": [
        {
          "form_template_id": "019d4cdc-9319-7d81-ae2e-fd6de7f1b4f0"
        }
      ]
    }
  }'
```

### Request details

* The body is optional. If you omit it, you can continue to audio capture without seeding context.
* If you include **`form_filling`**, provide valid **`values`** with a required **`form_template_id`** (UUID) for each template.
* Refer to [Suki medical form templates](/form-filling-api-reference/info/suki-medical-form-templates) to list templates for your integration.
* To update context later, use <Badge>PATCH</Badge> [Update form filling session context](/form-filling-api-reference/form-filling-sessions/update-context).

## Stream visit audio

Form filling uses the Partner WebSocket <Badge>GET</Badge> **`/ws/stream`**, not a separate form-filling streaming path.

Authenticate during the WebSocket handshake with:

* **`sdp_suki_token`**
* Your form-filling **`ambient_session_id`**

For browser versus non-browser handshake headers, PCM format, chunking, and **`EVENT`** messages, refer to [Ambient audio streaming](/documentation/ambient-audio-streaming) and the [Audio streaming API reference](/api-reference/ambient-sessions/audio-stream).

Close the WebSocket when audio capture is complete, then call end session.

## End the form-filling session

When visit capture is complete:

1. Close the WebSocket connection used for audio.
2. End the session with the REST API.

Call <Badge>POST</Badge> [End form filling session](/form-filling-api-reference/form-filling-sessions/end):

## Retrieve structured form output

After you end the session, poll until processing reaches a terminal status, then retrieve structured data.

### Poll session status

Call <Badge>GET</Badge> [Form filling session status](/form-filling-api-reference/form-filling-sessions/status):

```bash theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
curl --request GET \
  --url https://sdp.suki-stage.com/api/v1/form-filling/session/<ambient_session_id>/status \
  --header 'sdp_suki_token: <sdp_suki_token>' \
  --header 'sdp_provider_id: <sdp_provider_id>'
```

Poll until the status is terminal (for example **`completed`** or **`failed`**). Refer to the status API reference for all status values.

### Get structured data

Call <Badge>GET</Badge> [Form filling structured data](/form-filling-api-reference/form-filling-sessions/structured-data):

```bash theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
curl --request GET \
  --url https://sdp.suki-stage.com/api/v1/form-filling/session/<ambient_session_id>/structured-data \
  --header 'sdp_suki_token: <sdp_suki_token>' \
  --header 'sdp_provider_id: <sdp_provider_id>'
```

Example response shape:

```json theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
{
  "generated_values": [],
  "non_generated_values": []
}
```

The response includes:

* **`generated_values`**: Form instances Suki generated for this session
* **`non_generated_values`**: Templates that did not receive generated output

When webhooks are enabled for your partner account, Suki can notify your application when processing completes. Refer to [Webhook](/documentation/webhook/overview) and [Asynchronous notifications](/api-reference/asynchronous/webhook).

## Common integration patterns

### Pattern 1: Standard Form filling flow

A typical Form filling workflow follows these steps:

<Steps>
  <Step title="Create the session">
    Call [Create Form filling session](/form-filling-api-reference/form-filling-sessions/create) and save **`ambient_session_id`**.
  </Step>

<Step title="Seed context">
    Call [Seed Form filling session context](/form-filling-api-reference/form-filling-sessions/context) with **`form_template_id`** values when needed.
  </Step>

<Step title="Stream audio">
    Connect to **`/ws/stream`**, stream audio per [Ambient audio streaming](/documentation/ambient-audio-streaming), then close the WebSocket.
  </Step>

<Step title="End the session">
    Call [End Form filling session](/form-filling-api-reference/form-filling-sessions/end).
  </Step>

<Step title="Retrieve structured data">
    Poll [status](/form-filling-api-reference/form-filling-sessions/status), then call [structured data](/form-filling-api-reference/form-filling-sessions/structured-data).
  </Step>
</Steps>

### Pattern 2: Update context during the visit

If the templates in scope change during the visit, call [Update Form filling session context](/form-filling-api-reference/form-filling-sessions/update-context) before you end the session.

### Pattern 3: Submit feedback on a form instance

After clinicians review generated output, call [Form filling session feedback](/form-filling-api-reference/form-filling-sessions/feedback). Include **`feedback_metadata.form_id`** for the medical form instance you are rating.

## What you can build

<CardGroup>
  <Card title="In-person and Virtual Form Filling Workflows" icon="user">
    Complete template-based forms during room or telehealth visits with structured output in your UI.
  </Card>

<Card title="Server-side Capture Pipelines" icon="server">
    Capture audio on a backend service, stream on **`/ws/stream`**, and store structured data for downstream systems.
  </Card>

<Card title="Nursing and Clinical Assessments" icon="file-lines">
    Bind Suki templates in context and route **generated\_values** into your chart or internal tools.
  </Card>

<Card title="Webhook-driven Completion" icon="bell">
    Trigger save or review flows when Suki notifies your backend that processing finished.
  </Card>
</CardGroup>

## Related API references

<CardGroup>
  <Card title="Create Form Filling Session" icon="code" href="/form-filling-api-reference/form-filling-sessions/create">
    Create a Form filling session
  </Card>

<Card title="Seed Session Context" icon="file-lines" href="/form-filling-api-reference/form-filling-sessions/context">
    Provide form template metadata
  </Card>

<Card title="Form Filling Structured Data" icon="table" href="/form-filling-api-reference/form-filling-sessions/structured-data">
    Retrieve structured form output
  </Card>
</CardGroup>

## Best practices

<Tip>
  * **Close the WebSocket before end session** so processing can start reliably.
  * **Use the form-filling session ID** for **`/ws/stream`**, not an Ambient clinical note session ID.
  * **Poll status** until terminal, or configure webhooks for completion events.
  * **Handle non\_generated\_values** in your UI so clinicians know which templates need follow-up.
  * **Store tokens securely** and refresh **`sdp_suki_token`** before expiry.
</Tip>

## FAQs

<Accordion title="What's the difference between Form filling and Ambient clinical documentation?">
  | Feature                        | Description                                                                                                        |
  | :----------------------------- | :----------------------------------------------------------------------------------------------------------------- |
  | Form filling                   | Converts visit conversation into structured medical form output for Suki templates you bind in session context     |
  | Ambient clinical documentation | Converts speech to text and generates structured clinical notes, LOINC-based sections, and related ambient outputs |
</Accordion>

<Accordion title="Where do I get form_template_id values?">
  Call [Suki medical form templates](/form-filling-api-reference/info/suki-medical-form-templates). Use **`template_id`** from each template in **`form_filling.values`** when you seed or update context.
</Accordion>

# Form Filling Workflows - Integration Decision Guide
Source: https://developer.suki.ai/documentation/form-filling-integration-decision-guide

Compare Form filling APIs to select the right integration method for form filling workflows in your healthcare application

Suki for Partners provides different integration paths for adding form filling capabilities to your application.
Currently we offer the Form Filling APIs integration path which is designed for custom implementation approaches, and levels of UI ownership.

This guide explains the available integration options for form filling 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 ambient clinical documentation and dictation workflows, please refer to the [Ambient workflows integration decision guide](/documentation/integration-decision-guide).

## Integration options

### Form Filling APIs

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

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

## How to choose

<Tabs>
  <Tab title="By Project Type">
    <AccordionGroup>
      <Accordion title="Web-based Healthcare Application">
        **Choose Form Filling APIs if:**

* You need structured medical form output from visit conversation
        * You will build your own UI for template selection, recording, and form review
        * You want full control at the REST and WebSocket level in the browser
      </Accordion>

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

* **Choose Form Filling APIs** - implement REST and WebSocket in your native app or through your backend

**For Android Applications:**

* **Choose Form Filling APIs** - same API surface with your Android client and audio capture
      </Accordion>

<Accordion title="Backend System or Server Integration">
        **Choose Form Filling APIs**

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

<Tab title="By Team Skills">
    <CardGroup>
      <Card title="Frontend Experience">
        **Recommended: Form Filling APIs**

Build your web or mobile UI and call Form Filling REST endpoints and the Partner WebSocket from your client or backend-for-frontend layer.
      </Card>

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

Full control and leverages existing API development skills
      </Card>

<Card title="iOS/Swift Experience">
        **Recommended: Form Filling APIs**

Native iOS integration against the same Partner APIs with your own UI and device audio handling
      </Card>

<Card title="Limited Development Resources">
        **Recommended: Form Filling APIs**

A single API path across platforms; scope UI to the minimum workflow your product needs for template capture and review
      </Card>
    </CardGroup>
  </Tab>

<Tab title="By Requirements">
    | Your Need                                    | Recommended Choice | Why                                                                              |
    | -------------------------------------------- | ------------------ | -------------------------------------------------------------------------------- |
    | **Structured forms from visit conversation** | Form Filling APIs  | Template-driven output with **generated\_values** and **non\_generated\_values** |
    | **Custom UI/UX on web or mobile**            | Form Filling APIs  | Use your stack and patterns against the API                                      |
    | **Multi-platform support**                   | Form Filling APIs  | Same API surface across web, mobile, and backend                                 |
    | **Complete UX control (any client)**         | Form Filling APIs  | Build exactly what you need at the protocol level                                |
    | **In-person or telehealth form capture**     | Form Filling APIs  | One session workflow; you own the capture experience                             |
    | **Template catalog and session context**     | Form Filling APIs  | List templates and bind **form\_template\_id** in context                        |
  </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>

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

**Form Filling APIs:**

* WebSocket client implementation capability
* HTTPS/TLS support for secure API communication
* Use the form-filling **ambient\_session\_id** from [Create form filling session](/form-filling-api-reference/form-filling-sessions/create) on Form Filling REST calls and on **GET /ws/stream** (refer to [Ambient audio streaming](/documentation/ambient-audio-streaming) for WebSocket wire format)

## Integration scenarios

<Tabs>
  <Tab title="Web Applications">
    <AccordionGroup>
      <Accordion title="EHR Integration">
        **Scenario:** Existing web-based Electronic Health Record system needing structured medical form capture during visits

**Recommended: Form Filling APIs**

• Integrates into your existing web application\
        • Supports template selection and structured form output for nursing and clinical workflows\
        • You manage session lifecycle, audio streaming, and save logic in your EHR
      </Accordion>

<Accordion title="Patient Portal">
        **Scenario:** Healthcare patient portal where providers complete intake or assessment forms during telehealth visits

**Recommended: Form Filling APIs**

• Capture visit conversation in the browser\
        • Retrieve structured form data when processing completes\
        • Seamless integration with existing patient management systems
      </Accordion>

<Accordion title="Custom-branded form capture experience">
        **Scenario:** Web clinician workflow where form filling must match your design system, layout, and interaction patterns

**Recommended: Form Filling APIs**

• Full control over recording controls, status, and form presentation\
        • Seed and update session context with **form\_template\_id** values\
        • Stream audio on the Partner WebSocket with your form-filling session ID
      </Accordion>
    </AccordionGroup>
  </Tab>

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

**Recommended: Form Filling APIs**

• Native iOS performance and device integration\
        • Works with your existing iOS app architecture\
        • You implement REST, WebSocket, and form review UI in your app
      </Accordion>

<Accordion title="Android Healthcare App">
        **Scenario:** Native Android application for structured form capture during clinical visits

**Recommended: Form Filling APIs**

• Custom implementation using Form Filling APIs\
        • Full control over Android user experience\
        • Same session and structured-data workflow as web integrations
      </Accordion>
    </AccordionGroup>
  </Tab>

<Tab title="Backend Systems">
    <AccordionGroup>
      <Accordion title="Data Processing System">
        **Scenario:** Backend orchestration of form-filling sessions, context, and structured output into internal systems or an EHR

**Recommended: Form Filling 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: Form Filling APIs**

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

## Next steps

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

<CardGroup>
  <Card title="Form Filling Basic Usage" href="/documentation/form-filling-basic-usage" icon="list">
    Step-by-step Partner API workflow for form filling
  </Card>

<Card title="Form Filling API Overview" href="/form-filling-api-reference/overview" icon="list">
    Build custom form filling integrations with maximum flexibility
  </Card>

<Card title="Form Filling API Quickstart" href="/form-filling-api-reference/quickstart" icon="list">
    Get started with authentication and core API calls
  </Card>

<Card title="Form Filling" href="/documentation/form-filling" icon="list">
    Capabilities, use cases, and how form filling works
  </Card>

<Card title="Partner Onboarding" href="/documentation/partner-onboarding" icon="list">
    Start your integration journey with Suki
  </Card>
</CardGroup>

## 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, please prepare:**

* Description of your healthcare application and form filling workflows
* Target platform (web, iOS, Android, backend system)
* 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/)

# Form Filling Overview
Source: https://developer.suki.ai/documentation/form-filling-overview

Learn about form filling, when to use it, and how to integrate it into your application

Form filling converts provider and patient conversation during a visit into structured medical form output. Your application captures visit audio, and Suki maps what was said into template-driven fields you can review, edit, and save in your EHR or downstream workflows.

Form filling is different from **ambient workflows**, which transcribe the visit and generate structured clinical notes, LOINC-based sections, and related outputs. Form filling gives you **structured form instances** tied to Suki medical form templates you select for the session.

## When to use Form filling

Choose form filling when you need:

* Structured medical forms from visit conversation without generating a full ambient clinical note
* Form output you control in your application (display, edit, validate, or send elsewhere)
* Full control with Form filling REST APIs and the shared Partner WebSocket for audio

## Related topics

<CardGroup>
  <Card title="Form Filling" icon="file-lines" href="/documentation/form-filling">
    Capabilities, common use cases, how form filling works, and Form Filling Partner APIs.
  </Card>

<Card title="Basic Usage" icon="code" href="/documentation/form-filling-basic-usage">
    Step-by-step Partner API workflow: create a session, seed context, stream audio, end the session, and retrieve structured data.
  </Card>
</CardGroup>

## Related APIs documentation

Refer to these guides when you are ready to integrate:

<CardGroup>
  <Card title="Form Filling API References" icon="code" href="/form-filling-api-reference/overview">
    REST endpoints for sessions, context, structured data, feedback, and templates.
  </Card>

<Card title="Suki Medical Form Templates" icon="list" href="/form-filling-api-reference/info/suki-medical-form-templates">
    List Suki-defined templates and field definitions for session context.
  </Card>
</CardGroup>

## Next steps

<Icon icon="file-lines" /> Complete the [Partner onboarding](/documentation/partner-onboarding) process and get your credentials.

# Quickstart Guide
Source: https://developer.suki.ai/documentation/getting-started

Step-by-step guide to integrate Suki's Ambient APIs and SDKs into your healthcare application

This quickstart guide will help you integrate Suki's ambient documentation capabilities into your healthcare application. You'll go from initial setup to your first successful <Tooltip href="/Glossary/a">ambient session</Tooltip> in just a few steps.

<Note>
  **New to Suki?**

Consider following our comprehensive [Learning path](/documentation/learning-path) for a structured, step-by-step journey from onboarding to production deployment with progress tracking and time estimates.
</Note>

**What you'll accomplish**

By completing this guide, you will:

* Set up authentication with Suki developer tools
* Choose and integrate your preferred SDK or API
* Create your first ambient session with patient information
* Record and stream audio for at least 1 minute
* Retrieve a fully structured <Tooltip href="/Glossary/c">clinical note</Tooltip> with <Tooltip href="/Glossary/t">transcript</Tooltip>

**Estimated Time:** 30-45 minutes

<Tip>
  **Using an AI coding tool?**

Copy the following prompt to add the Suki developer documentation as a skill and [MCP server](/documentation/mcp) to your tool for better AI-assisted coding during the integration process. For all AI options (contextual menu, `llms.txt`, and `skill.md`), refer to [AI-optimized documentation](/documentation/ai-optimized-documentation).

<Prompt description="Install the Suki developer docs as a skill to get context on Suki's developer tools, APIs, and SDKs. Add the [MCP server](/documentation/mcp) for documentation search." icon="gear">
    Install the Suki developer docs as skill to get context on Suki's developer tools, APIs, and SDKs.

npx skills add [https://developer.suki.ai](https://developer.suki.ai)

Then add the Suki developer docs MCP server for access to documentation search. Follow the MCP instructions at [https://developer.suki.ai/documentation/mcp](https://developer.suki.ai/documentation/mcp).
  </Prompt>
</Tip>

## Before you begin

To integrate your application with Suki developer tools, you must meet the following requirements:

<CardGroup>
  <Card title="OAuth-compliant authentication system" icon="shield-check">
    For secure user management
  </Card>

<Card title="JWT tokens with consistent user identifiers" icon="key">
    For user authentication
  </Card>

<Card title="Publicly accessible JWKS endpoint" icon="link">
    For token validation
  </Card>

<Card title="ES6 compatible browser" icon="globe">
    Modern browser support (for Web SDK)
  </Card>
</CardGroup>

You'll also need the following from Suki to get started:

* **<Tooltip href="/Glossary/p">Partner ID</Tooltip>**:
  Unique identifier provided by Suki that you will use to authenticate our SDKs and APIs.

## How authentication works

Suki supports the following public key sharing authentication mechanisms. You will use your own identity provider to issue the token.

* **Stored Secret** - You provide your public key to Suki, and we store it securely in our database as an encrypted file.
* **JWKS URL**: You host your public keys at a public JSON Web Key Set (<Tooltip href="/Glossary/j">JWKS</Tooltip>) endpoint, and Suki fetches them dynamically to verify tokens.
* **Okta** - You use Okta as your Identity Provider, and Suki obtains the public key from your Okta issuer URL.
* **JWT Assertion** - You share your public key as a signed JWT that follows the RFC 7523 standard. Suki then verifies this JWT using our public key.

Refer to the [Partner onboarding](/documentation/partner-onboarding) and [Partner authentication](/documentation/partner-authentication) guides for more information.

<Warning>
  **Need Access?**

If you don't have the required information yet, contact our [partnership team](https://www.suki.ai/suki-partners/) to begin the onboarding process.
</Warning>

## Step 1: Choose your use case and workflow

Select the integration method that best fits your application requirements: Refer to the [Choose your workflow](/documentation/workflows) to help you decide.

## Step 2: Get started

Select a workflow below to get started. For ambient workflows, choose Web SDK, Mobile SDK, or Ambient APIs. For form filling workflows, choose the appropriate integration method.

<Tabs>
  <Tab title="Ambient Workflow" icon="waveform">
    <CardGroup>
      <Card title="Web SDK" icon="globe">
        **Best for:** React/JavaScript web applications

Pre-built UI components with automatic state management
      </Card>

<Card title="Mobile SDK" icon="mobile">
        **Best for:** Native iOS applications

Native framework optimized for mobile audio capture
      </Card>

<Card title="Ambient APIs" icon="code">
        **Best for:** Custom implementations

Maximum flexibility with direct API control
      </Card>
    </CardGroup>

<Callout>
      **Headless Web SDK** and **Dictation SDK** are additional integration options on Suki for Partners (**Beta**). Use the quickstarts below for install steps and configuration.

* [Headless Web SDK quickstart](/headless-web-sdk/quickstart)
      * [Dictation SDK quickstart](/dictation-sdk/quickstart)
    </Callout>

<Tabs>
      <Tab title="Web SDK" icon="globe">
        <Steps>
          <Step title="Install the package">
            Choose the appropriate package for your framework:

<Tabs>
              <Tab title="JavaScript">
                ```bash Bash theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
                npm install @suki-sdk/js @suki-sdk/core
                ```
              </Tab>

<Tab title="React">
                ```bash Bash theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
                npm install @suki-sdk/react @suki-sdk/core
                ```
              </Tab>
            </Tabs>
          </Step>

<Step title="Initialize SDK">
            Install `@suki-sdk/core` with `@suki-sdk/js` or `@suki-sdk/react`. Wrap your app with `SukiProvider`, create `SukiAuthManager` with your partner and provider values, then pass `authManager` into `initialize()` or `init()`. For details, see [Web SDK Quickstart](/web-sdk/quickstart) and [Migrating to Web SDK v3](/web-sdk/product-updates/migration-to-v3).

<CodeGroup>
              ```js JavaScript theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
              import { SukiAuthManager } from "@suki-sdk/core";
              import { initialize } from "@suki-sdk/js";

const authManager = new SukiAuthManager({
                partnerId: "f80c8db8-a4d0-4b75-8d63-56c82b5413f0", // Replace with your actual partner ID - REQUIRED
                partnerToken:
                  "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiYWRtaW4iOnRydWUsImlhdCI6MTUxNjIzOTAyMn0.KMUFsIDTnFmyG3nMiGM6H9FNFUROf3wh7SmqJp-QV30", // Replace with your actual partner token - REQUIRED
                providerName: "John doe", // Replace with the full name of the provider - REQUIRED
                providerOrgId: "1234", // Replace with the provider's organization ID - REQUIRED
                environment: "production", // Replace with the environment - REQUIRED
                loginOnInitialize: true, // Replace with false if you want to manually sign in the provider
                autoRegister: false, // Replace with true if you want to auto-register the provider
                providerId: "provider-123", // Replace with the provider's ID
                providerSpecialty: "FAMILY_MEDICINE", // Replace with the provider's specialty
              });

const sdkClient = initialize({
                authManager,
              });
              ```

```jsx React theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
              import { SukiProvider } from "@suki-sdk/react";
              function App() {
              return (
                <SukiProvider>
                  {/* Your application components go here */}
                  <ComponentA />
                </SukiProvider>
              );
              }
              ```
            </CodeGroup>
          </Step>

<Step title="Mount UI">
            In the same component where you initialized the SDK, mount the `SukiAssistant` component with encounter data:

<CodeGroup>
              ```js JavaScript expandable theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
                    import { SukiAuthManager } from "@suki-sdk/core";
                    import { initialize } from "@suki-sdk/js";

// replace this with your actual encounter data
                    const encounterDetails = {
                      identifier: "6ec3920f-b0b1-499d-a4e9-889bf788e5ab",
                      patient: {
                        identifier: "905c2521-25eb-4324-9978-724636df3436",
                        name: {
                          use: "official",
                          family: "Doe",
                          given: ["John"],
                          suffix: ["MD"],
                        },
                        birthDate: "1990-01-01",
                        gender: "Male",
                      },
                    };

const authManager = new SukiAuthManager({
                      partnerId: "f80c8db8-a4d0-4b75-8d63-56c82b5413f0", // Replace with your actual partner ID
                      partnerToken:
                        "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiYWRtaW4iOnRydWUsImlhdCI6MTUxNjIzOTAyMn0.KMUFsIDTnFmyG3nMiGM6H9FNFUROf3wh7SmqJp-QV30", // Replace with your actual partner token
                      providerName: "John doe", // Replace with the full name of the provider
                      providerOrgId: "1234", // Replace with the provider's organization ID
                      environment: "production", // Replace with the environment
                      loginOnInitialize: true, // Replace with false if you want to manually sign in the provider
                      autoRegister: false, // Replace with true if you want to auto-register the provider
                      providerId: "provider-123", // Replace with the provider's ID
                      providerSpecialty: "FAMILY_MEDICINE", // Replace with the provider's specialty
                    });

const sdkClient = initialize({
                      authManager,
                    });

// unsubscribe from the init event when no longer needed
                    window.addEventListener("beforeunload", () => {
                      unsubscribeInit();
                    });
              ```

```jsx React expandable theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
              import { useEffect, useMemo } from "react";
              import { SukiAuthManager } from "@suki-sdk/core";
              import { useSuki, SukiAssistant } from "@suki-sdk/react";

function ComponentA() {
              const authManager = useMemo(
              () =>
                new SukiAuthManager({
                  partnerId: "f80c8db8-a4d0-4b75-8d63-56c82b5413f0", // Replace with your actual partner ID
                  partnerToken:
                    "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiYWRtaW4iOnRydWUsImlhdCI6MTUxNjIzOTAyMn0.KMUFsIDTnFmyG3nMiGM6H9FNFUROf3wh7SmqJp-QV30", // Replace with your actual partner token
                  providerName: "John doe", // Replace with the full name of the provider
                  providerOrgId: "1234", // Replace with the provider's organization ID
                  environment: "production", // Replace with the environment
                  loginOnInitialize: true, // Replace with false if you want to manually sign in the provider
                  autoRegister: false, // Replace with true if you want to auto-register the provider
                  providerId: "provider-123", // Replace with the provider's ID
                  providerSpecialty: "FAMILY_MEDICINE", // Replace with the provider's specialty
                }),
              [],
              );

const { init, isInitialized } = useSuki();

// replace this with your actual encounter data
              const currentEncounter = {
              identifier: "6ec3920f-b0b1-499d-a4e9-889bf788e5ab",
              patient: {
                identifier: "905c2521-25eb-4324-9978-724636df3436",
                name: {
                  use: "official",
                  family: "Doe",
                  given: ["John"],
                  suffix: ["MD"],
                },
                birthDate: "1990-01-01",
                gender: "Male",
              },
              };

useEffect(() => {
              if (!isInitialized) {
                init({ authManager });
              }
              }, [init, isInitialized, authManager]);

return (
              <SukiAssistant encounter={currentEncounter} />
              {/* rest of your code */}
              );
              }
              ```
            </CodeGroup>
          </Step>

<Step title="Start recording">
            Click the recording button in the Suki web SDK UI to start capturing the conversation.
          </Step>

<Step title="Record for at least 1 minute">
            Record a test conversation. The session should be at least **1 minute long** for note generation to occur.
          </Step>

<Step title="Stop and retrieve note">
            Click stop recording button in the Suki web SDK UI. The generated note will automatically appear in the web SDK UI panel.
          </Step>
        </Steps>

<Note>
          For complete web SDK capabilities, refer to the [Web SDK section](/web-sdk/overview) of the documentation.
        </Note>
      </Tab>

<Tab title="Mobile SDK" icon="mobile">
        <Steps>
          <Step title="Install the framework">
            Add the Suki Mobile SDK to your iOS project following the [Installation guide](/mobile-sdk/installation).
          </Step>

<Step title="Initialize the SDK">
            Configure the SDK when your application starts:

<CodeGroup>
              ```swift Swift theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
              import SukiAmbientCore

// Set the SDK environment
              SukiAmbientCoreManager.shared.environment = .stage

// Initialize the SDK with partner information
              let partnerInfo: [String: AnyHashable] = [
                  SukiAmbientConstant.kPartnerId: "your-partner-id",
                  SukiAmbientConstant.kProviderInfo: [
                      SukiAmbientConstant.kOrgId: "provider_org_id",
                      SukiAmbientConstant.kName: "Dr. Jane Smith",
                      SukiAmbientConstant.kId: "providerId",
                      SukiAmbientConstant.kSpeciality: "FAMILY_MEDICINE"
                  ]
              ]

do {
                  try SukiAmbientCore.shared.initialize(
                      withPartnerInfo: partnerInfo,
                      with: true,
                      onCompletion: { result in
                          // Handle initialization result
                      },
                      withSessionDelegate: self,
                      withTokenProvider: self
                  )
              } catch {
                  print("Initialization failed: \(error)")
              }
              ```
            </CodeGroup>
          </Step>

<Step title="Create session">
            Initialize an ambient session with patient information:

<CodeGroup>
              ```swift Swift theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
              let sessionContext = [
                      SukiAmbientConstant.kSessionId: <encounter-id>,
                      SukiAmbientConstant.kIsMultilingual:isMultilingual
                  ] as [String : AnyHashable]        
                  SukiAmbientCoreManager.shared.createSession(with: sessionContext, onCompletion: { result in
                      switch result {
                      case .success(let sessionResponse):
                          print("Success")
                      case .failure(let error):
                          print("error = \(error)")
                      }
                  })
              ```
            </CodeGroup>
          </Step>

<Step title="Start recording">
            Begin capturing the clinical conversation:

<CodeGroup>
              ```swift Swift theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
              do {
                  try SukiAmbientCore.shared.start()
              } catch {
                  print("Recording failed: \(error)")
              }
              ```
            </CodeGroup>
          </Step>

<Step title="Record for at least 1 minute">
            Capture audio for at least **1 minute** to ensure note generation occurs.
          </Step>

<Step title="End session">
            Stop the recording and trigger note generation:

<CodeGroup>
              ```swift Swift theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
              do {
                  try SukiAmbientCore.shared.end()
              } catch {
                  print("End session failed: \(error)")
              }
              ```
            </CodeGroup>
          </Step>

<Step title="Retrieve generated content">
            Get the generated clinical note and transcript:

<CodeGroup>
              ```swift Swift theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
              // Get the recording ID from the session
              let recordingId = sessionId // Use the session ID as recording ID

// Retrieve content
              SukiAmbientCore.shared.content(for: recordingId) { result in
                  switch result {
                  case .success(let suggestions):
                      print("Generated Note: \(suggestions)")
                  case .failure(let error):
                      print("Failed to retrieve content: \(error)")
                  }
              }

// Retrieve transcript
              SukiAmbientCoreManager.shared.transcript(for: recordingId) { result in
                  switch result {
                  case .success(let response):
                      let transcriptText = (response.finalTranscript ?? []).compactMap { $0.transcript }.joined(separator: " ")
                      print("Transcript: \(transcriptText)")
                  case .failure(let error):
                      print("Failed to retrieve transcript: \(error)")
                  }
              }
              ```
            </CodeGroup>
          </Step>
        </Steps>

<Note>
          For complete mobile SDK capabilities, refer to the [Mobile SDK section](/mobile-sdk/overview) of the documentation.
        </Note>
      </Tab>

<Tab title="Ambient APIs" icon="code">
        <Steps>
          <Step title="Authenticate and get token">
            Get your access token by calling the login endpoint. If you have not registered with Suki, call the [Register](/api-reference/authentication/register) endpoint first to register a new user.

<CodeGroup>
              ```bash cURL theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
              curl -X POST https://sdp.suki-stage.com/api/v1/auth/login \
                -H "Content-Type: application/json" \
                -d '{
                  "partner_id": "your-partner-id",
                  "partner_token": "your-jwt-token",
                  "provider_id": "provider-123"
                }'
              ```
            </CodeGroup>

<Tip>
              Save the `suki_token` from the response. This token is valid for **1 hour** and must be included as `sdp_suki_token` header for all subsequent API calls.
            </Tip>

<Callout icon="code">
              **Important**:

* The production environment is **`https://sdp.suki.ai`** and **`wss://sdp.suki.ai`**.
              * The staging environment is **`https://sdp.suki-stage.com`** and **`wss://sdp.suki-stage.com`**.
              * Your partnership team will confirm which environment, base URL, and credentials apply for your integration.
            </Callout>
          </Step>

<Step title="Create ambient session">
            Start a new ambient session:

<CodeGroup>
              ```bash cURL theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
              curl -X POST https://sdp.suki-stage.com/api/v1/ambient/session/create \
                -H "sdp_suki_token: YOUR_SUKI_TOKEN" \
              -H "sdp_provider_id: <sdp_provider_id>" \
                -H "Content-Type: application/json" \
                -d '{
                  "ambient_session_id": "123dfg-456dfg-789dfg-012dfg",
                  "encounter_id": "123dfg-456dfg-789dfg-012dfg",
                  "multilingual": false
                }'
              ```
            </CodeGroup>

<Tip>
              Save the `ambient_session_id` from the response. You'll need it to stream audio and retrieve content. A successful create returns **201 Created**.
            </Tip>
          </Step>

<Step title="Post session context">
            Before you open the audio WebSocket, seed context for the session (improves note quality). Send <Badge>POST</Badge> to `/api/v1/ambient/session/{ambient_session_id}/context` with a JSON body that matches the [Context API](/api-reference/ambient-sessions/context) schema.

<CodeGroup>
              ```bash cURL theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
              curl -X POST "https://sdp.suki-stage.com/api/v1/ambient/session/YOUR_SESSION_ID/context" \
                -H "sdp_suki_token: YOUR_SUKI_TOKEN" \
              -H "sdp_provider_id: <sdp_provider_id>" \
                -H "Content-Type: application/json" \
                -d '{}'
              ```
            </CodeGroup>

<Note>
              Replace the empty JSON with the fields your integration needs. Opening `/ws/stream` before create and context are complete often causes failures.
            </Note>
          </Step>

<Step title="Stream audio via WebSocket">
            Stream over **WebSocket** (`wss://`, not plain HTTPS). Refer to [Audio streaming API reference](/api-reference/ambient-sessions/audio-stream) for authentication,
            and [Audio streaming guide](/documentation/ambient-audio-streaming) for the **JSON text frame** wire format, and **Python** and **TypeScript** examples.

<Warning>
              **Non-browser clients** must send `sdp_suki_token` and `ambient_session_id` as HTTP headers on the WebSocket **upgrade** request. **Browser clients** must send **`Sec-WebSocket-Protocol`** as a single comma-separated value: `SukiAmbientAuth`, then ambient session ID, then `sdp_suki_token` (see [Audio streaming API reference](/api-reference/ambient-sessions/audio-stream)). Each outbound message is one JSON text frame: **START\_TIME**, then **AUDIO** chunks (Base64 PCM), then an **AUDIO** frame whose `data` is Base64 of bytes **`EOF`** (**`RU9G`**).
            </Warning>
          </Step>

<Step title="End session">
            Signal that the conversation is over to trigger note generation:

<CodeGroup>
              ```bash cURL theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
              curl -X POST "https://sdp.suki-stage.com/api/v1/ambient/session/YOUR_SESSION_ID/end" \
                -H "sdp_suki_token: YOUR_SUKI_TOKEN" \
              -H "sdp_provider_id: <sdp_provider_id>"
              ```
            </CodeGroup>
          </Step>

<Step title="Retrieve generated content">
            After ending the session, wait a few seconds for processing, then fetch the clinical note:

<CodeGroup>
              ```bash cURL theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
              curl -X GET "https://sdp.suki-stage.com/api/v1/ambient/session/YOUR_SESSION_ID/content?cumulative=false" \
                -H "sdp_suki_token: YOUR_SUKI_TOKEN" \
              -H "sdp_provider_id: <sdp_provider_id>"
              ```
            </CodeGroup>
          </Step>
        </Steps>

<Warning>
          **Session Duration Requirement**

Your ambient session must be **at least 1 minute long** for note generation to occur. Sessions shorter than 1 minute receive a `SKIPPED` status, and Suki does not generate a clinical note.

For complete API capabilities, refer to the [API reference](/api-reference/overview) of the documentation.
        </Warning>
      </Tab>
    </Tabs>

## Verify success

After completing your first session, you should see:

<Tabs>
      <Tab title="For Web SDK">
        * The generated clinical note automatically appears in the Suki UI panel
        * Sections are organized according to your LOINC configuration
        * Transcript is available within the UI
      </Tab>

<Tab title="For Mobile SDK">
        * Call `content()` and `transcript()` to retrieve the note and transcript respectively
        * Check the session status to confirm successful completion
        * Access structured sections and conversation transcript programmatically
      </Tab>

<Tab title="For Ambient APIs">
        * <Badge>GET</Badge> request to `/api/v1/ambient/session/{ambient_session_id}/content` returns:
          * `summary` - Array of structured clinical note sections
        * <Badge>GET</Badge> request to `/api/v1/ambient/session/{ambient_session_id}/transcript` returns:
          * `final_transcript` - Complete conversation transcript
        * <Badge>GET</Badge> request to `/api/v1/ambient/session/{ambient_session_id}/status` returns:
          * `status` - Session status (`created`, `ready`, `running`, `aborted`, `skipped`, `failed`, `completed`)
      </Tab>
    </Tabs>

## Step 3: Advanced configuration (optional but recommended)

Configure the generated note in many ways. For example, to generate a customized clinical note, refer to the [LOINC codes](/documentation/note-sections) to define the sections you want to generate.

<CodeGroup>
      ```json Json theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
      {
        "sections": [
          {
            "loinc": "10164-2",
            "title": "History of Present Illness"
          },
          {
            "loinc": "51847-2", 
            "title": "Assessment and Plan"
          }
        ]
      }
      ```
    </CodeGroup>
  </Tab>

<Tab title="Form Filling Workflow" icon="file-lines">
    <CardGroup>
      <Card title="Form Filling APIs" icon="code">
        **Best for:** Custom implementations

REST session lifecycle plus shared Partner WebSocket audio for structured medical forms
      </Card>
    </CardGroup>

<Steps>
      <Step title="Authenticate and get token">
        Get your access token by calling the login endpoint. If you have not registered with Suki, call the [Register](/form-filling-api-reference/authentication/register) endpoint first to register a new user.

<CodeGroup>
          ```bash cURL theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
          curl -X POST https://sdp.suki-stage.com/api/v1/auth/login \
            -H "Content-Type: application/json" \
            -d '{
              "partner_id": "your-partner-id",
              "partner_token": "your-jwt-token",
              "provider_id": "provider-123"
            }'
          ```
        </CodeGroup>

<Tip>
          Save the `suki_token` from the response. This token is valid for **1 hour** and must be included as `sdp_suki_token` header for all subsequent API calls.
        </Tip>
      </Step>

<Step title="Create form-filling session">
        Start a new form-filling session:

<CodeGroup>
          ```bash cURL theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
          curl -X POST https://sdp.suki-stage.com/api/v1/form-filling/session/create \
            -H "sdp_suki_token: YOUR_SUKI_TOKEN" \
          -H "sdp_provider_id: <sdp_provider_id>" \
            -H "Content-Type: application/json" \
            -d '{}'
          ```
        </CodeGroup>

<Note>
          In Form Filling APIs, the session ID field is named **`ambient_session_id`**, but it is **not** the same ID as an Ambient API session. Use only the value returned from **form-filling** `/session/create` for form-filling REST calls and for **`/ws/stream`**.
        </Note>

<Tip>
          Save the **`ambient_session_id`** from the response. You need it for context, streaming, **end**, **status**, and **structured-data** calls. A successful create returns **201 Created**.
        </Tip>
      </Step>

<Step title="Seed context (optional)">
        Provide form template metadata before you stream audio. Send <Badge>POST</Badge> to `/api/v1/form-filling/session/{ambient_session_id}/context` with **`form_filling.values`** entries that include **`form_template_id`** for each template you want to use.

<CodeGroup>
          ```bash cURL theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
          curl -X POST "https://sdp.suki-stage.com/api/v1/form-filling/session/YOUR_SESSION_ID/context" \
            -H "sdp_suki_token: YOUR_SUKI_TOKEN" \
          -H "sdp_provider_id: <sdp_provider_id>" \
            -H "Content-Type: application/json" \
            -d '{
              "form_filling": {
                "values": [
                  { "form_template_id": "YOUR_FORM_TEMPLATE_UUID" }
                ]
              }
            }'
          ```
        </CodeGroup>

<Note>
          The request body is optional. You can skip this step and continue to audio capture. To list available templates, see [Suki medical form templates](/form-filling-api-reference/info/suki-medical-form-templates).
        </Note>
      </Step>

<Step title="Stream audio via WebSocket">
        Stream over **WebSocket** (`wss://`, not plain HTTPS). Use your **form-filling** **`ambient_session_id`** and **`sdp_suki_token`**. Refer to [Audio streaming API reference](/api-reference/ambient-sessions/audio-stream) and [Ambient audio streaming](/documentation/ambient-audio-streaming) for authentication, the **JSON text frame** wire format, and client examples.

<Warning>
          **Non-browser clients** must send `sdp_suki_token` and `ambient_session_id` as HTTP headers on the WebSocket **upgrade** request. **Browser clients** must send **`Sec-WebSocket-Protocol`** as a single comma-separated value: `SukiAmbientAuth`, then ambient session ID, then `sdp_suki_token` (see [Audio streaming API reference](/api-reference/ambient-sessions/audio-stream)). Each outbound message is one JSON text frame: **START\_TIME**, then **AUDIO** chunks (Base64 PCM), then an **AUDIO** frame whose `data` is Base64 of bytes **`EOF`** (**`RU9G`**).
        </Warning>
      </Step>

<Step title="End session">
        Signal that the visit is over and processing can begin:

<Step title="Retrieve structured data">
        After ending the session, poll status until processing completes, then fetch structured form output. You can also use a **webhook** when processing finishes (see [Webhook notifications](/api-reference/asynchronous/webhook)).

<CodeGroup>
          ```bash cURL theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
          # Check status
          curl -X GET "https://sdp.suki-stage.com/api/v1/form-filling/session/YOUR_SESSION_ID/status" \
            -H "sdp_suki_token: YOUR_SUKI_TOKEN" \
          -H "sdp_provider_id: <sdp_provider_id>"
          # Get structured data
          curl -X GET "https://sdp.suki-stage.com/api/v1/form-filling/session/YOUR_SESSION_ID/structured-data" \
            -H "sdp_suki_token: YOUR_SUKI_TOKEN" \
          -H "sdp_provider_id: <sdp_provider_id>"
          ```
        </CodeGroup>
      </Step>
    </Steps>

<Note>
      For complete Form Filling API capabilities, refer to the [Form Filling API overview](/form-filling-api-reference/overview) and [Form Filling quickstart](/form-filling-api-reference/quickstart).
    </Note>

## Verify success

After completing your first form-filling session, you should see:

* <Badge>GET</Badge> request to `/api/v1/form-filling/session/{ambient_session_id}/status` returns a terminal status when processing is done
    * <Badge>GET</Badge> request to `/api/v1/form-filling/session/{ambient_session_id}/structured-data` returns:
      * **`generated_values`** and **`non_generated_values`** for the session
    * Structured fields map to the templates you supplied in context (when provided)

## Next steps (form filling)

<Icon icon="file-lines" /> Refer to the [Form filling overview](/documentation/form-filling) to learn how form-filling workflows fit your product.

<Icon icon="file-lines" /> Refer to the [Form Filling API quickstart](/form-filling-api-reference/quickstart) for the full step-by-step API walkthrough.

<Icon icon="file-lines" /> Refer to the [Form filling integration decision guide](/documentation/form-filling-integration-decision-guide) to compare integration options.
  </Tab>
</Tabs>

## Success checklist

Before moving to production, ensure you have successfully completed these steps:

<AccordionGroup>
  <Accordion title="Authentication Works" icon="check">
    * Successfully call the `/api/v1/auth/login` endpoint
    * You receive a valid `suki_token` in the response
    * Your JWT token is properly formatted and not expired
    * Your JWKS endpoint is publicly accessible
  </Accordion>

<Accordion title="Session Creation Works" icon="check">
    * Create an ambient session with patient information
    * You receive an `ambient_session_id` in the response
    * The session status is valid (not `FAILED`)
  </Accordion>

<Accordion title="Audio streaming works" icon="check">
    * WebSocket connection establishes successfully
    * Audio chunks are being sent to Suki
    * No connection errors or timeouts occur
    * Session duration is at least 1 minute
  </Accordion>

<Accordion title="Content Retrieval Works" icon="check">
    * Fetch session content using the `ambient_session_id`
    * Response includes structured `summary` array with clinical content
    * Response includes a complete `transcript` of the conversation
    * Session status shows `COMPLETED` (not `SKIPPED` or `FAILED`)
  </Accordion>

<Accordion title="Integration Quality" icon="check">
    * Generated notes are accurate and clinically relevant
    * Transcript content is accurate and complete
    * LOINC sections match your requested configuration
    * Error handling is implemented for all API calls
  </Accordion>
</AccordionGroup>

## Troubleshooting

<Tabs>
  <Tab title="Common issues">
    <AccordionGroup>
      <Accordion title="Authentication Failed - 401 Unauthorized">
        **Problem:** Login request returns 401 Unauthorized error

**Solution:**

* Verify your `partner_id` matches the one provided by Suki
        * Ensure your JWT token (`partner_token`) is valid and not expired
        * Check that your JWT token includes the correct user identifier field
        * Verify your JWKS endpoint is publicly accessible and returning valid keys
        * Confirm your public key matches what was registered with Suki
      </Accordion>

<Accordion title="Session Creation Failed">
        **Problem:** Cannot create ambient session or receive error response

**Solution:**

* Confirm you have a valid `suki_token` from the login endpoint
        * Use `sdp_suki_token` header (not `Authorization: Bearer`) for all API calls
        * Verify `ambient_session_id` and `encounter_id` are **at most 36 characters** (<Tooltip href="/Glossary/v#varchar-36">varchar(36)</Tooltip>) when you set them, where applicable.
        * Check that `multilingual` is a boolean value (true/false)
        * Verify your partner account has the necessary permissions for ambient sessions
      </Accordion>

<Accordion title="WebSocket Connection Failed">
        **Problem:** WebSocket connection fails or immediately disconnects

**Solution:**

* Verify you're using the correct WebSocket URL: `wss://sdp.suki-stage.com/ws/stream`
        * For browser clients, ensure you're using `Sec-WebSocket-Protocol` header with format: `SukiAmbientAuth,<ambient_session_id>,<sdp_suki_token>`
        * For non-browser clients, include both `sdp_suki_token` and `ambient_session_id` as separate headers in the WebSocket upgrade request
        * Check network connectivity and firewall settings allow WebSocket connections
        * Ensure your `suki_token` hasn't expired (valid for 1 hour)
      </Accordion>

<Accordion title="Session status shows SKIPPED">
        **Problem:** Session completes but status is `SKIPPED` and no note is generated

**Solution:**

* Ensure your session duration is at least **1 minute long**
        * Verify audio is being properly captured and streamed
        * Check that audio chunks contain actual speech (not silence)
        * Confirm WebSocket connection remained stable throughout the session

<Note>
          A `SKIPPED` status is expected for sessions shorter than 1 minute or with no audible speech. This is not a system error.
        </Note>
      </Accordion>

<Accordion title="Audio Not Processing">
        **Problem:** Audio streams but transcript is empty or note not generated

**Solution:**

* Verify audio format is correct (PCM, 16-bit, 16kHz mono recommended)
        * Ensure audio chunks are the correct size (100ms chunks recommended)
        * Check that you end the stream with an **AUDIO** message whose `data` is Base64 of bytes **`EOF`** (value **`RU9G`**), then close the WebSocket and call the session **end** REST endpoint
        * Verify microphone permissions are granted in your application
        * Test with a known working audio sample first
      </Accordion>

<Accordion title="Content Retrieval Returns Empty or Incomplete Data">
        **Problem:** Session completes but content endpoint returns no data or incomplete note

**Solution:**

* Wait at least 5-10 seconds after ending the session before retrieving content
        * Check the session `status` - it should be `COMPLETED`, not `PROCESSING`
        * Verify you're using the correct `ambient_session_id` in the URL path
        * Use `sdp_suki_token` header (not `Authorization: Bearer`)
        * Ensure your `suki_token` is still valid (valid for 1 hour)
        * Check if session was `SKIPPED` due to short duration (less than 1 minute)
        * Verify you called the `/end` endpoint to trigger note generation
      </Accordion>
    </AccordionGroup>
  </Tab>

<Tab title="Getting help">
    * Technical Issues: Review our <a href="/documentation/faqs/general">FAQs</a>

* Integration Support: Contact our
      <a href="https://forms.suki.ai/SukiSupport/form/SukiSDKSupport/formperma/T3z7hYJ7Ph-J7JrWSN08QJn32BYjarkxqm8Lm8XFPow">Support team</a>

* Partnership Questions: Reach out to our
      <a href="https://www.suki.ai/suki-partners/">Partnership team</a>
  </Tab>
</Tabs>

## Next steps

<Icon icon="file-lines" /> Refer to the [Ambient Documentation Guide](/documentation/ambient-documentation) to learn more about how ambient documentation works.

<Icon icon="file-lines" /> Refer to the [Authentication Setup](/documentation/partner-authentication) to understand how to authenticate your application with Suki.

<Icon icon="file-lines" /> Refer to the [Note Sections](/documentation/note-sections) to customize the clinical note structure and LOINC codes.

<Icon icon="file-lines" /> Refer to the [API Reference](/api-reference/overview) to explore detailed API specifications.

# Home Page
Source: https://developer.suki.ai/documentation/home

Suki Developer Documentation

<div>
        <div>
          <div>
            <h1>
              <span>Start building</span>

<br />

<span>with Suki for Partners</span>
            </h1>

<p>
              <strong>Welcome to Suki developer documentation.</strong>
            </p>

<p>
              Find docs and resources to integrate Suki's APIs and SDKs into your product. Go from zero to production-ready integrations in days, not months.
            </p>

Start Building
                </a>

<a href="/documentation/use-case">
                  Explore Use Cases

<div>
            <div aria-label="Recently viewed documentation">
              <p>Recently viewed</p>

<ul />

<ul aria-label="Suggested pages">
                <li>
                  <a href="/documentation/getting-started">
                    Getting started guide
                  </a>
                </li>

<li>
                  <a href="/api-reference/overview">
                    Ambient API overview
                  </a>
                </li>

<li>
                  <a href="/documentation/learning-path">
                    Developer journey
                  </a>
                </li>
              </ul>

<p>
                Need access?

<a href="/documentation/partner-onboarding">
                  Get onboarded
                </a>

<a href="https://www.suki.ai/contact-us" aria-label="Get in touch with Suki. Opens suki.ai in a new tab.">
                  Get in touch
                </a>

.
              </p>
            </div>
          </div>
        </div>
      </div>
    </div>
  </div>

<section>
    <div>
      <p>What are you building?</p>

<h2>
        Pick your workflow
      </h2>

<p>
        Start with the workflow that matches your use case and choose the integration path that fits your technical approach.
      </p>
    </div>

<div>
      <article>
        <h3>Form filling</h3>

<ul>
          <li>
            <a href="/documentation/form-filling">Form filling overview</a>
          </li>

<li>
            <a href="/documentation/form-filling-integration-decision-guide">Form filling integration guide</a>
          </li>

<li>
            <a href="/form-filling-api-reference/overview">Form filling API reference</a>
          </li>
        </ul>
      </article>

<article>
        <h3>Ambient clinical intelligence</h3>

<ul>
          <li>
            <a href="/documentation/ambient-documentation">Ambient documentation</a>
          </li>

<li>
            <a href="/documentation/integration-decision-guide">Ambient integration guide</a>
          </li>

<li>
            <a href="/api-reference/overview">Ambient API reference</a>
          </li>
        </ul>
      </article>

<article>
        <h3>Dictation</h3>

<ul>
          <li>
            <a href="/documentation/dictation">Dictation overview</a>
          </li>

<li>
            <a href="/dictation-sdk/introduction">Dictation SDK</a>
          </li>

<li>
            <a href="/dictation-sdk/quickstart">Dictation quickstart</a>
          </li>
        </ul>
      </article>
    </div>
  </section>

<span>Form Filling</span>
          </button>

<span>Ambient</span>
          </button>

<span>Dictation</span>
          </button>
        </div>

REST
                </span>
              </div>

<p>Form Filling APIs allow you to create, update, and retrieve form filling sessions.</p>

```bash theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
              curl --request GET \
                --url https://sdp.suki-stage.com/api/v1/form-filling/session/{form-filling-session_id}/status \
                --header 'sdp_suki_token: <sdp_suki_token>' \
                --header 'sdp_provider_id: <sdp_provider_id>'
              ```

<a href="/form-filling-api-reference/overview">View API Reference →</a>
            </Tab>
          </Tabs>
        </div>

REST
                </span>

WebSocket
                </span>

Webhooks
                </span>
              </div>

<p>Ambient APIs allow you to create, update, and retrieve ambient sessions.</p>

<a href="/api-reference/overview">View API Reference →</a>
            </Tab>

iOS
                </span>

Swift
                </span>
              </div>

<p>Mobile SDK allows you to create, update, and retrieve ambient sessions on iOS devices.</p>

```swift theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
              // Add SukiAmbientCore.framework to your Xcode project
              import SukiAmbientCore.framework
              ```

<a href="/mobile-sdk/overview">View Mobile SDK Docs →</a>
            </Tab>

React
                </span>

JavaScript
                </span>
              </div>

<p>Web SDK allows you to create, update, and retrieve ambient sessions with the pre-built UI components.</p>

```bash theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
              npm install @suki-sdk/react
              ```

React
                </span>

Headless
                </span>
              </div>

<p>Headless Web SDK allows you to create, update, and retrieve ambient sessions in the browser without the pre-built UI.</p>

```bash theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
              npm install @suki-sdk/platform-react
              ```

<a href="/headless-web-sdk/introduction">View Headless SDK Docs →</a>
            </Tab>
          </Tabs>
        </div>

REST
                </span>

WebSocket
                </span>
              </div>

<p>Dictation APIs allow you to create, stream audio, and receive live transcripts from audio dictation sessions.</p>

```bash theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
              curl --request POST \
                --url https://sdp.suki-stage.com/api/v1/transcription/session/create \
                --header 'sdp_suki_token: <sdp_suki_token>' \
                --header 'sdp_provider_id: <sdp_provider_id>'
              ```

<a href="/api-reference/ambient-dictation">View API Reference →</a>
            </Tab>

Beta
                </span>

React
                </span>

JavaScript
                </span>
              </div>

<p>Dictation SDK allows you to embed dictation in the browser with a hosted iframe or React components.</p>

```bash theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
              npm install @suki-sdk/dictation-react
              ```

<a href="/dictation-sdk/introduction">View Dictation SDK Docs →</a>
            </Tab>
          </Tabs>
        </div>
      </div>
    </div>

<span>TypeScript</span>
              </button>

<span>Python</span>
              </button>

<div>
              <div>
                ```typescript theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
                const sessionId = '{ambient_session_id}';
                const res = await fetch(
                  `https://sdp.suki-stage.com/api/v1/ambient/session/${sessionId}/status`,
                  { headers: { sdp_suki_token: '<sdp_suki_token>', sdp_provider_id: '<sdp_provider_id>' } }
                );
                console.log(res.status, await res.json());
                ```
              </div>

<div>
                ```python theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
                import requests

session_id = "{ambient_session_id}"
                url = f"https://sdp.suki-stage.com/api/v1/ambient/session/{session_id}/status"
                headers = {"sdp_suki_token": "<sdp_suki_token>", "sdp_provider_id": "<sdp_provider_id>"}
                r = requests.get(url, headers=headers)
                print(r.status_code, r.json())
                ```
              </div>

<div>
                ```go theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
                package main

import (
                	"fmt"
                	"io"
                	"net/http"
                )

func main() {
                	url := "https://sdp.suki-stage.com/api/v1/ambient/session/{ambient_session_id}/status"
                	req, _ := http.NewRequest(http.MethodGet, url, nil)
                	req.Header.Set("sdp_suki_token", "<sdp_suki_token>")
                	req.Header.Set("sdp_provider_id", "<sdp_provider_id>")
                	res, _ := http.DefaultClient.Do(req)
                	defer res.Body.Close()
                	b, _ := io.ReadAll(res.Body)
                	fmt.Println(res.StatusCode, string(b))
                }
                ```
              </div>

<div>
                ```ruby theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
                require "net/http"

uri = URI("https://sdp.suki-stage.com/api/v1/ambient/session/{ambient_session_id}/status")
                req = Net::HTTP::Get.new(uri)
                req["sdp_suki_token"] = "<sdp_suki_token>"
                req["sdp_provider_id"] = "<sdp_provider_id>"
                res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |h| h.request(req) }
                puts res.code
                puts res.body
                ```
              </div>

<div>
                ```bash theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
                curl --request GET \
                  --url https://sdp.suki-stage.com/api/v1/ambient/session/{ambient_session_id}/status \
                  --header 'sdp_suki_token: <sdp_suki_token>' \
                  --header 'sdp_provider_id: <sdp_provider_id>'
                ```
              </div>
            </div>
          </div>
        </div>

<div>
    <div>
      <p>Explore the popular docs</p>

<h2>
        Start here
      </h2>

<p>
        Learn how Suki for Partners fits into your product. Explore guides on common use cases, integration paths, and go live faster.
      </p>
    </div>

New to Suki for Partners?
          </p>

<p>
            Understand the product, value, and integration approach before you start building.
          </p>
        </div>

<a href="/documentation/executive-summary" aria-label="Open executive summary for business leaders">
          Executive Summary

<div>
      <div>
        <div>
          <p>Latest releases</p>

<p>
            Explore new APIs, SDKs, and features recently added to Suki for Partners.
          </p>
        </div>
      </div>

<span>
              <span>Audio Dictation APIs</span>
              <span>Dictation APIs to transcribe audio in real-time</span>
            </span>

<span>
              <span>Headless Web SDK</span>
              <span>New beta headless SDK for building custom ambient integrations with full UI control</span>
            </span>

<span>
              <span>Dictation SDK</span>
              <span>New beta dictation SDK for embedding clinical dictation in the browser</span>
            </span>

<span>
              <span>Form Filling APIs</span>
              <span>New form filling APIs for creating form filling sessions and retrieving structured field data</span>
            </span>

<a href="/updates/release-notes">View Release Notes →</a>
      </div>
    </div>
  </div>
</div>

# Ambient Workflows - Integration Decision Guide
Source: https://developer.suki.ai/documentation/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, please refer to the [Form filling integration decision guide](/documentation/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>
  <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>
  <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>
  <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>
  <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

The Dictation SDK embeds hosted dictation in your web application via iframe and JavaScript or React packages.

<CardGroup>
  <Card title="Recommended for:" icon="microphone">
    • Web applications that need dictation\
    • Frontend systems that need dictation
  </Card>

<Card title="What's provided:" icon="gear">
    • Hosted iframe for dictation\
    • In-field and scratchpad modes\
    • JavaScript and React packages
  </Card>
</CardGroup>

## How to choose

<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

**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 Direct 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
      </Accordion>

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

* **Choose Mobile SDK** - provides native iOS functionality and device integration

**For Android Applications:**

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

<Accordion title="Backend System or Server Integration">
        **Choose Direct APIs**

* This is your only option for server-to-server integrations
        * Provides complete control over data processing and system integration
      </Accordion>
    </AccordionGroup>
  </Tab>

<Tab title="By Team Skills">
    <CardGroup>
      <Card title="Frontend/React Experience">
        **Recommended: Web SDK or Headless Web SDK**

Use **Web SDK** for pre-built UI and speed. Use **Headless Web SDK** when you will build custom UI in React with hooks.
      </Card>

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

Full control and leverages existing API development skills
      </Card>

<Card title="iOS/Swift Experience">
        **Recommended: Mobile SDK**

Native iOS functionality with SDK support and familiar development patterns
      </Card>

<Card title="Limited Development Resources">
        **Recommended: Web SDK**

Requires minimal custom UI work with ready-to-use components
      </Card>
    </CardGroup>
  </Tab>

<Tab title="By Requirements">
    | Your Need                                    | Recommended Choice | Why                                                        |
    | -------------------------------------------- | ------------------ | ---------------------------------------------------------- |
    | **Quick integration in the browser**         | Web SDK            | Ready-to-use components, minimal setup                     |
    | **Custom web UI in React**                   | Headless Web SDK   | Hooks for platform behavior; you own layout and components |
    | **Custom UI/UX without React on the web**    | Direct APIs        | Use your stack and patterns against the API                |
    | **Native mobile features (iOS)**             | 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 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>

## 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/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 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>
    </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>
    </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**

## Next steps

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

<CardGroup>
  <Card title="Web SDK Quickstart" href="/web-sdk/quickstart" icon="list">
    Get started with pre-built components and fast integration
  </Card>

<Card title="Headless Web SDK Quickstart" href="/headless-web-sdk/quickstart" icon="list">
    React hooks, custom UI, and ambient sessions in your application
  </Card>

<Card title="API Overview" href="/api-reference/overview" icon="list">
    Build custom integrations with maximum flexibility
  </Card>

<Card title="Mobile SDK Overview" href="/mobile-sdk/overview" icon="list">
    Native iOS integration for mobile applications
  </Card>

<Card title="Dictation SDK Overview" href="/dictation-sdk/introduction" icon="list">
    Hosted dictation in your web application
  </Card>

<Card title="Partner Onboarding" href="/documentation/partner-onboarding" icon="list">
    Start your integration journey with Suki
  </Card>
</CardGroup>

## 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, please prepare:**

* Description of your healthcare application and clinical workflows
* Target platform (web with React or not, iOS, Android, backend system)
* Development timeline and resource constraints
* Specific technical requirements or compliance needs

**Contact options:**

# Developer Learning Path
Source: https://developer.suki.ai/documentation/learning-path

Step-by-step guided journey to integrate Suki using ambient or form filling workflows with the Web SDK, Headless Web SDK, Mobile SDK, or REST APIs

## Your journey to Suki integration

Follow this structured path to successfully integrate Suki's AI-powered healthcare capabilities. Each step builds on the previous one, ensuring you have a solid foundation before moving forward.

<Note>
  **Estimated Total Time**: 4-6 weeks from start to production deployment
</Note>

## Foundation setup

### Step 1: Partner onboarding

**Goal**: Get registered with Suki and receive your <Tooltip href="/Glossary/p">Partner ID</Tooltip>

<Card>
  <CardGroup>
    <Card title="What You'll Do" icon="clipboard-check">
      * Contact Suki partnership team
      * Provide business information and authentication method
      * Receive your unique `partner_id`
    </Card>
  </CardGroup>

**Prerequisites**: Business information, chosen authentication method

**Time**: 3-5 business days

**Next Step**: Once you have your `partner_id`, move to Step 2

<div>
    <a href="/documentation/partner-onboarding">Start Partner Onboarding</a>
  </div>
</Card>

### Step 2: Authentication setup

**Goal**: Configure secure authentication between your system and Suki

<Card>
  <CardGroup>
    <Card title="What You'll Do" icon="key">
      * Choose authentication method (<Tooltip href="/Glossary/j">JWKS</Tooltip>, Okta, JWT Assertion)
      * Set up your identity provider integration
      * Test token generation and validation
    </Card>
  </CardGroup>

**Prerequisites**: <Tooltip href="/Glossary/p">Partner ID</Tooltip> from Step 1, access to your identity provider

**Time**: 2-3 days

**Next Step**: With authentication working, choose your integration path

<div>
    <a href="/documentation/partner-authentication">Setup Authentication</a>
  </div>
</Card>

***

### Step 3: Choose your integration path

Depending on the workflow you choose, you will need to choose the best integration method for your application.

Refer to the [Workflows overview](/documentation/workflows) for more information about the different workflows and how to choose the best integration method for your application.

<Tabs>
  <Tab title="Ambient Workflows">
    ### Integration choice

**Goal**: Select the best integration method for your application

<Card>
      <CardGroup>
        <Card title="Web SDK" icon="globe" href="/documentation/learning-path#web-sdk-path">
          **Best for**: React/JavaScript web apps that want Suki UI

* Pre-built clinical UI components
          * Automatic state management
          * Fastest browser implementation
        </Card>

<Card title="Headless Web SDK" icon="react" href="/documentation/learning-path#headless-web-sdk-path">
          **Best for**: React 18+ web apps with a custom UI

* Hooks for auth, sessions, and recording
          * You build all interface and layout
          * Same core ambient behavior as the Web SDK
        </Card>

<Card title="Mobile SDK" icon="mobile" href="/documentation/learning-path#mobile-sdk-path">
          **Best for**: Native iOS applications

* Optimized for mobile audio
          * Native performance
          * Offline capabilities
        </Card>

<Card title="Direct APIs" icon="code" href="/documentation/learning-path#api-path">
          **Best for**: Custom implementations on any stack

* Maximum flexibility
          * Any programming language
          * Full control at the API/WebSocket level
        </Card>
      </CardGroup>

**Time**: 1-2 hours to evaluate options

<div>
        <a href="/documentation/integration-decision-guide">Decision Guide</a>
      </div>
    </Card>

### Integration implementation

<Tabs>
      <Tab title="Web SDK path">
        **Goal**: Install and configure the Suki Web SDK

<Steps>
          <Step title="Install package (15 min)">
            Install `@suki-sdk/core` plus `@suki-sdk/react` for React or `@suki-sdk/js` for plain JavaScript

```bash theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
            npm install @suki-sdk/react @suki-sdk/core
            ```

**Next**: Initialize auth and the SDK client (see quickstart for your stack)
          </Step>

<Step title="Basic configuration (30 min)">
            Create `SukiAuthManager` from `@suki-sdk/core` with your `partnerId`, `partnerToken`, and provider fields. In React, wrap with `SukiProvider` and call `init({ authManager })` from `useSuki()` in a child (once, usually from `useEffect`). In JavaScript, call `initialize({ authManager })` from `@suki-sdk/js`.

```jsx theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
            import { SukiProvider } from '@suki-sdk/react';

function App() {
              return (
                <SukiProvider>
                  {/* init({ authManager }) from useSuki() in a child */}
                </SukiProvider>
              );
            }
            ```

**Next**: Mount the UI and start an ambient session
          </Step>

<Step title="First ambient session (45 min)">
            Mount the SDK UI with an `encounter` and walk through recording and note generation

**What you'll build**: A simple flow that starts ambient documentation, captures audio, and returns a clinical note

**Next**: Test with sample audio and verify note generation
          </Step>
        </Steps>

[Web SDK quickstart →](/web-sdk/quickstart)
      </Tab>

<Tab title="Headless Web SDK path">
        **Goal**: Install the Headless Web SDK and wire authentication and ambient hooks in React

<Steps>
          <Step title="Install package (15 min)">
            Install the Headless Web SDK in a **React 18+** project

```bash theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
            npm install @suki-sdk/platform-react
            ```

Confirm your test and production **host URLs** are on the Suki allowlist (see [Headless Web SDK prerequisites](/headless-web-sdk/prerequisites)).

**Next**: Add `PlatformClient` and `PlatformClientProvider`
          </Step>

<Step title="Platform client and provider (20 min)">
            Create a `PlatformClient` and wrap your app with `PlatformClientProvider` (see [Platform client and provider](/headless-web-sdk/api-reference/platform-client) and [Quickstart](/headless-web-sdk/quickstart))

```jsx theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
            import { PlatformClient, PlatformClientProvider } from '@suki-sdk/platform-react';

const client = new PlatformClient({ env: 'staging', enableDebug: true, logLevel: 'error' });

function App() {
              return (
                <PlatformClientProvider>
                  <YourApp />
                </PlatformClientProvider>
              );
            }
            ```

**Next**: Authenticate with `useAuth` inside the provider tree
          </Step>

<Step title="Authentication hooks (45 min)">
            Add the `useAuth` hook under the provider with your `partnerId` and `partnerToken` (see the [Authentication hook](/headless-web-sdk/guides/hooks/auth-hook) guide)

```jsx theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
            import { useAuth } from '@suki-sdk/platform-react';

function YourApp() {
              const { isLoggedIn, isPending, error, login } = useAuth({
                partnerId: 'your-partner-id',
                partnerToken: 'your-partner-token',
                // See Authentication hook guide for full options
              });
              // Render your own sign-in UI and loading states
            }
            ```

**Next**: Create an ambient session with `useAmbient`
          </Step>

<Step title="Session and recording (60 to 90 min)">
            Create a session with `useAmbient`, then use `useAmbientSession` for recording lifecycle and status

**What you'll build**: Your own controls and layout (start, pause, submit) backed by hook state, plus retrieval of note content when processing completes

**Next**: Follow the quickstart through your first end-to-end recording, then harden error handling

For step-by-step code, use the quickstart and [Authentication hook](/headless-web-sdk/guides/hooks/auth-hook), [Ambient hook](/headless-web-sdk/guides/hooks/ambient-hook), and [Ambient session hook](/headless-web-sdk/guides/hooks/ambient-session-hook) guides.
          </Step>
        </Steps>

[Headless Web SDK quickstart →](/headless-web-sdk/quickstart)
      </Tab>

<Tab title="Mobile SDK path">
        **Goal**: Install and configure the Suki Mobile SDK

<Steps>
          <Step title="Install framework (20 min)">
            Add the Suki Mobile SDK to your iOS project

**Methods**: SPM, CocoaPods, or manual installation

**Next**: Configure permissions and capabilities
          </Step>

<Step title="Basic configuration (45 min)">
            Initialize the SDK and set up basic configuration

```swift theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
            import SukiSDK

SukiSDK.configure(
                partnerId: "your-partner-id",
                environment: .staging
            )
            ```

**Next**: Implement session management
          </Step>

<Step title="First ambient session (60 min)">
            Create a basic ambient session with recording capabilities

**What you'll build**: A view controller that can create sessions, record audio, and retrieve generated notes

**Next**: Test with device microphone and verify functionality
          </Step>
        </Steps>

[Mobile SDK installation →](/mobile-sdk/installation)
      </Tab>

<Tab title="REST APIs path">
        **Goal**: Implement Suki's APIs directly in your application

<Steps>
          <Step title="Authentication implementation (60 min)">
            Implement the authentication flow to get Suki tokens

**Key endpoints**: `/auth/register`, `/auth/login`

**Next**: Test token generation and validation
          </Step>

<Step title="Session management (90 min)">
            Implement ambient session creation and management

**Key endpoints**:

* <Badge>POST</Badge> `/ambient-sessions` - Create session
            * <Badge>POST</Badge> `/ambient-sessions/{id}/context` - Set context
            * <Badge>GET</Badge> `WebSocket` - Audio streaming

**Next**: Implement audio streaming
          </Step>

<Step title="Content retrieval (45 min)">
            Implement note generation monitoring and content retrieval

**Key endpoints**:

* <Badge>GET</Badge> `/ambient-content/{id}/status` - Check status
            * <Badge>GET</Badge> `/ambient-content/{id}/content` - Get generated note

**Next**: Test end-to-end workflow
          </Step>
        </Steps>

[API overview →](/api-reference/overview)
      </Tab>
    </Tabs>
  </Tab>

<Tab title="Form Filling Workflows">
    ### Integration choice

**Goal**: Select the best integration method for form filling in your application

<Card>
      <CardGroup>
        <Card title="Form Filling APIs" icon="code" href="/documentation/learning-path#form-filling-api-path">
          **Best for**: Custom web, mobile, or backend integrations

* REST session lifecycle and structured form output
          * Shared Partner WebSocket for visit audio
          * You build template selection, capture, and review UI
        </Card>
      </CardGroup>

**Prerequisites**: <Tooltip href="/Glossary/p">Partner ID</Tooltip> and working authentication from Foundation setup (Steps 1–2)

**Time**: 1-2 hours to evaluate options and read the decision guide

<div>
        <a href="/documentation/form-filling-integration-decision-guide">Form Filling Decision Guide</a>
      </div>
    </Card>

### Integration implementation

<Tabs>
      <Tab title="Form Filling APIs path">
        **Goal**: Implement Form Filling REST APIs and the shared Partner WebSocket in your application

<Steps>
          <Step title="Authentication implementation (60 min)">
            Implement the authentication flow to get Suki tokens for Form Filling REST calls

**Key endpoints**: `/api/v1/auth/register`, `/api/v1/auth/login`

**Next**: Test token generation and call form-filling session APIs with `sdp_suki_token`
          </Step>

<Step title="Session and context (75 min)">
            Create a form-filling session and optionally seed template context before audio capture

**Key endpoints**:

* <Badge>POST</Badge> `/api/v1/form-filling/session/create` — Create session
            * <Badge>POST</Badge> `/api/v1/form-filling/session/{ambient_session_id}/context` — Bind `form_template_id` values

<Note>
              The session ID field is named **`ambient_session_id`**, but it is **not** the same ID as an Ambient API session. Use only the value returned from **form-filling** `/session/create` for form-filling REST and for **`/ws/stream`**.
            </Note>

**Next**: List templates if needed, then open the audio WebSocket
          </Step>

<Step title="Audio streaming (90 min)">
            Stream visit audio on the Partner WebSocket using your form-filling session ID

**Connection**: `wss://` to `GET /ws/stream` (same wire format as Ambient; see [Ambient audio streaming](/documentation/ambient-audio-streaming))

**Sequence**: **START\_TIME**, **AUDIO** chunks (Base64 PCM), **AUDIO** with **`EOF`** (`RU9G`), close the WebSocket, then call session **end** on REST

**Next**: Poll status or configure a webhook for completion
          </Step>

<Step title="Structured output (45 min)">
            End the session, monitor processing, and retrieve populated form fields

**Key endpoints**:

* <Badge>POST</Badge> `/api/v1/form-filling/session/{ambient_session_id}/end` — End session
            * <Badge>GET</Badge> `/api/v1/form-filling/session/{ambient_session_id}/status` — Check status
            * <Badge>GET</Badge> `/api/v1/form-filling/session/{ambient_session_id}/structured-data` — Get **generated\_values** and **non\_generated\_values**

**Optional**: [Webhook notifications](/api-reference/asynchronous/webhook) when processing finishes

**What you'll build**: An end-to-end flow from login through structured form output in your UI or downstream systems

**Next**: Test in-person and virtual scenarios, then harden error handling
          </Step>
        </Steps>

[Form Filling API quickstart →](/form-filling-api-reference/quickstart)
      </Tab>
    </Tabs>
  </Tab>
</Tabs>

***

## Advanced features

*Estimated Time: 1-2 weeks*

### Step 5: Add advanced capabilities

**Goal**: Enhance your integration with Suki's advanced features

<CardGroup>
  <Card title="Multilingual Support" icon="language" href="/api-reference/capabilities/multilingual">
    **Time**: 2-3 hours

Enable support for 80+ languages with automatic English note generation

**Key Features**:

* Automatic language detection
    * Multi-language conversations
    * English output standardization
  </Card>

<Card title="Problem-Based Charting" icon="heart-pulse" href="/api-reference/capabilities/problem-based-charting">
    **Time**: 4-6 hours

Implement diagnosis-focused documentation structure

**Key Features**:

* Problem-oriented notes
    * Diagnosis tracking
    * Enhanced clinical workflows
  </Card>

<Card title="Custom Note Sections" icon="file-text" href="/documentation/note-sections">
    **Time**: 2-4 hours

Configure custom clinical note sections using LOINC codes

**Key Features**:

* 26+ standard sections
    * Custom section ordering
    * EHR integration ready
  </Card>

<Card title="User Preferences" icon="user" href="/api-reference/user-preferences/preferences">
    **Time**: 3-5 hours

Allow providers to customize their documentation preferences

**Key Features**:

* Personal note styling
    * Section preferences
    * Workflow customization
  </Card>
</CardGroup>

***

## Production readiness

*Estimated Time: 1 week*

### Step 6: Testing & optimization

**Goal**: Ensure your integration is production-ready

<Card>
  <CardGroup>
    <Card title="What you will do" icon="flask">
      * Comprehensive testing with real clinical scenarios
      * Performance optimization and error handling
      * Security review and compliance verification
      * User acceptance testing with healthcare providers
    </Card>
  </CardGroup>

**Key areas**:

* Audio quality and streaming reliability
  * Note generation accuracy and speed
  * Error handling and recovery
  * HIPAA compliance verification

**Time**: 3-5 days
</Card>

### Step 7: Go live

**Goal**: Deploy your Suki-powered application to production

<Card>
  <CardGroup>
    <Card title="Production deployment" icon="rocket">
      * Switch to production environment
      * Monitor initial usage and performance
      * Gather user feedback and iterate
      * Scale based on usage patterns
    </Card>
  </CardGroup>

**Support resources**:

* 24/7 technical support during launch
  * Performance monitoring and alerts
  * Regular check-ins with Suki team

<div>
    <a href="/documentation/support">Get Support</a>
  </div>
</Card>

## Next steps

<Icon icon="file-lines" /> If you have all the required information and `partner_id`, start with the [Getting started guide](/documentation/getting-started) to get oriented.

<Icon icon="file-lines" /> For **ambient** workflows, open the quickstart or overview for your path: [Web SDK](/web-sdk/quickstart), [Headless Web SDK](/headless-web-sdk/quickstart), [Mobile SDK](/mobile-sdk/overview), or [Ambient API overview](/api-reference/overview).

<Icon icon="file-lines" /> For **form filling** workflows, use the [Form Filling API quickstart](/form-filling-api-reference/quickstart) and [Form filling overview](/documentation/form-filling).

# Documentation MCP Integration
Source: https://developer.suki.ai/documentation/mcp

Connect Suki developer documentation as an MCP server in your AI code editor to search guides, API reference, and SDK docs while you integrate

The Suki developer documentation is available as an **MCP server** (Model Context Protocol). Connect it to your AI code editor (**Cursor**, **VS Code**, **Claude**) while you work in your local development environment.

This connection lets the LLM in your editor search the Suki knowledge base to find code samples, API references, and guides.

For the contextual menu, copy options, and one-click AI integrations on every page, refer to [AI-optimized documentation](/documentation/ai-optimized-documentation).

## Key benefits

<CardGroup>
  <Card title="Accelerate your development" icon="rocket">
    Use the documentation as an MCP service in your AI code editor to assist your coding and integration tasks.
  </Card>

<Card title="Improve your LLM's responses" icon="brain">
    Retrieve information from the documentation in your AI code editor to improve the accuracy of the responses.
  </Card>

<Card title="Reduce manual research" icon="book">
    Reduce the need for manual research and documentation lookup.
  </Card>

<Card title="Reduce LLM hallucinations" icon="triangle-exclamation">
    Ground responses in current documentation instead of invented endpoints or SDK patterns.
  </Card>
</CardGroup>

<Note>
  The documentation MCP server provides **search** and **get page** tools only. It does not execute Suki API calls on your behalf.
</Note>

## MCP server URL

Use the following URL as the custom connector endpoint:

```
https://developer.suki.ai/mcp
```

You can copy this URL from the **Documentation MCP** dropdown in the top navigation bar, from **Copy MCP server URL** in the contextual menu on any page, or from the configuration snippets below.

The screenshot below shows the **Documentation MCP** dropdown in the top navigation bar:

The panel includes copy-ready snippets for the MCP endpoint, Cursor (`mcp.json`), Claude Code, VS Code (`.vscode/mcp.json`), and Claude (custom connector). Select the copy button next to each snippet to paste it into your editor or terminal.

## MCP server tools

When you connect the Suki developer documentation MCP server, it provides two tools:

1. **Search**: Searches across our documentation to find relevant content, returning snippets with titles and links. Use this when you need to discover information or find pages matching a query.
2. **Get page**: Retrieves the full content of a specific documentation page by its path. Use this when you already know the page path, such as from search results, and need the complete content rather than a snippet.

AI applications such as Cursor and Claude can determine when to use each tool based on the context of the conversation. For example, your AI application might first search our documentation to find relevant pages, then use the get page tool to retrieve the full content of the most relevant result.

### Search parameters

The search tool supports **optional parameters** that your AI applications can use to control and refine search results.

<Expandable title="Search parameters">
  <ResponseField name="pageSize" type="number">
    Number of results to return, between 1 and 50. Defaults to 10.
  </ResponseField>

<ResponseField name="scoreThreshold" type="number">
    Minimum relevance score between 0 and 1. Only returns results at or above this threshold. Use this to filter out low-relevance matches.
  </ResponseField>

<ResponseField name="version" type="string">
    Filter results to a specific documentation version. For example, `v0.7`. Only returns content tagged with the specified version or content available across all versions.
  </ResponseField>

<ResponseField name="language" type="string">
    Filter results to a specific language code. For example, `en`, `zh`, or `es`. Only returns content in the specified language or content available across all languages.
  </ResponseField>
</Expandable>

### Get page parameters

The get page tool accepts one required parameter:

<ResponseField name="page" type="string">
  The page path to retrieve, such as `documentation/webhook/quickstart`. Use page paths returned from search results.
</ResponseField>

## How to set up MCP integration

<Tabs>
  <Tab title="Cursor">
    <Steps>
      <Step title="Open MCP settings in Cursor" icon="gear">
        1. Use **Command + Shift + P** on Mac or **Ctrl + Shift + P** on Windows to open the command palette.
        2. Search for **Open MCP settings** and select **Add custom MCP**. This opens `mcp.json`.
        3. Add the following configuration:

```json theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
        {
          "servers": [
            {
              "url": "https://developer.suki.ai/mcp"
            }
          ]
        }
        ```

Or select **Connect to Cursor** from the contextual menu on any documentation page.
      </Step>
    </Steps>
  </Tab>

<Tab title="VS Code">
    <Steps>
      <Step title="Configure the MCP server in VS Code" icon="gear">
        1. Create a `.vscode/mcp.json` file in your project root.
        2. Add the following configuration:

```json theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
        {
          "servers": {
            "suki-docs": {
              "type": "http",
              "url": "https://developer.suki.ai/mcp"
            }
          }
        }
        ```
      </Step>
    </Steps>
  </Tab>

<Tab title="Claude">
    <Steps>
      <Step title="Add a custom connector in Claude" icon="gear">
        1. Navigate to the **Connectors** page in Claude settings.
        2. Select **Add custom connector**.
        3. Set the name to **Suki Developer Documentation MCP server** and the URL to `https://developer.suki.ai/mcp`.
        4. Select **Add**.
        5. When using Claude, select the attachments button and choose **Suki Developer Documentation MCP server**.
      </Step>
    </Steps>
  </Tab>

<Tab title="Claude Code">
    <Steps>
      <Step title="Install the MCP server with Claude Code CLI" icon="terminal">
        Run the following command:

```bash theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
        claude mcp add --transport http "Suki Developer Documentation MCP server" https://developer.suki.ai/mcp
        ```
      </Step>
    </Steps>
  </Tab>
</Tabs>

<Tip>
  Use the **Documentation MCP** dropdown in the top navigation bar to copy these snippets without retyping URLs or JSON.
</Tip>

## Test your connection

After configuration, ask your AI tool:

```
What MCP tools do you have available?
```

You should see the Suki documentation search and get page tools listed. Then try:

```
Search the Suki documentation for ambient session webhooks
```

The AI should search and return relevant documentation pages.

## Troubleshooting

<AccordionGroup>
  <Accordion icon="plug" title="MCP server not connecting">
    Verify the URL is exactly `https://developer.suki.ai/mcp`. Check your internet connection and restart your AI tool after configuration.
  </Accordion>

<Accordion icon="search" title="Search or get page tools not available">
    Confirm the MCP server was added correctly. Try removing and re-adding the server configuration. Check your AI tool's MCP support documentation.
  </Accordion>

<Accordion icon="file-lines" title="Search returns no results">
    Try different or more general search terms (for example, "webhook" instead of "session completion webhook payload"). Verify the MCP connection is active.
  </Accordion>
</AccordionGroup>

## Additional context for AI tools

Use these URLs when an AI tool needs broader context than a single page:

Install the skill from your project:

```bash npm theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
npx skills add https://developer.suki.ai
```

# Medication Orders
Source: https://developer.suki.ai/documentation/medication-orders

Learn how the Medical Orders API and Suki Medical Orders Service turn clinician conversations into structured, EHR-ready medication orders

<span>Quick summary</span>
  </div>

<div>
    The Medical Orders API uses the Suki Medical Orders Service to identify and suggest clinical orders from doctor-patient conversations. Verbal instructions become structured, EHR-compatible artifacts (for example RxCUI codes) so you can streamline workflows and reduce manual work.
  </div>

<span>Last updated:</span>
    <span>May 2026</span>
  </div>
</div>

<Info>
  **Medication orders are supported by:** APIs, Mobile SDK, Web SDK
</Info>

<Warning>
  This feature is not enabled by default. To enable it, contact Suki to request access (if not already enabled).
</Warning>

<Note>
  * **REST APIs:** Send encounter configuration, context, and retrieve structured order payloads through our ambient APIs (including the [Context API](/api-reference/ambient-sessions/context) and structured data endpoints mentioned below).
  * **Mobile SDK (iOS):** Pass optional medication context on <Tooltip href="/Glossary/a">ambient sessions</Tooltip>
    after you create a session. Refer to [Orders info](/mobile-sdk/ambient-guides/provide-clinical-context#orders-info) section in provide clinical context for more information.
  * **Web SDK:** Use the [Medication orders integration](/web-sdk/medication-orders/overview) guide to configure and generate medication orders in the Headed Web SDK.
</Note>

**Medication orders** uses the Suki Medical Orders Service to identify and suggest clinical orders from doctor-patient conversations. Those instructions are translated into structured, EHR-compatible artifacts so you can streamline workflows and reduce manual effort.

During a <Tooltip href="/Glossary/e">clinical encounter</Tooltip>, Suki surfaces medication recommendations. The service converts them into structured payloads
(for example [RxCUI codes](https://www.nlm.nih.gov/research/umls/rxnorm/overview.html)) for accuracy and reliability downstream.

Use medication orders when you need to:

* **Align with your EHR:** Apply validation that matches how your EHR expects orders to look before submission.
* **Keep clinical context tight:** Tie every order to a diagnosis through problem-based context (PBC).
* **Track orders across sessions:** Reconcile new, continued, or discontinued therapy when the same <Tooltip href="/Glossary/e">encounter</Tooltip> spans more than one <Tooltip href="/Glossary/a">ambient session</Tooltip>.
* **Integrate flexibly:** Pull full <Tooltip href="/Glossary/s">structured data</Tooltip> or focus on medication orders only.

## Key features

<CardGroup>
  <Card title="EHR-centric validation" icon="shield-check">
    Apply strict validation logic for your configured EHR so orders stay submittable under that system's rules.
  </Card>

<Card title="Problem-based context (PBC)" icon="link">
    Every order links to a mandatory diagnosis so fidelity stays high and each order traces to a problem in the session.
  </Card>

<Card title="Cumulative session reconciliation" icon="rotate">
    Re-ambient logic reconciles orders across multiple sessions in one encounter, using active medications, prior session data, and the current transcript.
  </Card>

<Card title="Flexible retrieval" icon="download">
    Pull all structured data at once, or target medication orders only when that fits your app.
  </Card>
</CardGroup>

## Technical requirements

For an order to be valid and submittable, the following fields must be present:

* **Drug name**
* **Medication code (RxCUI)** that matches the acceptable list for your configured EHR
* **Linked diagnosis** that references an existing, valid problem in the session

<Note>
  If mandatory fields are missing, the API returns the order in the `partial_medication_orders` list. If a suitable diagnosis cannot be identified, the order is marked **`INCOMPLETE_DX`**.
</Note>

## Integration workflow for Ambient APIs

```mermaid actions={false} theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
flowchart TD
    A[Configure encounter] --> B[Ingest context<br/>via API call]
    B --> C[Cumulative reconciliation<br/>NEW, <br/>DISCONTINUE, <br/>REFILL]
    C --> D[Retrieve structured<br/>data via API call]

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

<Steps>
  <Step title="Configure the encounter" icon="gear">
    Set EHR context at the encounter level so validation applies for the whole session.

* **Field:** `submittable_ehr`
    * **Type:** enum (for example `athena`, `epic`, `cerner`)
  </Step>

<Step title="Ingest context" icon="database">
    Use the <Badge>POST</Badge> [Context API](/api-reference/ambient-sessions/context) to send the patient's active medication list and any orders from prior sessions. For high-fidelity generation, explicitly separate **`encounter_context`** from **`previous_session_orders`** so the service can tell current encounter data from earlier session data.

While sending the medication orders to the context API, set **`status`** on each medication order to **`ACTIVE`**, **`DISCONTINUED`**, or **`REFILLED`**.

<Step title="Run cumulative reconciliation ("Diff" logic)" icon="rotate">
    The Medical Orders Service applies re-ambient reconciliation using:

* Active medications shared from the EHR
    * Orders generated from previous sessions
    * The current session transcript

The API returns an updated cumulative list. Medications can be labeled **NEW**, **DISCONTINUE**, or **REFILL**.
  </Step>

<Step title="Retrieve structured data" icon="code">
    Call the structured data endpoints to read generated orders. Use the paths in [Retrieve structured orders](#retrieve-structured-orders). For the full structured payload (not only orders), see [Get structured data](/api-reference/ambient-content/structured-data) and [Get encounter structured data](/api-reference/ambient-content/encounter-structured-data).

**Example medication order payload**

```json JSON theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
    {
      "drug_name": "Lisinopril",
      "medication_code": {
        "type": "RXCUI",
        "code": "314076"
      },
      "dosage": {
        "raw_value": "1 tablet",
        "quantity": 1,
        "unit": "TAB"
      },
      "frequency": {
        "raw_value": "Once daily",
        "structured_value": "ONE_A_DAY"
      },
      "instructions": "Take one tablet by mouth once daily",
      "medication_timing": {
        "raw_value": "In the morning",
        "structured_value": "IN_THE_MORNING"
      },
      "strength": {
        "raw_value": "10mg"
      },
      "format": {
        "raw_value": "Tablet"
      },
      "route": {
        "raw_value": "By mouth"
      },
      "linked_diagnosis_codes": [
        {
          "type": "ICD10",
          "code": "I10"
        }
      ],
      "number_of_refills": 3,
      "start_date": "2024-01-15T00:00:00Z",
      "end_date": "2024-04-15T00:00:00Z",
      "duration_in_days": 90,
      "status": "REFILLED",
      "metadata": {
        "origin": "EMR",
        "encounter_relation": "CURRENT_ENCOUNTER"
      }
    }
    ```
  </Step>
</Steps>

<Note>
  **REST alignment:** On the [Context API](/api-reference/ambient-sessions/context), set **`emr.target_emr`** to **`ATHENA`**, **`EPIC`**, or **`CERNER`** so medication validation lines up with the same EHR you target at encounter configuration (see Step 1 above). That guide also lists required fields when you send **`orders.medication_orders.values`** on the same request.
</Note>

## Retrieve structured orders

Use the following endpoints to retrieve structured orders:

<CardGroup>
  <Card title="Session-Scoped Medication Orders" icon="code" href="/api-reference/ambient-content/structured-data">
    Retrieve structured orders for a session
  </Card>

<Card title="Encounter-Scoped Medication Orders" icon="code" href="/api-reference/ambient-content/encounter-structured-data">
    Retrieve structured orders for an encounter
  </Card>
</CardGroup>

## Global filtering rules

The Medication Orders API applies these filters by default:

* **Intent filtering:** Orders where `intent_flag` is **FALSE** are dropped (for example when a patient asks about a drug but the clinician does not prescribe it).
* **Referential integrity:** Generated orders only link to problems that appear in the current artifacts. They never reference missing data.
* **Empty values:** The Medication Orders API does not return string placeholders such as `NA` or empty strings for optional fields that were not verbalized.

# Note Sections (LOINC Codes)
Source: https://developer.suki.ai/documentation/note-sections

LOINC standardized clinical note sections supported by Suki for EHR integration

<Callout title="Updates" icon="bell">
  **Updated**

Added Medication orders (LOINC **`52471-0`**) as a supported note section to enable Medication orders in the note generation process for the Headed Web SDK.
</Callout>

<span>Quick summary</span>
  </div>

<div>
    Note sections divide <Tooltip href="/Glossary/c">clinical notes</Tooltip> into standard parts such as "Chief Complaint," "Physical Exam," and "Assessment and Plan." Suki uses <Tooltip href="/Glossary/l">LOINC</Tooltip> codes to identify each section, which ensures seamless integration with your EHR system.
  </div>

<span>Last updated:</span>
    <span>May 2026</span>
  </div>
</div>

<Info>
  **Note sections is supported by:** APIs, Web SDK, Mobile SDK, Headless Web SDK
</Info>

Note sections divide clinical notes into standard parts such as "Chief Complaint," "Physical Exam," and "Assessment and Plan." This organized structure makes notes easier to read and ensures seamless integration with your EHR system.

Suki uses <Tooltip href="/Glossary/l">LOINC</Tooltip> codes (Logical Observation Identifiers Names and Codes) to identify each section. LOINC is a widely adopted healthcare standard, which means your notes will work consistently across different EHR systems and applications.

When you specify the note sections, you get the following benefits:

* **Better organization**: Content is automatically sorted into the right sections
* **EHR ready**: Notes match the format your EHR expects
* **Industry standard**: LOINC codes are recognized across healthcare systems
* **Customizable**: Choose only the sections you need for your workflow

## How it works

When you start an <Tooltip href="/Glossary/a">ambient session</Tooltip>, you specify which sections you want in your note by providing their LOINC codes. Suki listens to the conversation and automatically organizes what's discussed into those sections.

**Example:**

If you specify "Chief Complaint" (10154-3), "History of Present Illness" (10164-2), and "Physical Exam" (29545-1), Suki will:

* Put information about why the patient is visiting into the Chief Complaint section
* Organize the patient's story into the History of Present Illness section
* Capture exam findings into the Physical Exam section

The generated note includes each section with its LOINC code, making it easy to map directly to your EHR's structure.

## Supported note sections

Suki supports the following clinical note sections using LOINC codes:

| SR No. | LOINC CODE | Section Common Name        |
| ------ | ---------- | -------------------------- |
| 1      | 39238-1    | Anticipatory Guidance      |
| 2      | 42348-3    | Advanced Directives        |
| 3      | 48765-2    | Allergies                  |
| 4      | 51848-0    | Assessment                 |
| 5      | 51847-2    | Assessment and Plan        |
| 6      | 10154-3    | Chief Complaint            |
| 7      | 61144-2    | Diet                       |
| 8      | 55128-3    | Disposition                |
| 9      | 46239-0    | Discussion Notes           |
| 10     | 10157-6    | Family History             |
| 11     | 47420-5    | Functional Status          |
| 12     | 8648-8     | Hospital Course            |
| 13     | 10164-2    | History of Present Illness |
| 14     | 11369-6    | Immunizations              |
| 15     | 61150-9    | Interval History           |
| 16     | 10160-0    | Medications                |
| 17     | 10190-7    | Mental Status Exam         |
| 18     | 11348-0    | Past Medical History       |
| 19     | 11358-9    | Past Psychiatric History   |
| 20     | 10167-5    | Past Surgical History      |
| 21     | 69730-0    | Patient Instructions       |
| 22     | 29545-1    | Physical Exam              |
| 23     | 18776-5    | Plan                       |
| 24     | 11450-4    | Problem List               |
| 25     | 47519-4    | Procedure                  |
| 26     | 56822-0    | Response to Therapy        |
| 27     | 30954-2    | Results                    |
| 28     | 78486-8    | Risk Assessment            |
| 29     | 10187-3    | Review of Systems          |
| 30     | 29299-5    | Reason for Visit           |
| 31     | 29762-2    | Social History             |
| 32     | 75325-1    | Symptoms and Stressors     |
| 33     | 61146-7    | Therapy Goals              |
| 34     | 8716-3     | Vitals                     |
| 35     | 11334-0    | Development History        |
| 36     | 52471-0    | Medication Orders          |

## Choosing your sections

Select sections that match your clinical workflow and EHR requirements. Here are some common configurations:

| Configuration           | Description                                                                                                                      |
| :---------------------- | :------------------------------------------------------------------------------------------------------------------------------- |
| **Basic SOAP Note**     | Chief Complaint (10154-3), History of Present Illness (10164-2), Physical Exam (29545-1), and Assessment and Plan (51847-2)      |
| **Comprehensive Visit** | Add Medications (10160-0), Allergies (48765-2), Problem List (11450-4), and Review of Systems (10187-3)                          |
| **Specialty-Specific**  | Choose sections relevant to your specialty (e.g., Mental Status Exam (10190-7) for psychiatry, Vitals (8716-3) for primary care) |

<Tip>
  Start with a few essential sections and add more as needed. Adjust your configuration anytime based on what works best for your workflow.
</Tip>

## How to use note sections

Specify which sections you want when creating an ambient session by providing their LOINC codes.

**Example:**

```javascript JavaScript theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
ambientOptions: {
  sections: [
    { loinc: "10154-3" }, // Chief Complaint
    { loinc: "10164-2" }, // History of Present Illness
    { loinc: "29545-1" }, // Physical Exam
    { loinc: "51847-2" }  // Assessment and Plan
  ]
}
```

Suki automatically organizes the conversation content into these sections. Each generated section includes:

* **Section name**: The readable title (e.g., "Chief Complaint")
* **Content**: Relevant text extracted from the conversation
* **LOINC code**: The standard identifier for EHR integration

This structured format makes it easy to map sections directly to your EHR's note template.

# Welcome To Suki For Partners
Source: https://developer.suki.ai/documentation/overview

Suki for Partners is Suki's developer platform that provides Clinical documentation, Form filling, and Dictation capabilities into your healthcare applications. With our APIs and SDKs, you can add advanced AI features without the complexity of building and maintaining a clinical AI system. Watch the video below to see Suki for Partners in practice.

<video alt="Suki for Partners platform demonstration video" aria-label="Suki for Partners platform demonstration video">
  Your browser does not support the video tag.
</video>

## Overview

Every patient visit is a conversation. But for clinicians, that conversation often comes with an invisible burden.

While listening to patients, clinicians must also document findings, update records, navigate clinical systems, and complete administrative tasks. This constant context switching can interrupt the flow of the visit, reduce patient engagement, contribute to clinician burnout, and increase the risk of missed details.

Suki was built to change that.

Powered by **Ambient Clinical Intelligence**, Suki helps clinicians stay focused on the patient instead of the screen. By listening to conversations, understanding clinical context, and completing documentation tasks in the background, Suki reduces administrative work and gives clinicians more time for care.

## Ambient Clinical Intelligence across healthcare

Today, Suki powers AI experiences across a broad range of healthcare workflows:

* **Telehealth:** Through partnerships such as [Zoom](https://www.suki.ai/press-releases/zoom-and-suki-plan-to-provide-ai-generated-clinical-notes-to-healthcare-institutions/), Suki generates clinical notes directly within virtual care workflows, helping clinicians focus on patient conversations instead of documentation.
* **Care management:** Organizations such as [HealthEdge](https://www.suki.ai/press-releases/healthedge-and-suki-introduce-ambient-clinical-intelligence-for-care-management/) use Suki to bring Ambient Clinical Intelligence into care coordination and post-acute workflows, reducing documentation burden across the continuum of care.
* **Electronic health records (EHR):** Through integrations with EHR platforms including [WellSky](https://www.suki.ai/press-releases/wellsky-launches-ai-powered-ambient-listening-for-specialty-care-ehr/), medent, and [Azalea Health](https://www.suki.ai/press-releases/suki-establishes-program-to-ai-enable-electronic-health-records/), Suki embeds ambient clinical intelligence directly into the systems clinicians already use to document and manage patient care.
* **Revenue cycle management:** Suki supports documentation and coding workflows across revenue cycle management organizations, including collaborations with [Optum Real](https://www.fiercehealthcare.com/ai-and-machine-learning/optum-real-and-suki-build-out-collaboration-r1-teams-heidi-link-ai-scribe), helping improve operational efficiency and financial performance.

## Bring Suki to your product

**Suki for Partners** makes the same technology available through [APIs](/api-reference/overview) and [SDKs](/sdk-overview/overview), allowing healthcare organizations and technology vendors to embed clinically intelligent AI experiences directly into their products and workflows.

Instead of building, training, and maintaining a healthcare AI platform from scratch, you can use Suki's clinically tuned infrastructure to deliver AI-powered experiences within existing healthcare workflows.

## What you can build

With Suki for Partners, you can add capabilities such as:

* **Ambient note generation** to create clinical documentation from patient conversations.
* **Natural language voice interactions** that allow clinicians to complete tasks using speech.
* **Medically tuned dictation** optimized for clinical terminology and healthcare workflows.
* **Voice and text-based form filling** for faster data capture and documentation.

## Your experience, powered by Suki

You remain in control of the user experience, workflow design, and branding.

Suki provides the clinical intelligence, healthcare-specific capabilities, and enterprise-grade infrastructure required to deliver AI-powered healthcare experiences at scale.

<Callout icon="sparkles">
  Latest capabilities and features to try:

<Badge icon="sparkles">New</Badge> **Form filling APIs:** Create and manage form filling sessions to collect data during in-person visits or virtual encounters. [Learn more](/form-filling-api-reference/overview).

<Badge icon="sparkles">Beta</Badge> **Dictation SDK:** Embed speech-to-text capabilities into your web app with in-field and scratchpad modes. [Learn more](/dictation-sdk/introduction).

<Badge icon="sparkles">Beta</Badge> **Headless Web SDK:** React hooks and core APIs for fully custom clinical UIs. [Learn more](/headless-web-sdk/introduction).

<Badge icon="sparkles">New</Badge> **Audio Dictation APIs:** Create sessions, stream audio, and retrieve transcripts for real-time dictation workflows. [Learn more](/documentation/dictation).

<Badge icon="sparkles">New</Badge> **Audio Streaming and Download API:** Stream or download original audio from ambient sessions for playback, QA, or archival. [Learn more](/documentation/audio-streaming-download).
</Callout>

## Recommended path for getting started

Follow these steps to go from zero to a working Suki for Partners integration.

<Accordion title="Start your integration">
  <Steps>
    <Step title="Read the quickstart guide" icon="rocket">
      Set up your environment, review prerequisites, and run your first integration steps against Suki for Partners.

<a href="/documentation/getting-started">Learn more</a>
    </Step>

<Step title="Learn how to get access to Suki APIs and SDKs" icon="key">
      Understand how Partner IDs, tokens, and secure access work so your app can call Suki APIs and SDKs safely.

<a href="/documentation/partner-authentication">Learn more</a>
    </Step>

<Step title="Choose your workflow" icon="sliders">
      Choose between Ambient Workflows and Form Filling Workflows to pick the workflow that fits your use case.

<a href="/documentation/workflows">Learn more</a>
    </Step>

<Step title="Explore product capabilities" icon="list">
      Dig into ambient documentation, dictation, note sections, multilingual support, and other features you can ship in your product.

<a href="/documentation/note-sections">Learn more</a>
    </Step>

<Step title="Explore use cases" icon="magnifying-glass">
      Explore the most common use cases for Suki for Partners.

<a href="/documentation/use-case">Learn more</a>
    </Step>
  </Steps>

<Note>
    This documentation focuses on Suki for Partners. For Suki Assistant (the end-user app), contact
    <a href="mailto:support@suki.ai">support</a>.
  </Note>
</Accordion>

## Why choose Suki for Partners?

Building AI capabilities in-house is complex and time-consuming. Suki for Partners gives you a faster way to add AI-powered healthcare features without building and maintaining your own AI infrastructure.

Move from months of in-house development to shipping AI features in days.

Whether you're building EHRs, telehealth platforms, care management systems, or revenue cycle tools, our developer toolkit helps you accelerate your AI roadmap without the heavy development work.

## Key benefits

<AccordionGroup>
  <Accordion title="Purpose-Built for Healthcare" icon="heart">
    Built specifically for healthcare, enabling you to quickly deploy clinical workflows and documentation features.
  </Accordion>

<Accordion title="AI Differentiation" icon="sparkles">
    Use the latest AI technology to differentiate your solutions and position yourself as a market leader.
  </Accordion>

<Accordion title="Customizable" icon="paint-brush">
    Customize the look and feel of your application to match your brand with our web SDK.
  </Accordion>

<Accordion title="Higher User Adoption" icon="user">
    Drive stronger user adoption and retention by reducing clinician burnout.
  </Accordion>

<Accordion title="Secure & Compliant" icon="lock">
    Compliant with HIPAA guidelines with secure and private data handling.
  </Accordion>

<Accordion title="Fast Integration" icon="rocket">
    Skip long development cycles. Integration takes weeks, not months.
  </Accordion>
</AccordionGroup>

## What can you build with Suki for Partners?

Use Suki for Partners to build:

<div>
  <CardGroup>
    <Card title="Clinical Documentation (Ambient)" icon="file-text">
      Automatically generate clinical documentation from doctor-patient conversations.
    </Card>

<Card title="Voice-Powered Workflows" icon="microphone">
      Add natural language interaction to your healthcare applications.
    </Card>

<Card title="EHR Integration" icon="database">
      Seamlessly connect with existing electronic health records (EHRs) and telehealth platforms.
    </Card>

<Card title="Mobile Healthcare Apps" icon="mobile">
      Build iOS and Android apps with AI-powered clinical documentation features.
    </Card>
  </CardGroup>
</div>

## Key capabilities

Suki for Partners includes powerful ambient capabilities to enhance your healthcare applications. Refer to the cards below for more details on each capability.

<div>
  <CardGroup>
    <Card title="Multilingual Support" icon="language" href="/api-reference/capabilities/multilingual">
      <div>
        <span>80+ Languages</span>
      </div>

Support 80+ languages with automatic English note generation.
    </Card>

<Card title="Personalization" icon="user" href="/api-reference/capabilities/personalization">
      <div>
        <span>Customizable</span>
      </div>

Customize note generation based on provider preferences.
    </Card>

Organize clinical notes by patient problems and diagnoses instead of traditional sections.
    </Card>

<Card title="Note Sections" icon="file-text" href="/documentation/note-sections">
      <div>
        <span>LOINC</span>
      </div>

Configure custom clinical note sections using standard LOINC codes.
    </Card>

<Card title="Clinical Documentation (Ambient)" icon="microphone" href="/documentation/ambient-documentation">
      <div>
        <span>AI-Powered</span>
      </div>

Automatically generate clinical notes from patient-provider conversations.
    </Card>

<Card title="Specialties" icon="stethoscope" href="/documentation/specialties">
      <div>
        <span>Specialized</span>
      </div>

Optimize note generation for specific medical specialties.
    </Card>
  </CardGroup>

Real-time audio transcription for converting patient-provider conversations into text.
    </Card>

<Card title="Form Filling" icon="file-lines" href="/documentation/form-filling">
      <div>
        <span>New</span>
        <span>Form Filling</span>
      </div>

Create form filling sessions for nursing and other clinical workflows.
    </Card>
  </CardGroup>
</div>

## How to integrate with Suki for Partners?

Based on your use case and workflow, you can select the integration method that fits your project's requirements, UI strategy, and technical approach:

<Tabs>
  <Tab title="Ambient Workflows" icon="waveform">
    Choose the integration method that fits your project's requirements, UI strategy, and technical approach:

<div>
          <h3>Ambient REST APIs</h3>

<p>
            Use our APIs for direct access to Suki's AI features. Ideal when you need to build a completely custom user interface, integrate specific functions into an existing system, or keep full control over the user experience.
          </p>

<p>
            Access capabilities like <strong>ambient documentation</strong>, <strong>speech recognition</strong>, <strong>form filling</strong>, and <strong>coding assistance</strong>.
          </p>

<span>Quickstart</span>
            </a>

<span>API overview</span>
            </a>

<span>Partner authentication</span>
            </a>
          </div>

<div>
            <p>
              Our Ambient Clinician Note Generation API is currently in <strong>Early Access</strong>. To request access, contact our
              <a href="https://www.suki.ai/suki-partners/">Partnership team</a>.
            </p>
          </div>
        </div>
      </div>

<p>
            The Suki <strong>Web SDK</strong> includes <strong>pre-built UI components</strong> for quick integration into web-based healthcare applications. Use ready-to-use components to add clinical workflows like note-taking without designing the full UI yourself.
          </p>

<span>Quickstart</span>
            </a>

<span>Web SDK overview</span>
            </a>

<span>Implementation</span>
            </a>
          </div>
        </div>
      </div>

<div>
          <div>
            <h3>Headless Web SDK</h3>
            <Badge icon="sparkles">Beta</Badge>
          </div>

<p>
            For <strong>React 18+</strong> apps that need full control over layout and branding. Use our hooks and core APIs for authentication, ambient sessions, and streaming while you build every screen to match your design system.
          </p>

<span>Quickstart</span>
            </a>

<span>Headless Web SDK overview</span>
            </a>

<span>Compare integration options</span>
            </a>
          </div>

<div>
            <p>
              The Headless Web SDK is currently in <strong>Beta</strong> phase.
            </p>
          </div>
        </div>
      </div>

<div>
          <h3>Mobile SDK</h3>

<p>
            The Suki <strong>Mobile SDK</strong> is a headless SDK for native mobile applications. Design your own UI while using our SDK's functions for note generation, with strong backend functionality and maximum layout flexibility.
          </p>

<span>Quickstart</span>
            </a>

<span>Mobile SDK overview</span>
            </a>

<span>Create session</span>
            </a>
          </div>

<div>
            <p>
              Currently supports <strong>iOS</strong>. <strong>Android</strong> support is <strong>coming soon</strong>.
            </p>
          </div>
        </div>
      </div>

<div>
          <div>
            <h3>Dictation SDK</h3>
            <Badge icon="sparkles">Beta</Badge>
          </div>

<p>
            Embed <strong>clinical dictation</strong> in web applications with a <strong>hosted iframe</strong>. Use <strong>in-field</strong> mode on a specific text control or <strong>scratchpad</strong> mode for a floating dictation surface. Integrate with <strong>JavaScript</strong> or <strong>React</strong>; you design entry points and receive transcript text through callbacks.
          </p>

<span>Quickstart</span>
            </a>

<span>Dictation SDK overview</span>
            </a>

<span>JavaScript integration</span>
            </a>
          </div>

<div>
            <p>
              The Dictation SDK is currently in <strong>Beta</strong> phase.
            </p>
          </div>
        </div>
      </div>
    </div>
  </Tab>

<Tab title="Form Filling Workflows" icon="file-lines">
    Choose the integration method that fits your project's requirements, UI strategy, and technical approach:

<div>
          <h3>Form Filling REST APIs</h3>

<p>
            Use our Form filling APIs for direct access to structured medical-form workflows. Ideal when you need a completely custom user interface, integrate into an existing system, or keep full control over capture, session lifecycle, and how structured output is saved.
          </p>

<p>
            Create sessions, seed context, stream audio over the shared Partner Ambient <strong>WebSocket</strong>, retrieve <strong>structured form data</strong>, and submit feedback using REST endpoints.
          </p>

<span>Quickstart</span>
            </a>

<span>API overview</span>
            </a>

<span>Authentication</span>
            </a>
          </div>

<div>
            <p>
              For streaming audio and shared WebSocket behavior, see
              <a href="/documentation/audio-stream">Audio streaming</a>.
            </p>
          </div>
        </div>
      </div>
    </div>
  </Tab>
</Tabs>

# Partner Authentication
Source: https://developer.suki.ai/documentation/partner-authentication

JWT-based authentication implementation for Suki platform partners

<Callout icon="handshake">
  **Are you a Suki partner?**

To use any of our APIs or SDKs, you must be a Suki partner. Contact our partnership team to get started with the onboarding process. They will help you set up your authentication system and get you started with the Suki APIs and SDKs.

<div>
    <a href="https://www.suki.ai/suki-partners/">
      Contact Partnership Team

This guide explains how Suki uses your existing authentication system to authenticate your application to use Suki's APIs and SDKs. You'll use your existing authentication system; Suki doesn't handle user logins directly. You'll use a <Tooltip href="/Glossary/p">Partner Token</Tooltip> (JWT) that your identity provider issues after user sign-in.

## Prerequisites

Before you begin, ensure you have:

<CardGroup>
  <Card title="Authentication System" icon="shield-check">
    An authentication system that generates standards-compliant JWTs or is OAuth 2.0 compliant.
  </Card>

<Card title="User Identifier" icon="user">
    JWTs that include at least one consistent user identifier claim (like `sub` or `email`).
  </Card>

<Card title="Public Key Endpoint" icon="link">
    A publicly accessible <Tooltip href="/Glossary/j">JWKS</Tooltip> endpoint where Suki can fetch your public keys to verify tokens.
  </Card>

<Card title="Completed Onboarding" icon="handshake">
    Completed [Partner onboarding](/documentation/partner-onboarding) and registered your JWKS endpoint URL with Suki.
  </Card>
</CardGroup>

<Note>
  Already a Suki partner and looking for how to authenticate providers and users to use the Suki APIs? Refer to [Provider authentication](/api-reference/provider-authentication) for more details.
</Note>

## How authentication works

Suki uses a federated authentication model called **token exchange**. Instead of creating separate user accounts, Suki trusts your existing authentication system.

**The process:**

1. A user signs in to your application using your identity provider
2. Your system generates a JWT token for that user
3. You send this token (called `partnerToken`) to Suki when initializing APIs or SDKs
4. Suki verifies the token using your public keys and grants access

The `partnerToken` must be a standard <Tooltip href="/Glossary/j">JWT</Tooltip> that Suki can verify using your public keys.

### Authentication flow

```mermaid actions={false} theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
flowchart TD
    Start([User Signs In]) --> IDP[Identity Provider<br/>authenticates user]
    IDP --> Token[IDP issues<br/>partner token JWT]
    Token --> Init[Your app initializes Suki SDK<br/>with partner token]
    Init --> Send[SDK sends partner token<br/>to Suki Backend]
    Send --> Validate[Suki Backend<br/>validates token<br/>using your JWKS endpoint]
    Validate --> Check{Token valid?}
    Check -->|No| Error[Authentication fails]
    Check -->|Yes| SukiToken[Suki Backend returns<br/>Suki-specific token]
    SukiToken --> Store[SDK stores<br/>token internally]
    Store --> Ready[SDK ready for use]
    Ready --> Feature[User requests Suki feature]
    Feature --> Call[App calls<br/>SDK method]
    Call --> Auth[SDK makes authorized request<br/>to Suki Backend]
    Auth --> Response[Suki Backend<br/>returns result]
    Response --> Display[SDK returns<br/>result to app]
    Display --> End([Complete])
    
    classDef authStyle fill:#FFE148,stroke:#D4A017,stroke-width:2px,color:#000000
    classDef tokenStyle fill:#FFF394,stroke:#FFE148,stroke-width:2px,color:#000000
    classDef readyStyle fill:#FFD700,stroke:#D4A017,stroke-width:3px,color:#000000
    
    class IDP,Init,Send,Validate authStyle
    class Token,SukiToken,Store tokenStyle
    class Ready readyStyle
```

## Key concepts

### Identity provider (IDP)

An Identity Provider is the system that handles user authentication for your application. When users sign in, your IDP verifies their credentials and confirms their identity. This can be a third-party service like **Okta** or **Azure AD**, or a system you built yourself.

### Partner token (JWT)

The `partnerToken` is a JWT (JSON Web Token) that your identity provider creates after successfully authenticating a user. You pass this token to Suki's SDKs or APIs during initialization to prove the user's identity.

**Requirements for the partner token:**

* Must be signed using the [RS256 algorithm](https://www.techtarget.com/searchsecurity/definition/RSA) (RSA Signature with SHA-256)
* Must be issued by your identity provider after user authentication
* Must include user identifier claims that Suki can verify

**Required claims for the partner token:**

The `partnerToken` you provide to Suki must include one or more of these JWT claims:

* **`exp`** - Token expiration time (Unix timestamp). The token must not be expired when you send it to Suki.
* **`iss`** - Token issuer (usually your identity provider's URL or identifier).
* **`aud`** - Token audience (who the token is intended for).
* **User Identifier** - A claim that uniquely identifies the user, such as `sub`, `email`, or a custom claim like `userId`.

<Note>
  During onboarding, you must inform Suki which **identifier field** your tokens use. If your tokens have multiple identifiers, **specify** which one is the **primary identifier**.
</Note>

## Public key sharing methods

Suki needs your public keys to verify your tokens. Choose one of these methods to share them:

| Method             | Description                                                            |
| ------------------ | ---------------------------------------------------------------------- |
| **JWKS\_URL**      | (Recommended) Host your public keys at a public JWKS URL endpoint.     |
| **STORED\_SECRET** | Share your public key with Suki; we store it securely in our database. |
| **OKTA**           | Use Okta as your identity provider; share your Okta issuer URL.        |
| **JWTASSERTION**   | Share your public key as a JWT signed by Suki's private key.           |

### JWKS URL (recommended)

A JWKS (JSON Web Key Set) URL is a public HTTPS endpoint where Suki can fetch your public keys. Suki uses these keys to verify that your `partnerToken` was signed by your identity provider and hasn't been tampered with.

**Example JWKS URL:** `https://sdp.suki-stage.com/api/auth/.well-known/jwks-pub.json`

**Example JWKS Response:**

```json JSON theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
{
  "keys": [
    {
      "kty": "RSA",
      "kid": "sdp-pub",
      "use": "sig",
      "alg": "RS256",
      "n": "base64url-encoded-modulus",
      "e": "base64url-encoded-exponent"
    }
  ]
}
```

### How to find your JWKS URL

If you use Okta, Auth0, AWS Cognito, Azure AD, or Google Identity, they provide this URL automatically.

**Where to find it:**

* Check your identity provider's developer console → application settings → **JWKS** or **OpenID Connect configuration**
* Often available at: `https://your-idp-domain/.well-known/openid-configuration`
* If you can't find it, contact your identity provider or watch this [Tutorial video](https://www.youtube.com/watch?v=biv2kFFjsfE)

## Generating the partner token

### Use OAuth 2.0 / OpenID Connect (recommended)

Using OAuth 2.0 or OpenID Connect is the recommended approach. Your identity provider (like Okta or Azure AD) handles user login and issues an ID token (a JWT). This ID token becomes your `partnerToken` that you pass to Suki.

**Why this is secure:**

* Your identity provider handles authentication
* Neither Suki nor your app handles user passwords
* Tokens are cryptographically signed and verified

**Sample JWT:**

```JWT JWT theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
eyJhbGciOiJSUzI1NiIsImtpZCI6IjEyMzQ1In0.
eyJzdWIiOiJ1c2VyXzAwMSIsImVtYWlsIjoidXNlckBleGFtcGxlLmNvbSIsImV4cCI6MTcyNDUwMDAwMH0.
TUlDSEFTdW5nU2lnbmF0dXJlRGlnaXRhbGx5U2lnbmVkV2l0aFByaXZhdGVLZXk
```

<Tip>
  Use [jwt.io](https://jwt.io/) to decode and inspect JWT tokens. Paste your token to see its claims and verify the structure.

### Using a custom authentication system

If you don't use OAuth 2.0, you can generate JWTs with your own authentication system. Make sure your tokens meet the requirements in this guide:

* Signed with RS256 algorithm
* Include all required claims
* Properly formatted as a standard JWT

<Note>
  When you pass a `partnerToken` to Suki, we use your `partnerId` to find your registered JWKS URL and verify the token's signature. We trust that you've properly authenticated the user.
</Note>

## Authentication flow steps

<Steps>
  <Step title="User signs in" icon="user">
    A user signs in to your application using your identity provider. After successful authentication, your IDP issues a JWT token (`partnerToken`).
  </Step>

<Step title="Initialize SDK" icon="rocket">
    Your application initializes the Suki SDK with the `partnerToken` and your `partnerId`. The SDK sends these to Suki's backend for validation.
  </Step>

<Step title="Token validation" icon="shield-check">
    Suki validates your token:

* Uses your `partnerId` to find your partner configuration
    * Fetches your public keys from your registered JWKS endpoint
    * Verifies the token's digital signature using those keys
    * Confirms the token hasn't expired and contains required claims
  </Step>

<Step title="Receive Suki token" icon="key">
    If validation succeeds, Suki returns a Suki-specific token. The SDK:

* Stores this token securely (you don't need to manage it)
    * Automatically includes it in all API requests
    * Refreshes it automatically when needed
  </Step>

<Step title="Ready to use" icon="check-circle">
    Your application can now use Suki's APIs and SDKs. The SDK handles token management automatically.
  </Step>
</Steps>

## Troubleshooting

Common authentication issues and how to fix them:

<Accordion title="Missing User Identifier">
  **Error:** 400 Bad Request - "Missing required identifier claim"

**Fix:**

* Check that your `partnerToken` includes the user identifier claim you specified during onboarding
  * Ensure the identifier value is not empty or null
  * If your token structure changed, contact [Suki support](https://forms.suki.ai/SukiSupport/form/SukiSDKSupport/formperma/T3z7hYJ7Ph-J7JrWSN08QJn32BYjarkxqm8Lm8XFPow) to update your configuration
</Accordion>

<Accordion title="Invalid or Expired Token">
  **Error:** 401 Unauthorized - "Token validation failed"

**Fix:**

* Verify your application generates valid JWTs
  * Check the `exp` claim to ensure the token hasn't expired
  * Confirm all required claims (`exp`, `iss`, `aud`, user identifier) are present
  * Use [jwt.io](https://jwt.io/) to decode and inspect your token
</Accordion>

<Accordion title="JWKS Endpoint Not Accessible">
  **Error:** 502 Bad Gateway or timeout

**Fix:**

* Ensure your JWKS endpoint URL is publicly accessible over HTTPS
  * Check firewall rules or IP restrictions that might block Suki's servers
  * Test the URL in a browser or with `curl` to confirm it's reachable
</Accordion>

<Accordion title="Wrong Partner ID">
  **Error:** 400 Bad Request - "Unknown partner identifier"

**Fix:**

* Verify the `partnerId` you're using matches the one Suki provided during onboarding
  * Check that your JWKS URL in Suki's system matches your actual endpoint URL
</Accordion>

<Accordion title="Malformed Token">
  **Error:** 400 Bad Request - "Malformed token"

**Fix:**

* Ensure the token follows standard JWT format: `header.payload.signature`
  * Verify the token is properly Base64URL encoded
  * Check that the `alg` in the header matches your signing algorithm (should be RS256)
</Accordion>

<Accordion title="Key Rotation Issues">
  **Error:** Authentication fails after previously working

**Fix:**

* If you rotated your signing keys, update your JWKS endpoint with the new public keys
  * Verify the `kid` (Key ID) in your JWT header matches a key in your JWKS endpoint
  * Ensure old keys remain available during the transition period
</Accordion>

## Next steps

Once authentication is working, you're ready to integrate Suki's features:

<Icon icon="file-lines" /> **[Web SDK](/web-sdk/overview)** - Add pre-built UI components to your web application

<Icon icon="file-lines" /> **[Mobile SDK](/mobile-sdk/overview)** - Integrate ambient intelligence into iOS apps

<Icon icon="file-lines" /> **[Headless Web SDK](/headless-web-sdk/introduction)** - Build custom UIs with React hooks

<Icon icon="file-lines" /> **[API reference](/api-reference/overview)** - Use REST APIs for maximum flexibility

# Partner Onboarding
Source: https://developer.suki.ai/documentation/partner-onboarding

Complete onboarding process to become a Suki Developer Platform partner

Before you can use Suki's APIs and SDKs, you must complete a **one-time** onboarding process. This guide walks you through getting started as a Suki partner.

Once onboarded, you'll receive a <Tooltip href="/Glossary/p">Partner ID</Tooltip> (`partner_id`) that identifies your organization. Then register users and start integrating Suki's AI capabilities into your application.

## Key concepts

<Card>
  <CardGroup>
    <Card title="Partner" icon="handshake">
      An organization that integrates with Suki to use our services. A partner can contain multiple organizations.
    </Card>

<Card title="Organization" icon="building">
      A group of users within a partner, such as a hospital or a clinic.
    </Card>

<Card title="Provider" icon="user">
      A user within an organization, such as a doctor or a nurse, who uses Suki's services.
    </Card>
  </CardGroup>
</Card>

## Partner ID

A Partner ID is a unique identifier that Suki assigns to your organization during onboarding. You'll use this ID in all API calls and SDK initializations.

**What it's used for:**

* Links your application to its configuration in the Suki Developer Platform
* Determines which authentication endpoint to use for token validation
* Maps your user roles to Suki's capabilities

<Tip>
  You'll receive your Partner ID after completing onboarding. Include it in all API requests and when initializing SDKs.
</Tip>

## How authentication works

Suki uses your existing identity provider to authenticate users. You don't need to create separate user accounts in Suki.

**The authentication flow:**

1. A provider signs in to your application using your identity provider (like Okta, Azure AD, or Auth0)
2. Your identity provider issues a token for that user
3. You send this token to Suki in your API requests
4. Suki verifies the token to confirm the user's identity and grant access

<Tip>
  **Identity Provider**: A service that authenticates users and issues identity tokens. Examples include Okta, Auth0, and Azure AD. You'll use your existing identity provider (no need to set up a new one for Suki).
</Tip>

## Onboarding process

Follow these steps to get started:

### Onboarding flow

```mermaid actions={false} theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
flowchart TD
    A([Start]) --> B[Contact Suki Customer Success]
    B --> C[Share business details, use case,<br/>contact person, and authentication method]
    C --> D[Suki reviews and provisions your account]
    D --> E[You receive your Partner ID]
    E --> F[Register users and call APIs<br/>with identity provider tokens]
    F --> G([Integrate and go live])

classDef stepStyle fill:#FFE148,stroke:#D4A017,stroke-width:2px,color:#000000
    classDef milestoneStyle fill:#FFF394,stroke:#FFE148,stroke-width:2px,color:#000000
    classDef doneStyle fill:#FFD700,stroke:#D4A017,stroke-width:3px,color:#000000

class B,C,D stepStyle
    class E milestoneStyle
    class F,G doneStyle
```

<Steps>
  <Step title="Contact Suki" icon="user-plus">
    Reach out to the Suki Customer Success team to begin onboarding. Have this information ready:

* **Business details**: Official business name, email address, and phone number
    * **Use case**: Description of your business and how you plan to use Suki
    * **Contact person**: Name of the person managing the integration
    * **Authentication method**: How you'll authenticate users (see options below)

<Callout icon="lock-open">
      **Supported Authentication Methods**

Suki supports these authentication methods. You'll use your existing identity provider:

* **Stored Secret** - Share your public key with Suki, stored securely in our database
      * **JWKS URL** - Host your public keys at a public endpoint; Suki fetches them automatically
      * **Okta** - Use Okta as your identity provider; Suki gets keys from your Okta issuer URL
      * **JWT Assertion** - Share your public key as a signed JWT following RFC 7523

Learn more in the [Partner authentication](/documentation/partner-authentication) guide.
    </Callout>
  </Step>

<Step title="Suki reviews your information" icon="check-circle">
    The Suki team reviews your information and sets up your account. This typically takes a few business days.
  </Step>

<Step title="Receive your Partner ID" icon="key">
    Once approved, you'll receive your unique Partner ID. Use this ID in all API calls and SDK initializations to identify your organization.
  </Step>
</Steps>

## Getting support

Need help? Reach out through any of these channels:

<AccordionGroup>
  <Accordion title="Contact the Suki team">
    Reach out to your Suki Customer Success or Program Manager directly.
  </Accordion>

<Accordion title="Slack channel">
    Use the dedicated Slack channel created for your integration team.
  </Accordion>

<Accordion title="Support ticket">
    Create a [Support ticket](https://forms.suki.ai/SukiSupport/form/SukiSDKSupport/formperma/T3z7hYJ7Ph-J7JrWSN08QJn32BYjarkxqm8Lm8XFPow) for technical issues or questions.
  </Accordion>
</AccordionGroup>

# Supported Medical Specialties
Source: https://developer.suki.ai/documentation/specialties

Complete list of 100+ medical specialties supported by the Suki Platform

<span>Quick summary</span>
  </div>

<div>
    A Medical Specialty is the type of care a provider (doctor) practices, like Cardiology, Pediatrics, or Emergency Medicine. When you tell Suki what specialty a provider (doctor) has, Suki generates notes that match how that specialty works.
  </div>

<span>Last updated:</span>
    <span>June 2026</span>
  </div>
</div>

<Info>
  **Specialties is supported by:** APIs, Web SDK, Mobile SDK, Headless Web SDK
</Info>

A Medical Specialty is the type of care a <Tooltip href="/Glossary/p">provider</Tooltip> (doctor) practices, like Cardiology, Pediatrics, or Emergency Medicine. When you tell Suki what specialty a provider has, Suki generates notes that match how that specialty works.

For example, a **Cardiologist** and a **Pediatrician** have different specialties, and the notes that Suki needs to generate for them will be different.

* **Cardiologist**: Uses terms like "ejection fraction," "stent placement," "cardiac catheterization"
* **Pediatrician**: Uses terms like "growth percentile," "vaccination schedule," "developmental milestones"

When you specify the specialty, Suki:

* **Uses the right medical terms** for that specialty
* **Recognizes specialty-specific abbreviations** correctly
* **Structures notes** the way that specialty typically documents
* **Provides relevant suggestions** that match that specialty's workflow

As a result, providers get more accurate notes that match how that specialty actually works in practice.

## How it works

When you start an <Tooltip href="/Glossary/a">ambient session</Tooltip>, specify the provider's specialty. Suki uses this information throughout the session to generate notes that match the specialty's documentation standards and terminology.

<Note>
  Suki supports 120+ medical specialties. We regularly add new specialties as they become available. If you need a specialty that's not listed, contact support.
</Note>

## How to use specialties

Specify a specialty when initializing the SDK or providing session context. Use the specialty code (like `CARDIOLOGY` or `PEDIATRICS`) from the list below.

<Tabs>
  <Tab title="Web SDK">
    **Web SDK Example:**

```javascript JavaScript highlight={9} theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
    import { SukiAuthManager } from "@suki-sdk/core";
    import { initialize } from "@suki-sdk/js";

const authManager = new SukiAuthManager({
      partnerId: "your-partner-id",
      partnerToken: "your-partner-token",
      providerName: "John Doe",
      providerOrgId: "1234",
      providerSpecialty: "CARDIOLOGY", // Optional, defaults to FAMILY_MEDICINE
      environment: "production",
      loginOnInitialize: true,
      providerId: "1234567890", // optional - default is empty
    });

const sdkClient = initialize({
      authManager,
    });
    ```
  </Tab>

<Tab title="Headless Web SDK">
    **Headless Web SDK Example:**

```typescript TypeScript highlight={8} theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
    import { useAmbientSession } from "@suki-sdk/react-headless";

const { setSessionContext } = useAmbientSession();

// Set specialty in session context
    await setSessionContext({
      provider: {
        specialty: "CARDIOLOGY"
      }
    });
    ```
  </Tab>

<Tab title="Mobile SDK">
    **Mobile SDK Example:**

```swift Swift highlight={3} theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
    let contextDetail: [String: AnyHashable] = [
        SukiAmbientConstant.kProviderContext: [
            SukiAmbientConstant.kSpeciality: "CARDIOLOGY"
        ]
    ]

try SukiAmbientCore.shared.setSessionContext(with: contextDetail) { result in
        // Handle result
    }
    ```
  </Tab>
</Tabs>

<Note>
  If you don't specify a specialty, Suki defaults to `FAMILY_MEDICINE`. For best results, always specify the provider's actual specialty.
</Note>

## Supported specialties

Suki supports the following medical specialties. Use the **Value** column when specifying a specialty in your code:

<p>
    No specialties match your search. Try a different term.
  </p>

| S.No | Value                                         | Description                                      |
  | ---- | --------------------------------------------- | ------------------------------------------------ |
  | 1    | NA                                            | N/A - No Specialty                               |
  | 2    | ALLERGY\_AND\_IMMUNOLOGY                      | Allergy and Immunology                           |
  | 3    | ANESTHESIOLOGY                                | Anesthesiology                                   |
  | 4    | CARDIOLOGY                                    | Cardiology                                       |
  | 5    | CRITICAL\_CARE                                | Critical Care                                    |
  | 6    | DERMATOLOGY                                   | Dermatology                                      |
  | 7    | EMERGENCY\_MEDICINE                           | Emergency Medicine                               |
  | 8    | ENDOCRINOLOGY                                 | Endocrinology                                    |
  | 9    | FAMILY\_MEDICINE                              | Family Medicine                                  |
  | 10   | GASTROENTEROLOGY                              | Gastroenterology                                 |
  | 11   | GENETICS                                      | Genetics                                         |
  | 12   | HEMATOLOGY                                    | Hematology                                       |
  | 13   | INFECTIOUS\_DISEASE                           | Infectious Disease                               |
  | 14   | INTERNAL\_MEDICINE                            | Internal Medicine                                |
  | 15   | MEDICAL\_ONCOLOGY                             | Medical Oncology                                 |
  | 16   | NEPHROLOGY                                    | Nephrology                                       |
  | 17   | NEUROLOGY                                     | Neurology                                        |
  | 18   | NEUROSURGERY                                  | Neurosurgery                                     |
  | 19   | NUCLEAR\_MEDICINE                             | Nuclear Medicine                                 |
  | 20   | OBSTETRICS\_GYNECOLOGY                        | Obstetrics and Gynecology                        |
  | 21   | OPHTHALMOLOGY                                 | Ophthalmology                                    |
  | 22   | ORTHOPEDIC\_SURGERY                           | Orthopedic Surgery                               |
  | 23   | OTOLARYNGOLOGY\_HEAD\_AND\_NECK               | Otolaryngology - Head and Neck Surgery           |
  | 24   | PALLIATIVE\_MEDICINE                          | Palliative Medicine                              |
  | 25   | PAIN\_MANAGEMENT                              | Pain Management                                  |
  | 26   | PATHOLOGY                                     | Pathology                                        |
  | 27   | PEDIATRICS                                    | Pediatrics                                       |
  | 28   | PHYSICAL\_MEDICINE\_AND\_REHABILITATION       | Physical Medicine and Rehabilitation             |
  | 29   | PLASTIC\_SURGERY                              | Plastic Surgery                                  |
  | 30   | PODIATRY                                      | Podiatry                                         |
  | 31   | PREVENTATIVE\_MEDICINE                        | Preventative Medicine                            |
  | 32   | PSYCHIATRY                                    | Psychiatry                                       |
  | 33   | PULMONOLOGY                                   | Pulmonology                                      |
  | 34   | RADIATION\_ONCOLOGY                           | Radiation Oncology                               |
  | 35   | RADIOLOGY\_DIAGNOSTIC                         | Radiology - Diagnostic                           |
  | 36   | RADIOLOGY\_INTERVENTIONAL                     | Radiology - Interventional                       |
  | 37   | RHEUMATOLOGY                                  | Rheumatology                                     |
  | 38   | SPORTS\_MEDICINE                              | Sports Medicine                                  |
  | 39   | SURGERY\_CARDIAC\_AND\_THORACIC               | Surgery - Cardiac and Thoracic                   |
  | 40   | SURGERY\_COLON\_AND\_RECTAL                   | Surgery - Colon and Rectal                       |
  | 41   | SURGERY\_GENERAL                              | Surgery - General                                |
  | 42   | SURGERY\_PEDIATRIC                            | Surgery - Pediatric                              |
  | 43   | SURGERY\_VASCULAR                             | Surgery - Vascular                               |
  | 44   | UROLOGY                                       | Urology                                          |
  | 45   | UNLISTED\_MEDICAL                             | Unlisted - Medical                               |
  | 46   | UNLISTED\_SURGICAL                            | Unlisted - Surgical                              |
  | 47   | LACTATION                                     | Lactation                                        |
  | 48   | NUTRITION                                     | Nutrition                                        |
  | 49   | VETERINARIAN                                  | Veterinarian                                     |
  | 50   | GERIATRICS                                    | Geriatrics                                       |
  | 51   | HOSPITAL\_MEDICINE                            | Hospital Medicine                                |
  | 52   | SLEEP\_MEDICINE                               | Sleep Medicine                                   |
  | 53   | FUNCTIONAL\_MEDICINE                          | Functional Medicine                              |
  | 54   | INTEGRATIVE\_MEDICINE                         | Integrative Medicine                             |
  | 55   | HEPATOLOGY                                    | Hepatology                                       |
  | 56   | PEDIATRIC\_ALLERGY\_AND\_IMMUNOLOGY           | Pediatric Allergy and Immunology                 |
  | 57   | PEDIATRIC\_CARDIOLOGY                         | Pediatric Cardiology                             |
  | 58   | PEDIATRIC\_ENDOCRINOLOGY                      | Pediatric Endocrinology                          |
  | 59   | PEDIATRIC\_CRITICAL\_CARE                     | Pediatric Critical Care                          |
  | 60   | DEVELOPMENTAL\_AND\_BEHAVIORAL\_PEDIATRICS    | Developmental and Behavioral Pediatrics          |
  | 61   | PEDIATRIC\_HOSPITAL\_MEDICINE                 | Pediatric Hospital Medicine                      |
  | 62   | PEDIATRIC\_NEPHROLOGY                         | Pediatric Nephrology                             |
  | 63   | PEDIATRIC\_RHEUMATOLOGY                       | Pediatric Rheumatology                           |
  | 64   | PEDIATRIC\_GASTROENTEROLOGY                   | Pediatric Gastroenterology                       |
  | 65   | PEDIATRIC\_PSYCHIATRY                         | Pediatric Psychiatry                             |
  | 66   | GYN\_ONCOLOGY                                 | Gyn-Oncology                                     |
  | 67   | REPRODUCTIVE\_ENDOCRINOLOGY\_AND\_INFERTILITY | Reproductive Endocrinology and Infertility (REI) |
  | 68   | UROGYNECOLOGY                                 | Urogynecology                                    |
  | 69   | SPINE\_SURGERY                                | Spine Surgery                                    |
  | 70   | INTERVENTIONAL\_CARDIOLOGY                    | Interventional Cardiology                        |
  | 71   | CARDIOLOGY\_AND\_ELECTROPHYSIOLOGY            | Cardiology and Electrophysiology                 |
  | 72   | HEART\_FAILURE\_AND\_TRANSPLANT\_CARDIOLOGY   | Heart Failure and Transplant Cardiology          |
  | 73   | ADULT\_CONGENITAL\_HEART\_DISEASE             | Adult Congenital Heart Disease                   |
  | 74   | GASTROENTEROLOGY\_ONCOLOGY                    | Gastroenterology Oncology                        |
  | 75   | SURGERY\_ONCOLOGY                             | Surgery Oncology                                 |
  | 76   | SURGERY\_BARIATRICS                           | Surgery Bariatrics                               |
  | 77   | INVASIVE\_CARDIOLOGY                          | Invasive Cardiology                              |
  | 78   | SURGERY\_THORACIC                             | Surgery Thoracic                                 |
  | 79   | SURGERY\_CARDIOVASCULAR                       | Surgery Cardiovascular                           |
  | 80   | PEDIATRIC\_PULMONOLOGY                        | Pediatric Pulmonology                            |
  | 81   | PEDIATRIC\_ADOLESCENT                         | Pediatric Adolescent                             |
  | 82   | TRANSPLANT\_NEPHROLOGY                        | Transplant Nephrology                            |
  | 83   | HEMATOLOGY\_AND\_ONCOLOGY                     | Hematology and Oncology                          |
  | 84   | MEDICINE\_BARIATRIC                           | Medicine Bariatric                               |
  | 85   | SURGERY\_TRAUMA                               | Surgery Trauma                                   |
  | 86   | BEHAVIORAL\_HEALTH                            | Behavioral Health                                |
  | 87   | URGENT\_CARE                                  | Urgent Care                                      |
  | 88   | COMPREHENSIVE\_CARE                           | Comprehensive Care                               |
  | 89   | OCCUPATIONAL\_MEDICINE                        | Occupational Medicine                            |
  | 90   | ADDICTION\_MEDICINE                           | Addiction Medicine                               |
  | 91   | CARDIAC\_IMAGING                              | Cardiac Imaging                                  |
  | 92   | TRANSPLANT\_HEPATOLOGY                        | Transplant Hepatology                            |
  | 93   | SPINAL\_ONCOLOGY\_AND\_SPINE\_TUMOR\_SURGERY  | Spinal Oncology and Spine Tumor Surgery          |
  | 94   | CONCIERGE\_MEDICINE                           | Concierge Medicine                               |
  | 95   | DRUG\_AND\_ALCOHOL\_REHAB                     | Drug and Alcohol Rehab                           |
  | 96   | TRANSPLANT\_PANCREAS                          | Transplant Pancreas                              |
  | 97   | TRANSPLANT\_INTESTINE                         | Transplant Intestine                             |
  | 98   | BONE\_MARROW\_TRANSPLANT                      | Bone Marrow Transplant                           |
  | 99   | VETERINARY\_URGENT\_CARE                      | Veterinary Urgent Care                           |
  | 100  | VETERINARY\_EMERGENCY\_AND\_CRITICAL\_CARE    | Veterinary Emergency and Critical Care           |
  | 101  | INPATIENT\_PSYCHIATRY                         | Inpatient Psychiatry                             |
  | 102  | NEUROMUSCULOSKELETAL\_MANIPULATIVE\_MEDICINE  | Neuromusculoskeletal Manipulative Medicine       |
  | 103  | EPILEPSY                                      | Epilepsy                                         |
  | 104  | NEUROIMMUNOLOGY                               | Neuroimmunology                                  |
  | 105  | HEADACHE                                      | Headache                                         |
  | 106  | VASCULAR\_NEUROLOGY                           | Vascular Neurology                               |
  | 107  | SURGERY\_BREAST                               | Surgery Breast                                   |
  | 108  | ACCIDENT\_AND\_INJURY                         | Accident and Injury                              |
  | 109  | CANCER\_GENETICS                              | Cancer Genetics                                  |
  | 110  | ONCOLOGY\_BREAST                              | Oncology Breast                                  |
  | 111  | ONCOLOGY\_CUTANEOUS                           | Oncology Cutaneous                               |
  | 112  | ONCOLOGY\_GENITOURINARY                       | Oncology Genitourinary                           |
  | 113  | ONCOLOGY\_HEAD\_AND\_NECK                     | Oncology Head and Neck                           |
  | 114  | INTERVENTIONAL\_PAIN                          | Interventional Pain                              |
  | 115  | ONCOLOGY\_ORTHOPEDIC                          | Oncology Orthopedic                              |
  | 116  | ONCOLOGY\_THORACIC                            | Oncology Thoracic                                |
  | 117  | ONCOLOGY                                      | Oncology                                         |
  | 118  | ONCOLOGY\_WOMENS                              | Oncology Womens                                  |
  | 119  | ORTHOPEDICS\_HAND                             | Orthopedics Hand                                 |
  | 120  | WOUND\_CARE                                   | Wound Care                                       |
</div>

## Getting the list via API

Fetch the list of supported specialties at runtime using the Specialties API:

<CardGroup>
  <Card title="Specialties API" icon="code" href="/api-reference/info/specialties">
    Get the list of supported medical specialties via API
  </Card>
</CardGroup>

This is useful if you want to:

* Display specialty options in a dropdown menu
* Validate specialty codes before sending them to Suki
* Keep your application in sync with Suki's latest specialty additions

## Best practices

<Tip>
  * **Always specify the specialty**: Don't rely on the default. Providing the correct specialty improves note quality.
  * **Match your EHR**: Use the specialty that matches what's in your EHR system for consistency.
  * **Update when needed**: If a provider changes specialties, update the specialty in your session context.
  * **Use specific codes**: Choose the most specific specialty available (e.g., `PEDIATRIC_CARDIOLOGY` instead of `CARDIOLOGY` if applicable).
</Tip>

# Support
Source: https://developer.suki.ai/documentation/support

Get help with integration issues and contact information for Suki platform support

Suki Support is available 24/7 to help you with any issues you may have.

## Self help

If you are having an issue with your integration, you can try the following:

<Steps>
  <Step title="Check the FAQs for common questions">
    * Refer to our [General FAQs](/documentation/faqs/general) for answers to common questions.
    * Refer to our [API FAQs](/api-reference/faqs/authentication) for answers to common questions about the Suki APIs.
    * Refer to our [Web SDK FAQs](/web-sdk/faqs/general) for answers to common questions about the Suki Web SDK.
    * Refer to our [Mobile SDK FAQs](/mobile-sdk/faqs/general) for answers to common questions about the Suki Mobile SDK.
    * Refer to our [Headless Web SDK FAQs](/headless-web-sdk/faqs/general) for answers to common questions about the Suki Headless Web SDK.
    * Refer to our [Dictation SDK FAQs](/dictation-sdk/faqs/general) for answers to common questions about the Suki Dictation SDK.
  </Step>

<Step title="Ask the AI assistant">
    Our documentation is powered by AI. If you're stuck, ask the AI assistant for help. Click the **Ask AI** button at the bottom-right of the page, or the sparkle icon on a code block, to open the assistant panel.
  </Step>

<Step title="Use docs in your AI tools to improve your LLM's responses">
    Add this documentation to your AI tools so they use the docs more effectively. Refer to [AI-optimized documentation](/documentation/ai-optimized-documentation) for the contextual menu, copy options, and one-click AI integrations on every page.

From your project, run:

```bash theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
    npx skills add https://developer.suki.ai
    ```

Or connect the documentation MCP server in your editor. Refer to [Documentation MCP](/documentation/mcp) for setup steps.
  </Step>
</Steps>

<Info>
  Looking for a demo? Contact our [Sales team](https://www.suki.ai/contact-us/) to schedule a demo or visit our site at [Suki.ai](https://www.suki.ai/).
</Info>

## Suki support help desk

If our FAQs and AI assistant were not able to provide answers, or you are having an issue in production, you can reach Suki through any of these channels:

* **Email**: <a href="mailto:support@suki.ai">[support@suki.ai](mailto:support@suki.ai)</a>
* **Support ticket**: Submit a [Suki SDK Support ticket](https://forms.suki.ai/SukiSupport/form/SukiSDKSupport/formperma/T3z7hYJ7Ph-J7JrWSN08QJn32BYjarkxqm8Lm8XFPow) for technical issues or questions.
* **Customer Success or Program Manager**: Reach out to your assigned Suki contact directly.
* **Slack**: Use the dedicated Slack channel created for your integration team.

To help us resolve your issue faster, please include the following details in your email or support ticket:

* **Full error message**: The complete text of the error, including any associated error codes.

* **SDK or API version**: The exact version of the Suki SDK and API you are using.

* **Partner ID**: Your assigned partner identifier.

* **Timestamp**: The UTC timestamp of when the issue occurred.

* **User identifier field**: The field your tokens use to identify the user (e.g., `sub`, `email`).

<Tip>
  **Always use the GA APIs and keep your SDKs up to date**

We regularly update the Suki SDKs and APIs with new features and performance improvements. For the best experience, we recommend always using the latest version of the SDKs and APIs.
</Tip>

## Next steps

<Icon icon="file-lines" /> Refer to our [FAQs](/documentation/faqs/general) for answers to common questions.

# Suki SDKs technical execution
Source: https://developer.suki.ai/documentation/technical-execution

Partner technical execution: how integration works, what partners need, critical technical requirements for Web SDK, Mobile SDK, Suki REST APIs, and Headless Web SDK, integration timeline, and expanded phases.

<div>
  <section>
    <div>
      <div>
        <div>
          <p>Technical Execution</p>

<div />

<h1>Technical Execution</h1>
          <p>Suki SDKs & APIs · Engineering checklist</p>

<p>
            How integration works, what partners need, critical technical requirements, and integration timeline
          </p>
        </div>

<div>
    <div>
      <h2>Technical execution at a glance</h2>

<p>
        Learn how to integrate Suki SDKs and APIs into your product. Go through this technical execution guide for technical requirements and the integration process for our developer tools.
      </p>

<div>
        <h2>How integration works</h2>

<div />

<p>
          These four phases apply across the Web SDK, Mobile SDK, Headless Web SDK, and Suki REST APIs. Your surface changes how you implement each step; use the <a href="/documentation/technical-execution#critical-technical-requirements">Critical technical requirements</a> section below for checklists by product.
        </p>

<h3>Setup and configuration</h3>
            <p>Partner ID, security (JWKS), and environment setup. Install the Web or Headless package, embed the Mobile SDK, or configure REST API clients.</p>
          </div>

<h3>Authentication</h3>
            <p>Connect your IdP, issue partner tokens, and validate access for embedded SDKs or server-side REST API calls.</p>
          </div>

<h3>Ambient session and AI</h3>
            <p>Run sessions with Web or Headless UI, native mobile capture, or API-driven flows. Stream audio, receive transcript and structured clinical note.</p>
          </div>

<h3>Note delivery</h3>
            <p>Receive structured payloads (JSON), map to your formats, and route to chart, record, or downstream systems.</p>
          </div>
        </div>
      </div>

<section>
        <h2>What partners need</h2>

<div />

<p>To use our developer tools, you need to have the following:</p>

<div>
          <div><div><h3>✓ Identity & Security System</h3></div><p>An existing authentication system (OAuth 2.0 or similar) is the foundation. The SDK connects to what's already in place. Most organizations already meet these requirements.</p></div>
          <div><div><h3>✓ Development environment</h3></div><p>Teams shipping a browser client with React (<code>@suki-sdk/react</code>) or JavaScript (<code>@suki-sdk/js</code>) are ready. Server-rendered-only stacks still need a supported client bundle. Standard tools and package managers are all that's needed.</p></div>
          <div><div><h3>✓ Clinical knowledge</h3></div><p>Clinical teams already understand their specialties and documentation requirements. That expertise configures the SDK for optimal note generation.</p></div>
          <div><div><h3>✓ Structured data path</h3></div><p>Ability to receive structured payloads and route them into charts, care plans, billing, or other downstream systems. The SDK delivers LOINC-oriented note data your services can map and persist.</p></div>
          <div><div><h3>✓ Audio capabilities</h3></div><p>Standard web browser microphone permissions and HTTPS connections. Capabilities every modern web application already supports.</p></div>
          <div><div><h3>✓ User information</h3></div><p>Stable identifiers and context for the person using the SDK (for example, physician, nurse, case manager, or virtual care role), plus organization or tenant IDs you already store.</p></div>
        </div>
      </section>

<section>
        <h2>Integration Methods</h2>

<div />

<p>Use our pre-built browser UI with the Web SDK for `React` or `JavaScript` to get started quickly.</p>

View Checklist
              </a>
            </div>
          </div>

<div>
            <div>
              <h3>Mobile SDK</h3>
            </div>

<p>Use our native iOS SDK to integrate Suki clinical intelligence into your native iOS applications.</p>

View Checklist
              </a>
            </div>
          </div>

<p>Use our REST APIs and webhooks to integrate Suki clinical intelligence into your backend or custom client.</p>

View Checklist
              </a>
            </div>
          </div>

<div>
            <div>
              <h3>Headless Web SDK</h3>
            </div>

<p>Use our headless Web SDK to integrate Suki clinical intelligence into your web application with full control over your own user interface.</p>

View Checklist
              </a>
            </div>
          </div>

<div>
            <div>
              <h3>Dictation SDK</h3>
            </div>

<p>Embed clinical dictation in web applications with a hosted iframe, using JavaScript or React packages and your own layout around the dictation surface.</p>

View Checklist
              </a>
            </div>
          </div>

<div>
            <div>
              <h3>Form Filling APIs</h3>
            </div>

<p>Use Form Filling REST APIs and the shared Partner WebSocket to run voice-driven medical form workflows with structured output in your product.</p>

View Checklist
              </a>
            </div>
          </div>
        </div>
      </section>

<section>
        <h2>Integration timeline</h2>

<div />

<div>
          <p><strong>From concept to production in weeks, not months.</strong></p>

<div>
                <div>
                  <h3>Build & customize</h3>

<div />

<p>SDK integration and UI customization so the experience matches your product.</p>
                </div>
              </div>

<div />

<div>
                <div>
                  <h3>Total time to value</h3>

<div />

<p><strong>2-4 weeks</strong> from start to production launch. Compare that to 6-12 months building ambient AI from scratch.</p>
                </div>
              </div>
            </div>

<div>
              <div>
                <div>
                  <h3>Kickoff</h3>

<div />

<p>Partner onboarding and environment setup.</p>
                </div>
              </div>

<div>
                <div>
                  <h3>Validate & ship</h3>

<div />

<p>Testing, QA, and production deployment with confidence.</p>
                </div>
              </div>
            </div>
          </div>
        </div>
      </section>
    </div>

<div>
      <h2>Expanded reference</h2>

<section>
              <h2>Critical technical requirements (Web SDK)</h2>

<div />

<p>These five areas require attention for smooth deployment. Each requirement is standard for modern healthcare web applications.</p>

<div>
                <div>
                  <h4>Authentication</h4>
                  <p>Requirements</p>

<ul>
                    <li>OAuth 2.0 compliant identity provider or custom JWT generation system</li>
                    <li>Publicly accessible JWKS endpoint (HTTPS) for token verification</li>
                    <li>JWT tokens signed with RS256 algorithm</li>
                    <li>Required claims: <code>exp</code>, <code>iss</code>, <code>aud</code>, and user identifier</li>
                  </ul>

<p><strong>Why it matters:</strong> Secure authentication is the foundation of trust. Get this right from the start, and everything else flows smoothly.</p>

<div>
                    <a href="/documentation/partner-authentication">Partner Authentication Guide</a>
                  </div>
                </div>

<div>
                  <h4>Installation</h4>
                  <p>Requirements</p>

<ul>
                    <li>React or JavaScript development environment</li>
                    <li>Node.js with npm, pnpm, or yarn package manager</li>
                    <li>ES6 compatible browser environment</li>
                  </ul>

<p>Package selection</p>

<ul>
                    <li>React apps: install <code>@suki-sdk/react</code></li>
                    <li>Non-React browser apps: install <code>@suki-sdk/js</code></li>
                  </ul>

<p><strong>Why it matters:</strong> Match the package to the stack. React apps get React-optimized components. The JS package targets browser JavaScript outside React. This avoids unnecessary complexity.</p>

<div>
                    <a href="/web-sdk/installation">Installation Guide</a>
                  </div>
                </div>

<div>
                  <h4>Specialties information</h4>
                  <p>Requirements</p>

<ul>
                    <li>List of medical specialties the application supports</li>
                    <li>Understanding of LOINC codes for clinical note sections</li>
                    <li>Mapping between encounter types and appropriate LOINC codes</li>
                  </ul>

<p><strong>Why it matters:</strong> Context is everything. A cardiology note looks different from a behavioral health note. Proper configuration ensures notes are clinically appropriate and perfectly formatted for partner workflows.</p>

<div>
                    <a href="/documentation/specialties">Supported Specialties</a>
                    <a href="/documentation/note-sections#supported-note-sections">LOINC Codes and Note Sections</a>
                    <a href="/web-sdk/product-updates/migration-to-v2#new-required-fields-explained">Specialty Context</a>
                  </div>
                </div>

<div>
                  <h4>Note output and downstream integration</h4>
                  <p>Requirements</p>

<ul>
                    <li>Infrastructure to receive note submission events or callbacks</li>
                    <li>Logic to parse LOINC-encoded JSON structure</li>
                    <li>Workflow to map Suki's output format to your systems of record or handoff targets</li>
                  </ul>

<p><strong>Why it matters:</strong> Completed notes arrive as LOINC-encoded JSON. Partner systems receive structured, ready-to-use data for charts, exports, or internal services. No manual translation needed.</p>

<div>
                    <a href="/web-sdk/guides/note-management#receiving-note-content">Note Submission and Retrieval</a>
                  </div>
                </div>

<div>
                  <h4>Microphone permissions</h4>
                  <p>Requirements</p>

<ul>
                    <li>Microphone access permission flow in the application</li>
                    <li>HTTPS connection for production (required for microphone access)</li>
                    <li>Iframe configuration if embedding: add <code>allow="microphone; clipboard-write; clipboard-read"</code> attributes</li>
                  </ul>

<p><strong>Why it matters:</strong> Audio capture is essential. Without proper microphone permissions, the system can't function. Ensure permissions are requested and iframe configurations are correct.</p>

<div>
                    <a href="/web-sdk/examples/using-inside-iframe#granting-required-permissions">Iframe Permissions Guide</a>
                  </div>
                </div>
              </div>
            </section>
          </Tab>

<section>
              <h2>Critical technical requirements (Mobile SDK)</h2>

<div />

<p>These areas need attention for native iOS deployments. The Mobile SDK is a headless framework: you own the UI while the SDK handles audio, sessions, and platform services.</p>

<div>
                <div>
                  <h4>Authentication and tokens</h4>
                  <p>Requirements</p>

<ul>
                    <li>Implement <code>tokenProvider protocol</code> so the mobile SDK can request authentication tokens when needed</li>
                    <li>Pass `PartnerID`, `ProviderInfo`, and related fields to <code>initialize</code> as described in configuration guide</li>
                    <li>Use <code>.stage</code> for development and <code>.prod</code> for production</li>
                  </ul>

<p><strong>Why it matters:</strong> The SDK exchanges tokens with Suki services on a predictable contract. A correct token provider and initialization payload avoid auth failures during sessions.</p>

<div>
                    <a href="/documentation/partner-authentication">Partner Authentication</a>
                    <a href="/mobile-sdk/configuration">Configuration</a>
                  </div>
                </div>

<div>
                  <h4>Installation and platform</h4>
                  <p>Requirements</p>

<ul>
                    <li>Xcode project targeting <strong>iOS 13.0</strong> or later</li>
                    <li><code>SukiAmbientCore.framework</code> added, embedded, and set to <strong>Embed & Sign</strong></li>
                    <li><code>NSMicrophoneUsageDescription</code> in <code>Info.plist</code> with a clear, user-facing explanation</li>
                  </ul>

<p><strong>Why it matters:</strong> Apple enforces microphone disclosure and embedding rules. A correct deployment target and framework embedding prevent runtime crashes and App Store rejection.</p>

<div>
                    <a href="/mobile-sdk/installation">Mobile SDK Installation</a>
                  </div>
                </div>

<div>
                  <h4>Session lifecycle and delegates</h4>
                  <p>Requirements</p>

<ul>
                    <li>Session delegate implementation for lifecycle and status updates</li>
                    <li>Recording flows aligned with your UX: start, pause, resume, end, and cancel as needed</li>
                    <li>Background recording flag in <code>initialize</code> when your product requires it</li>
                  </ul>

<p><strong>Why it matters:</strong> Ambient capture is stateful. Delegates keep your UI and backend logic in sync with SDK events and errors.</p>

<div>
                    <a href="/mobile-sdk/ambient-guides/create-session">Create Session</a>
                    <a href="/mobile-sdk/ambient-guides/recording">Recording Controls</a>
                  </div>
                </div>

<div>
                  <h4>Content and downstream integration</h4>
                  <p>Requirements</p>

<ul>
                    <li>Logic to poll or receive structured content when a session completes</li>
                    <li>Mapping of structured output into your EHR, exports, or internal services</li>
                    <li>Offline mode awareness: recording can continue when the network is unstable; sync when connectivity returns</li>
                  </ul>

<p><strong>Why it matters:</strong> Clinical value lands when notes reach the right system. Plan retrieval and persistence before go-live.</p>

<div>
                    <a href="/mobile-sdk/ambient-guides/session-status-and-content-retrieval">Session Status and Content Retrieval</a>
                  </div>
                </div>
              </div>
            </section>
          </Tab>

<section>
              <h2>Critical technical requirements (Suki REST APIs)</h2>

<div />

<p>Use these when your backend or a custom client orchestrates login, sessions, and content without the pre-built Web SDK UI. Follow REST and streaming patterns in the API reference.</p>

<div>
                <div>
                  <h4>Authentication and tokens</h4>
                  <p>Requirements</p>

<ul>
                    <li>HTTPS-only clients; obtain a Suki token via login using <code>partner\_id</code>, <code>partner\_token</code>, and <code>provider\_id</code> as documented</li>
                    <li>Partner JWTs issued consistently with your JWKS and Suki validation rules</li>
                    <li>Secure storage and rotation of credentials in your services</li>
                  </ul>

<p><strong>Why it matters:</strong> API access is token-driven. Misconfigured login or partner tokens surface as 401s across session and content calls.</p>

<div>
                    <a href="/api-reference/provider-authentication">Authentication</a>
                    <a href="/api-reference/quickstart">API Quickstart</a>
                  </div>
                </div>

<div>
                  <h4>Endpoints and environments</h4>
                  <p>Requirements</p>

<ul>
                    <li>Correct base URL and API version for stage versus production</li>
                    <li>Use of versioned paths (for example, <code>/api/v1/...</code>) per resource</li>
                    <li>Follow our **HTTPS guidelines** and documented status codes</li>
                  </ul>

<p><strong>Why it matters:</strong> Environment mix-ups cause subtle failures. Pin URLs per environment in configuration, not in scattered constants.</p>

<div>
                    <a href="/api-reference/overview">API Overview</a>
                    <a href="/api-reference/https-guidelines">HTTPS Guidelines</a>
                  </div>
                </div>

<div>
                  <h4>Ambient operations</h4>
                  <p>Requirements</p>

<ul>
                    <li>REST flows for ambient session lifecycle and ambient content as your integration requires</li>
                    <li>Audio or streaming integrations where the API uses WebSockets for real-time transmission</li>
                    <li>Webhook or polling patterns if your architecture consumes async completion signals</li>
                  </ul>

<p><strong>Why it matters:</strong> Ambient features span REST and streaming. Plan both client behavior and server-side orchestration up front.</p>

<div>
                    <a href="/api-reference/ambient-session-management">Ambient Session Management</a>
                    <a href="/api-reference/ambient-content-retrieval">Ambient Content Retrieval</a>
                  </div>
                </div>

<div>
                  <h4>Operational readiness</h4>
                  <p>Requirements</p>

<ul>
                    <li>Retry and error-handling policies aligned with your SLA and the platform's HTTP semantics</li>
                    <li>Logging and monitoring that avoid PHI in unsecured logs</li>
                    <li>Load and rate expectations validated with your Suki contact for high-volume workloads</li>
                  </ul>

<p><strong>Why it matters:</strong> Production APIs need observability and safe handling of transient failures, especially in clinical workflows.</p>

<div>
                    <a href="/api-reference/asynchronous/webhook">Webhook Notifications</a>
                  </div>
                </div>
              </div>
            </section>
          </Tab>

<section>
              <h2>Critical technical requirements (Headless Web SDK)</h2>

<div />

<p>Partner authentication and tokens are the same as the Web SDK. Headless differs because you build your own UI and integrate <code>useAuth</code>, ambient hooks, and related APIs instead of pre-built components.</p>

<div>
                <div>
                  <h4>Authentication</h4>
                  <p>Requirements</p>
                  <p>Same partner authentication checklist as the Web SDK tab.</p>

<p><strong>Why it matters:</strong> It is the same trust model as the Web SDK. In Headless you connect tokens through <code>useAuth</code> and related hooks; auth gaps block ambient APIs until identity is wired correctly.</p>

<div>
                    <a href="/documentation/partner-authentication">Partner Authentication Guide</a>
                    <a href="/headless-web-sdk/authentication">Headless Authentication</a>
                  </div>
                </div>

<div>
                  <h4>Installation and runtime</h4>
                  <p>Requirements</p>

<ul>
                    <li>React <strong>18.0</strong> or higher</li>
                    <li>Install <code>@suki-sdk/platform-react</code> with npm, pnpm, or yarn</li>
                    <li>ES6-compatible browser environment</li>
                  </ul>

<p><strong>Why it matters:</strong> The package ships React hooks. Version and bundler assumptions must match what we test and support.</p>

<div>
                    <a href="/headless-web-sdk/installation">Headless Installation</a>
                  </div>
                </div>

<div>
                  <h4>Partner configuration</h4>
                  <p>Requirements</p>

<ul>
                    <li><code>partnerId</code> from Suki during onboarding</li>
                    <li>Test and production host URLs allowlisted for your app</li>
                    <li>User identifier field in the JWT agreed during onboarding and reflected in tokens</li>
                  </ul>

<p><strong>Why it matters:</strong> Headless initialization fails fast when hosts or user identity keys do not match what Suki configured for your tenant.</p>

<div>
                    <a href="/headless-web-sdk/prerequisites">Prerequisites</a>
                    <a href="/documentation/partner-onboarding">Partner Onboarding</a>
                  </div>
                </div>

<div>
                  <h4>Ambient hooks and browser permissions</h4>
                  <p>Requirements</p>

<ul>
                    <li>Integrate ambient and session hooks per quickstart; handle pending, error, and completion states in your UI</li>
                    <li>Microphone permission UX and HTTPS in production</li>
                    <li>If you embed in an iframe, set appropriate <code>allow</code> attributes for microphone (and clipboard if needed)</li>
                  </ul>

<p><strong>Why it matters:</strong> You own the experience. Explicit permission and error paths keep capture reliable for clinicians.</p>

<div>
                    <a href="/headless-web-sdk/quickstart">Headless Quickstart</a>
                    <a href="/headless-web-sdk/guides/hooks/ambient-hook">Ambient Hook</a>
                  </div>
                </div>
              </div>
            </section>
          </Tab>

<section>
              <h2>Critical technical requirements (Dictation SDK)</h2>

<div />

<p>Dictation embeds a hosted iframe in your web app. You supply partner credentials, mount the surface in your layout, and wire <code>SukiAuthManager</code> and <code>DictationClient</code> (or React equivalents) instead of building capture UI yourself.</p>

<div>
                <div>
                  <h4>Authentication and partner credentials</h4>
                  <p>Requirements</p>

<ul>
                    <li><code>partnerId</code> and <code>partnerToken</code> from Suki after partner onboarding</li>
                    <li><code>SukiAuthManager</code> from <code>@suki-sdk/core</code> with provider fields and staging or production environment</li>
                    <li>Successful login before the dictation iframe can initialize</li>
                  </ul>

<p><strong>Why it matters:</strong> Invalid or missing credentials block iframe initialization. Auth must be stable before clinicians open dictation.</p>

<div>
                    <a href="/documentation/partner-authentication">Partner Authentication Guide</a>
                    <a href="/dictation-sdk/guides/authentication">Dictation Authentication</a>
                  </div>
                </div>

<div>
                  <h4>Installation and runtime</h4>
                  <p>Requirements</p>

<ul>
                    <li>Browser client with <code>HTMLIFrameElement</code> and <code>postMessage</code> (not Node.js or SSR-only rendering for the iframe)</li>
                    <li>Install <code>@suki-sdk/core</code> plus <code>@suki-sdk/dictation</code> or <code>@suki-sdk/dictation-react</code></li>
                    <li>HTTPS in production for secure iframe and platform calls</li>
                  </ul>

<p><strong>Why it matters:</strong> Dictation is browser-hosted. Package and runtime choices must match the integration track you ship.</p>

<div>
                    <a href="/dictation-sdk/installation">Dictation Installation</a>
                    <a href="/dictation-sdk/quickstart">Dictation Quickstart</a>
                  </div>
                </div>

<div>
                  <h4>Layout and iframe hosting</h4>
                  <p>Requirements</p>

<ul>
                    <li>A mount container (<code>rootElement</code>) with real height and a stable layout box</li>
                    <li><code>overflow: visible</code> on wrappers when minimized or floating so the iframe is not clipped</li>
                    <li>If embedded in an iframe, appropriate <code>allow</code> attributes for microphone and clipboard as needed</li>
                  </ul>

<p><strong>Why it matters:</strong> The hosted surface sizes to your DOM. Clipping or zero-height containers hide dictation or break interaction.</p>

<div>
                    <a href="/dictation-sdk/prerequisites">Dictation Prerequisites</a>
                    <a href="/dictation-sdk/guides/configuration">Dictation Configuration</a>
                  </div>
                </div>

<div>
                  <h4>Session modes and callbacks</h4>
                  <p>Requirements</p>

<ul>
                    <li>Choose in-field or scratchpad mode and pass <code>ShowOptions</code> per session</li>
                    <li>Wire submit, cancel, and draft callbacks so your app persists dictated text</li>
                    <li>Error handling for auth failures, layout issues, and iframe load problems</li>
                  </ul>

<p><strong>Why it matters:</strong> You own the surrounding UX. Mode and callback wiring determine how dictated content returns to your fields or charts.</p>

<div>
                    <a href="/dictation-sdk/guides/in-field-mode">In-Field Mode</a>
                    <a href="/dictation-sdk/guides/callbacks">Dictation Callbacks</a>
                  </div>
                </div>
              </div>
            </section>
          </Tab>

<section>
              <h2>Critical technical requirements (Form Filling APIs)</h2>

<div />

<p>Form Filling uses REST for session lifecycle and the shared Partner WebSocket for visit audio. Your backend or custom client authenticates, creates a form-filling session, streams audio with that session ID, then retrieves structured output or consumes webhooks.</p>

<div>
                <div>
                  <h4>Authentication and tokens</h4>
                  <p>Requirements</p>

<ul>
                    <li>OAuth-compliant authentication and JWTs with consistent user identifiers</li>
                    <li>Publicly accessible JWKS endpoint (HTTPS) for token verification</li>
                    <li>Partner credentials: register providers, then obtain a Suki token via login</li>
                  </ul>

<p><strong>Why it matters:</strong> Form Filling REST and WebSocket calls are token-driven. Misconfigured login or JWKS surfaces as auth failures across the workflow.</p>

<div>
                    <a href="/form-filling-api-reference/authentication">Form Filling Authentication</a>
                    <a href="/documentation/partner-authentication">Partner Authentication Guide</a>
                  </div>
                </div>

<div>
                  <h4>Endpoints and environments</h4>
                  <p>Requirements</p>

<ul>
                    <li>Correct base URL and API version for stage versus production</li>
                    <li>Versioned Form Filling paths under <code>/api/v1/form-filling/...</code></li>
                    <li>HTTPS-only clients and documented HTTP status handling</li>
                  </ul>

<p><strong>Why it matters:</strong> Environment mix-ups cause subtle failures. Pin URLs and credentials per environment in configuration.</p>

<div>
                    <a href="/form-filling-api-reference/overview">Form Filling API Overview</a>
                    <a href="/api-reference/https-guidelines">HTTPS Guidelines</a>
                  </div>
                </div>

<div>
                  <h4>Session lifecycle and audio streaming</h4>
                  <p>Requirements</p>

<ul>
                    <li>Create a form-filling session and seed context (template and encounter metadata) when needed</li>
                    <li>Stream audio on <code>GET /ws/stream</code> using the form-filling <code>ambient\_session\_id</code></li>
                    <li>End the session and monitor status until processing completes</li>
                  </ul>

<p><strong>Why it matters:</strong> Capture spans REST and WebSocket. Use the form-filling session ID on the shared stream so audio maps to the correct workflow.</p>

<div>
                    <a href="/form-filling-api-reference/quickstart">Form Filling Quickstart</a>
                    <a href="/documentation/ambient-audio-streaming">Ambient Audio Streaming</a>
                  </div>
                </div>

<div>
                  <h4>Structured output and operations</h4>
                  <p>Requirements</p>

<ul>
                    <li>Poll status and structured-data endpoints, or subscribe to webhooks for completion</li>
                    <li>Map structured form fields into your EHR, exports, or internal services</li>
                    <li>Retry, logging, and PHI-safe observability aligned with your SLA</li>
                  </ul>

<p><strong>Why it matters:</strong> Clinical value lands when populated forms reach the right system. Plan retrieval, validation, and handoff before go-live.</p>

<div>
                    <a href="/form-filling-api-reference/form-filling-content-retrieval">Form Filling Content Retrieval</a>
                    <a href="/api-reference/asynchronous/webhook">Webhook Notifications</a>
                  </div>
                </div>
              </div>
            </section>
          </Tab>
        </Tabs>
      </div>
    </div>
  </div>
</div>

# Partner Use Cases
Source: https://developer.suki.ai/documentation/use-case

Partner scenarios for EHRs, telehealth, care management, revenue cycle, and related applications: Ambient, Dictation, and Form filling. Search, filter, open a card, then use View documentation.

<div>
  <section>
    <div>
      <div>
        <div>
          <p>Suki for Partners</p>

<div />

<h1>
            Use Cases
          </h1>

<p>
            Explore the most popular use cases, workflows, and integrations for Suki for Partners. Review each use case to understand how to use Suki for Partners in your product and accelerate your AI roadmap.
          </p>
        </div>

<span>Ambient</span>
            </button>

<span>Form filling</span>
            </button>

<span>Dictation</span>
            </button>
          </div>
        </div>
      </div>

<div>
        <h2>Featured use cases</h2>
        <p>Start with paths many clinical and operational partners implement first.</p>

<div>
              <span>Ambient</span>
              <span>Automate clinical documentation from the visit</span>

<p>
                Draft clinical notes from encounter audio while you control capture and authentication.
              </p>

<div>
                <span>Ambient APIs</span><span>Web SDK</span><span>Mobile SDK</span><span>Headless Web SDK</span>
              </div>
            </div>

<div>
              <span>Form filling</span>
              <span>Complete structured medical forms from visit audio</span>

<p>
                Turn visit conversation into template-driven form output for your workflow.
              </p>

<div>
                <span>Form Filling APIs</span><span>REST</span>
              </div>
            </div>

<h2>All use cases</h2>

<div>
              <span>Form filling</span>
              <span>Template-driven form sessions</span>

<p>
                Bind Suki medical form templates to a session and retrieve structured output.
              </p>

<div>
                <span>Form Filling APIs</span><span>Templates</span>
              </div>
            </div>

<div>
              <span>Form filling</span>
              <span>Structured form output and EHR handoff</span>

<p>
                Retrieve generated form values and route them into review, save, or handoff flows.
              </p>

<div>
                <span>Form Filling APIs</span><span>Structured data</span>
              </div>
            </div>

<div>
              <span>Ambient</span>
              <span>Problem-based charting and structured note content</span>

<p>
                Align generated notes to problems, sections, and chart-aware titles.
              </p>

<div>
                <span>Web SDK</span><span>Headless Web SDK</span><span>Ambient APIs</span>
              </div>
            </div>

<div>
              <span>Ambient</span>
              <span>Medication orders and richer session context</span>

<p>
                Enrich sessions so drafts reflect medication orders and chart context.
              </p>

<div>
                <span>Ambient APIs</span><span>Mobile SDK</span>
              </div>
            </div>

<div>
              <span>Ambient</span>
              <span>Session audio for playback or download</span>

<p>
                Request short-lived recording access for replay or archival jobs.
              </p>

<div>
                <span>Ambient APIs</span>
              </div>
            </div>

<div>
              <span>Ambient</span>
              <span>Webhooks and asynchronous session completion</span>

<p>
                Receive HTTPS callbacks when ambient sessions complete or fail.
              </p>

<div>
                <span>Webhooks</span><span>Ambient APIs</span>
              </div>
            </div>

<div>
              <span>Dictation</span>
              <span>Hosted browser dictation for fields and scratchpads</span>

<p>
                Add hosted speech-to-text to web fields or scratchpad workflows.
              </p>

<div>
                <span>Dictation SDK</span><span>JavaScript</span><span>React</span>
              </div>
            </div>

<div>
              <span>Dictation</span>
              <span>API-driven real-time dictation without hosted UI</span>

<p>
                Create transcription sessions, stream audio, and handle partial and final transcripts.
              </p>

<div>
                <span>Dictation APIs</span><span>WebSocket</span>
              </div>
            </div>

<div>
              <span>Ambient</span>
              <span>Telehealth and shared browser audio capture</span>

<p>
                Capture ambient audio inside browser telehealth and shared-audio setups.
              </p>

<div>
              <span>Ambient</span>
              <span>Fully custom ambient UI with React hooks</span>

<p>
                Build a fully custom ambient React UI with Headless Web SDK hooks (beta).
              </p>

<div>
                <span>Headless Web SDK</span><span>React</span><span>Beta</span>
              </div>
            </div>

<div>
              <span>Ambient</span>
              <span>Note sections and structured documentation outputs</span>

<p>
                Shape generated notes into predictable sections for downstream systems.
              </p>

<div>
                <span>Web SDK</span><span>Ambient APIs</span>
              </div>
            </div>

<div>
              <span>Dictation</span>
              <span>Choose the right dictation integration path</span>

<p>
                Compare API, Web SDK, and Dictation SDK options for speech-to-text.
              </p>

<div>
                <span>Dictation APIs</span><span>Dictation SDK</span>
              </div>
            </div>

<div>
              <span>Dictation</span>
              <span>Real-time dictation streaming over WebSocket</span>

<p>
                Send JSON audio messages and receive partial and final transcript frames.
              </p>

<div>
                <span>WebSocket</span><span>Dictation APIs</span>
              </div>
            </div>

<div>
              <span>Ambient</span>
              <span>Offline-capable ambient capture (React)</span>

<p>
                Plan ambient capture for brief connectivity loss in React.
              </p>

<div>
                <span>Headless Web SDK</span><span>React</span>
              </div>
            </div>

<div>
              <span>Ambient</span>
              <span>Compact ambient UI with minimized layout</span>

<p>
                Run ambient capture in a compact Web SDK footprint when space is tight.
              </p>

<div>
              <span>Ambient</span>
              <span>Personalization and preference-aware ambient behavior</span>

<p>
                Send personalization payloads so generation honors provider and organization settings.
              </p>

<div>
                <span>Ambient APIs</span>
              </div>
            </div>

<div>
              <span>Form filling</span>
              <span>Choose the Form Filling API path</span>

<p>
                Confirm Form Filling API ownership across web, mobile, and backend teams.
              </p>

<div>
                <span>Form Filling APIs</span><span>Guide</span>
              </div>
            </div>

<p>
          No scenarios match your filters or search. Choose All or another workflow, or try a different keyword.
        </p>
      </div>

<section>
        <h2>
          Partner case studies and press
        </h2>

<div>
          <div aria-label="Featured partner stories">
            <a href="https://www.suki.ai/press-releases/healthedge-and-suki-introduce-ambient-clinical-intelligence-for-care-management/" aria-label="Open press release: HealthEdge and Suki introduce ambient clinical intelligence for care management">
              <div>
                Suki + HealthEdge
              </div>

<div>
                <span>HealthEdge and Suki: ambient care management</span>

<a href="https://www.suki.ai/press-releases/suki-and-athenahealth-expand-partnership-with-general-availability-of-ambient-notes-using-sukis-ambient-technology/" aria-label="Open press release: Suki and athenahealth expand partnership with general availability of ambient notes">
              <div>
                Suki + athenahealth
              </div>

<div>
                <span>Ambient notes on the athenahealth network</span>

<div>
                <span>Zoom and Suki: AI clinical notes</span>

<div aria-label="More partner stories and news">
              <a href="https://go.suki.ai/azalea-case-study" aria-label="Open case study: Why leading EHRs are integrating ambient listening (Azalea)">
                <div>
                  Case study
                </div>

<div>
                  <span>EHRs and ambient listening (Azalea Health)</span>

<div>
                    <span>View case study</span>
                    <span>↗</span>
                  </div>
                </div>
              </a>

# Webhook Configuration
Source: https://developer.suki.ai/documentation/webhook/configuration

Register your webhook callback URL during partner onboarding and meet endpoint requirements for receiving Suki notifications

Webhook configuration is done during [Partner onboarding](/documentation/partner-onboarding). You provide Suki with the **callback URL** (the full URL of the endpoint that will receive <Badge>POST</Badge> requests). This URL is stored at the partner level and is used for all webhook notifications for your organization.

Suki also gives you a **secret key** on your partner record. You use that key only on your server to prove each incoming <Badge>POST</Badge> really came from Suki (see [Signature verification](/documentation/webhook/signature-verification)). Treat it like a password.

## How it works

During onboarding you share your **callback URL** with Suki. Suki stores it on your **partner record** along with your **secret key**. When an Ambient session completes or fails, Suki sends a single <Badge>POST</Badge> to that URL. Your server verifies the signature, processes the payload, and returns **2xx**.

<Note>
  You cannot register or change your webhook URL through a self-service portal or API. Provide your callback URL to the Suki team (for example, during [partner onboarding](/documentation/partner-onboarding)). Suki will configure it for your partner account and confirm the URL with you once it is set.
</Note>

Your endpoint must follow these requirements:

* Accept <Badge>POST</Badge> requests over **HTTPS** only, with **TLS 1.2** or higher. Suki will not send webhooks to **HTTP** URLs.
* Be reachable from the internet (no localhost or private IPs in production).
* Respond with **2xx** (for example, 200) on successful receipt so Suki can consider the notification delivered. Handle validation and business logic after returning 200 if needed.

## Security best practices

<AccordionGroup>
  <Accordion icon="lock" title="Use HTTPS only">
    Your callback URL must use **HTTPS** with **TLS 1.2** or higher. Never use plain HTTP for webhooks.
  </Accordion>
</AccordionGroup>

## Next steps

<Icon icon="file-lines" /> Refer to [Signature verification](/documentation/webhook/signature-verification) for HMAC-SHA-256 verification steps and Python and TypeScript examples.

<Icon icon="file-lines" /> Refer to [Security & best practices](/api-reference/security-best-practices#webhook-security) for platform-wide guidance.

# Webhook Event Types
Source: https://developer.suki.ai/documentation/webhook/event-types

Event types your webhook endpoint receives when ambient sessions complete, fail, time out, or are cancelled

Your webhook endpoint can receive notifications for the following events:

After you configure a callback URL during [partner onboarding](/documentation/webhook/configuration), Suki sends a single <Badge>POST</Badge> to that URL when an Ambient session completes, fails, times out, or is cancelled. Each delivery uses **`Content-Type: application/json`** and includes **`generated-at`** and **`X-API-Key`** headers so you can verify the request before you trust the body. Refer to [Signature verification](/documentation/webhook/signature-verification) for those steps.

Read the top-level **`status`** field in the JSON and branch your handler on the event type. For **session completion** and **session failure**, the API reference documents **`"success"`** and **`"failure"`** payloads with example JSON. For **session timeout** and **session cancellation**, the payload includes **`session_id`** and **`encounter_id`**; refer to the sections below for what to do next.

You can use the following event types to handle the notifications:

<Note>
  The [Asynchronous notifications (webhook)](/api-reference/asynchronous/webhook) API reference documents **`success`** and **`failure`** payloads with example JSON. Timeout and cancellation are webhook events listed in this guide; the API reference does not yet include example JSON for those events.
</Note>

## Session completion

When an ambient session finishes and note generation completes successfully, your endpoint receives a **session completion** notification.

**When `status` is `"success"`:** The payload identifies the session and encounter and provides links to retrieve results. It includes:

* `session_id`, `encounter_id` (always present)
* Optionally: `sessions`, `additional_info`, `_links`

**Inside `_links`**, each key is an array of link objects (`href`, `method`, `name`, `type`).

Following are the keys you will see in the `_links` object:

* **`contents`:** Session-level note content.
* **`encounter_content`:** Encounter-level content.
* **`structured_data`:** Session-level structured clinical data.
* **`encounter_structured_data`:** Encounter-level structured clinical data.
* **`status`:** Status checks.
* **`transcripts`:** Transcripts.

Use the **`_links`** object to fetch session content, encounter content, structured clinical data, status, and transcripts from the Ambient APIs. For each link, combine its **`href`** with your API base URL and use the correct authentication when you call those follow-up APIs.

The **`sessions`** array lists the session IDs tied to the encounter so far.

For an example JSON body, refer to [Payload & Response](/documentation/webhook/payload-and-response).

## Session failure

When the ambient session or note generation fails, your endpoint receives a **session failure** notification.

**When `status` is `"failure"`:** The payload identifies the session and encounter and describes the error. It includes:

* `session_id`, `encounter_id`, `error_code`, `error_detail`

Use **`error_code`** and **`error_detail`** to log the failure, trigger alerts, or show an error in your application. The API reference example uses **`ERROR_CODE_TRANSCRIPTION`** with detail **`Error in transcription`**.

For an example JSON body, refer to [Payload & Response](/documentation/webhook/payload-and-response).

## Session timeout

When an ambient session times out, your endpoint receives a **session timeout** notification.

The payload includes **`session_id`** and **`encounter_id`**. The API reference does not yet document other fields or example JSON for this event.

Record the identifiers and update your application state. If you need the current processing state, refer to [Ambient Session Status](/api-reference/ambient-content/status).

## Session cancellation

When an ambient session is cancelled, your endpoint receives a **session cancellation** notification.

The payload includes **`session_id`** and **`encounter_id`**. The API reference does not yet document other fields or example JSON for this event.

Record the identifiers and update any in-progress state for that session. To confirm how the session ended on the platform, refer to [Ambient Session Status](/api-reference/ambient-content/status). Documented status values there include **`aborted`**, which means the ambient session was cancelled by the user or client.

## Next steps

<Icon icon="file-lines" /> Refer to [Payload & Response](/documentation/webhook/payload-and-response) for payload structure, example JSON bodies, implementation tips, and follow-up API response codes.

<Icon icon="file-lines" /> Refer to [Signature verification](/documentation/webhook/signature-verification) for HMAC-SHA-256 verification steps and Python and TypeScript examples.

<Icon icon="file-lines" /> Refer to the [Asynchronous notifications (webhook)](/api-reference/asynchronous/webhook) API reference for the OpenAPI specification and sample handler code.

# Notification Webhook For Partners
Source: https://developer.suki.ai/documentation/webhook/overview

Learn how Suki pushes notifications to your application via Notification Webhook and how push compares to pull

<span>Quick summary</span>
  </div>

<div>
    Suki provides a webhook endpoint so your application can be notified when ambient sessions complete or fail. You configure a callback URL. When an event occurs, Suki sends a <Badge>POST</Badge> request to that URL.
    Suki supports `push` and `pull` mechanisms based on partner requirements for notifications.
  </div>

<span>Last updated:</span>
    <span>June 2026</span>
  </div>
</div>

<Info>
  **Notification webhook is supported by:** APIs. Web SDK, Mobile SDK, and Headless Web SDK use the same platform APIs for sending notifications.
</Info>

Suki for Partners provides a <Tooltip href="/Glossary/w">webhook</Tooltip> endpoint so your application can be notified when ambient sessions complete or fail. You configure a callback URL. When an event occurs, Suki sends a <Badge>POST</Badge> request to that URL.

This guide explains how webhooks work and how push compares to pull. Suki supports both push and pull based on partner requirements. This guide focuses on push (webhooks). It also covers how the capability applies across APIs and SDKs and how to implement and secure your webhook endpoint.

## Push vs pull

Notifications can be delivered in two main ways:

* **Pull:** Your application repeatedly asks Suki whether something has changed (for example, [Polling the Session Status endpoint](/api-reference/ambient-content/status)). Your system is responsible for when and how often to check.
* **Push:** Suki sends a request to your application when an event happens. Your application exposes an endpoint that Suki calls; you do not need to poll.

Suki supports both **push** and **pull** based on partner requirements. When you choose to use push mechanism, Suki sends a single <Badge>POST</Badge> request to a callback URL that you provide when a session completes, fails, times out, or is cancelled.

<Note>
  With **push mechanism**, you host the **callback URL** and the **infrastructure that receives the notification**.

Suki does not store or queue notifications; delivery is **one-way** and **immediate**.
</Note>

## Notification capability across all offerings

Webhook notifications are part of the **Suki Developer Platform** APIs. You register a webhook callback URL at the **partner level** during onboarding; that URL is used for all sessions created under your partner account.

<Note>
  The Web SDK, Mobile SDK, and Headless Web SDK all use the same notification webhook for sending notifications to your callback URL.
</Note>

When a session is started and ended from any of these clients, the same platform backend processes it and sends the webhook notification to your callback URL.

<Tip>
  We configure one webhook URL per partner. That single URL receives all webhook notifications for your organization, whether the session was created with the direct API, Web SDK, Mobile SDK, or Headless Web SDK. You do not need a separate URL for each client to receive notifications.
</Tip>

## Guides

<CardGroup>
  <Card title="Quickstart" icon="rocket" href="/documentation/webhook/quickstart">
    Step-by-step setup: prerequisites, implement your endpoint, verify, and test.
  </Card>

<Card title="Payload & Response" icon="file-lines" href="/documentation/webhook/payload-and-response">
    Payload structure, example JSON, implementation tips, and follow-up API responses.
  </Card>

<Card title="Signature Verification" icon="lock" href="/documentation/webhook/signature-verification">
    Verify HMAC-SHA-256 signatures with your partner secret key before you trust the body.
  </Card>

<Card title="Configuration" icon="gear" href="/documentation/webhook/configuration">
    Register your callback URL during onboarding and meet endpoint requirements.
  </Card>

<Card title="Event Types" icon="bell" href="/documentation/webhook/event-types">
    Session completion, failure, timeout, and cancellation events your endpoint receives.
  </Card>
</CardGroup>

## API reference

To view and implement your webhook endpoint, refer to the [Asynchronous notifications (webhook)](/api-reference/asynchronous/webhook) API reference.

# Webhook Payload & Response
Source: https://developer.suki.ai/documentation/webhook/payload-and-response

Learn about the structure of the webhook payload and response

Suki sends each notification as a <Badge>POST</Badge> with **`Content-Type: application/json`**. Every delivery includes headers you use to verify the request before you trust the body:

| Header             | What it is                                                                                                                            |
| :----------------- | :------------------------------------------------------------------------------------------------------------------------------------ |
| **`X-API-Key`**    | Hex-encoded **HMAC-SHA-256** signature of this request (see [Signature verification](/documentation/webhook/signature-verification)). |
| **`generated-at`** | Unix time in **milliseconds** for when Suki built the request. Use it to spot stale or replayed traffic.                              |

Your handler should verify those headers first, then read the top-level **`status`** field in the JSON and branch on **`"success"`** or **`"failure"`**.

For the full request specification and sample handler code in Python and TypeScript, refer to the [Asynchronous notifications (webhook)](/api-reference/asynchronous/webhook) API reference.

## Payload structure

Every webhook body includes a top-level `status` field. All other fields depend on that value.

**When `status` is `"success"`:** The payload identifies the session and encounter and provides links to retrieve results. It includes:

* `session_id`, `encounter_id` (always present)
* Optionally: `sessions`, `additional_info`, `_links`

**Inside `_links`**, each key is an array of link objects (`href`, `method`, `name`, `type`).

Following are the keys you will see in the `_links` object:

<Note>
  Use the **`_links`** object to get URLs for fetching session content, encounter content, structured clinical data, status, and transcripts from the Ambient APIs. For each link, combine its **`href`** with your API base URL and use the correct authentication when you call those follow-up APIs.

The **`sessions`** array lists the session IDs tied to the encounter so far.
</Note>

**When `status` is `"failure"`:** The payload identifies the session and encounter and describes the error. It includes:

* `session_id`, `encounter_id`, `error_code`, `error_detail`

Use these fields to log the failure, trigger alerts, or show an error in your application.

For a summary of completion, failure, timeout, and cancellation events, refer to [Event types](/documentation/webhook/event-types).

## Example payloads

The following examples show the JSON bodies your endpoint receives. Use them to validate your parser and to see how the structure maps to the description above.

**Success:**

When a session completes and note generation succeeds, your endpoint receives a payload like this:

```json JSON theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
{
  "_links": {
    "contents": [
      {
        "href": "/path/to/resource", // the URL to fetch the session content
        "method": "GET",
        "name": "name",
        "type": "application/json"
      }
    ],
    "encounter_content": [
      {
        "href": "/path/to/resource", // the URL to fetch the encounter content
        "method": "GET",
        "name": "name",
        "type": "application/json"
      }
    ],
    "structured_data": [
      {
        "href": "/path/to/resource",
        "method": "GET",
        "name": "name",
        "type": "application/json"
      }
    ],
    "encounter_structured_data": [
      {
        "href": "/path/to/resource",
        "method": "GET",
        "name": "name",
        "type": "application/json"
      }
    ],
    "status": [
      {
        "href": "/path/to/resource", // the URL to fetch the status
        "method": "GET",
        "name": "name",
        "type": "application/json"
      }
    ],
    "transcripts": [
      {
        "href": "/path/to/resource", // the URL to fetch the transcripts
        "method": "GET",
        "name": "name",
        "type": "application/json"
      }
    ]
  },
  "additional_info": {
    "priority": "high"
  },
  "encounter_id": "4d753ce1-bbff-43e1-950a-82dea2d86873",
  "session_id": "a953839a-ddcd-407d-b9b0-3ed4b6be4be2",
  "sessions": [
    "20965414-929a-4f71-a3e5-b92bec07d086",
    "29de56bc-960a-4cd5-b18f-79a798d62874"
  ],
  "status": "success"
}
```

Combine each `href` in `_links` with your API base URL and send a <Badge>GET</Badge> request with the appropriate authentication to retrieve content, structured data, encounter resources, status, or transcripts. The `sessions` array lists all session IDs for this encounter.

**Failure:**

When a session or note generation fails, your endpoint receives a payload like this:

```json JSON theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
{
  "encounter_id": "29de56bc-960a-4cd5-b18f-79a798d62874", // the ID of the encounter that failed
  "error_code": "ERROR_CODE_TRANSCRIPTION", // the error code that occurred
  "error_detail": "Error in transcription", // the error detail
  "session_id": "20965414-929a-4f71-a3e5-b92bec07d086", // the ID of the session that failed
  "status": "failure"
}
```

Use `error_code` and `error_detail` to log the failure, send an alert, or display an error to the user.

## Implementation tips

<Tip>
  * Return **200 OK** quickly and do heavy work (follow-up API calls, database updates) in a background job or queue.
  * Treat the handler as idempotent; use `session_id` to detect duplicate deliveries and process each notification only once.
  * Check **`generated-at`** and reject requests that are too old for your risk window, so replayed calls are less useful to an attacker.
  * Store the **secret key** in a secrets manager (for example AWS Secrets Manager or Azure Key Vault), not in source control.
  * Add **rate limiting** on the public URL so abuse is harder.
  * Keep the endpoint highly available (for example a load balancer or redundant instances).
  * Log that a webhook was received plus `session_id`, `encounter_id`, and `status`; avoid logging full bodies if they contain sensitive data.
</Tip>

## Responses from Suki webhook endpoint

When you call the Suki Webhook Endpoint (for example, using the `href` values in `_links` to fetch content, status, or transcripts), Suki returns an HTTP status and, for errors, a JSON body with `code` and `message`.

| Code    | Description                                                                                                          |
| ------- | -------------------------------------------------------------------------------------------------------------------- |
| **200** | OK. The request succeeded.                                                                                           |
| **400** | Bad Request. The request was invalid. Example: `{"code": 400, "message": "invalid request"}`                         |
| **401** | Unauthorized. The token is invalid or authentication failed. Example: `{"code": 401, "message": "invalid token"}`    |
| **500** | Internal Server Error. The server encountered an error. Example: `{"code": 500, "message": "internal server error"}` |

In your application, handle `401` by re-authenticating or refreshing the token. Handle `400` by fixing the request or showing an error. Consider retrying on `5xx` when appropriate.

# Webhook Quickstart
Source: https://developer.suki.ai/documentation/webhook/quickstart

Step-by-step guide to configure, implement, and test a Suki notification webhook endpoint

This guide walks you through how to receive Suki notification webhooks in your application. You configure a callback URL during onboarding, implement a secure POST handler on your server, and process session completion or failure events when Suki calls your endpoint.

## Prerequisites

Before you start, make sure you have:

* Completed [Partner onboarding](/documentation/partner-onboarding)
* Provided Suki with your **callback URL** (HTTPS) and received confirmation that it is configured on your partner record. See [Configuration](/documentation/webhook/configuration).
* Your partner **secret key** from Suki. You use it on your server to verify each incoming POST. See [Signature verification](/documentation/webhook/signature-verification).
* A server-side endpoint reachable from the internet over **HTTPS** (TLS 1.2 or higher)
* An integration path that creates and ends Ambient sessions (direct API, Web SDK, Mobile SDK, or Headless Web SDK). Webhooks fire when those sessions complete or fail.

<Note>
  You cannot register or change your webhook URL through a self-service portal or API. Suki configures one callback URL per partner during onboarding.
</Note>

## Steps

<Steps>
  <Step title="Confirm your callback URL with Suki" icon="gear">
    Share the full HTTPS URL of the endpoint that will receive notifications (for example `https://your-app.example.com/webhooks/notification`) with the Suki team during [partner onboarding](/documentation/partner-onboarding). Suki stores it at the partner level and uses it for all webhook deliveries for your organization.
  </Step>

<Step title="Implement a POST handler on your server" icon="code">
    Host an endpoint that accepts <Badge>POST</Badge> requests with **`Content-Type: application/json`**. Configure your framework to read the **raw request body** before JSON parsing. Suki calls this URL when a session completes, fails, times out, or is cancelled.
  </Step>

<Step title="Verify the signature on every request" icon="lock">
    Read the **`generated-at`** and **`X-API-Key`** headers and verify the HMAC-SHA-256 signature with your partner secret key before you parse the body. If verification fails, return **4xx** and stop. Refer to [Signature verification](/documentation/webhook/signature-verification) for the exact steps and code examples.
  </Step>

<Step title="Parse the JSON and branch on status" icon="file-lines">
    After verification succeeds, parse the body and read the top-level **`status`** field. Branch on **`"success"`** or **`"failure"`**. For field-level detail and example JSON, refer to [Payload & Response](/documentation/webhook/payload-and-response).
  </Step>

<Step title="Process the notification" icon="bell">
    * **Success:** Use **`session_id`**, **`encounter_id`**, and **`_links`** to fetch note content, transcripts, or status from the Ambient APIs. Combine each **`href`** with your API base URL and use the correct authentication when you call those follow-up APIs.
    * **Failure:** Log **`error_code`** and **`error_detail`**, alert your application, or surface an error to the user.
  </Step>

<Step title="Return 2xx to acknowledge receipt" icon="check">
    Respond with **200** (or another **2xx**) after you accept the notification so Suki can consider it delivered. You can run follow-up API calls or queue work after the response if needed.
  </Step>

<Step title="Test end to end" icon="play">
    Run an Ambient session through your integration (create session, stream audio, end session). When processing finishes, Suki sends a POST to your callback URL. Confirm your handler verifies the signature, parses the payload, and processes the event. Refer to the [Ambient API quickstart](/api-reference/quickstart) if you need a session workflow to test against.
  </Step>
</Steps>

## Next steps

<Icon icon="file-lines" /> Refer to [Event types](/documentation/webhook/event-types) for session completion, failure, timeout, and cancellation events.

<Icon icon="file-lines" /> Refer to [Signature verification](/documentation/webhook/signature-verification) for HMAC-SHA-256 verification steps and Python and TypeScript examples.

<Icon icon="file-lines" /> Refer to the [Asynchronous notifications (webhook)](/api-reference/asynchronous/webhook) API reference for the OpenAPI specification and sample handler code.

# Webhook Signature Verification
Source: https://developer.suki.ai/documentation/webhook/signature-verification

Learn how to verify the signature of the webhook request to ensure it is genuine

When Suki calls your webhook, it proves the call is genuine by sending a **signature** you can recompute on your side. If the signature matches, the request really used your **secret key** and the **body was not altered** on the way to you.

<Warning>
  Verify every webhook before you parse the JSON body. Unverified POSTs can expose your integration to spoofed events and tampered payloads.
</Warning>

## What you need

Think of it in three plain pieces:

| Piece                     | What it is                                                                                                                                                                           |
| :------------------------ | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Secret key**            | A password-like string Suki puts on your **partner record** and shares with you during [partner onboarding](/documentation/partner-onboarding). Only your **server** should know it. |
| **`generated-at` header** | A number: **Unix time in milliseconds** when Suki built this request. You need it as part of the signed text.                                                                        |
| **`X-API-Key` header**    | The **expected signature** for this request, already turned into **hex** text. Your job is to compute the same hex and see if they are equal.                                        |

Suki sends each notification as a <Badge>POST</Badge> with **`Content-Type: application/json`**. Your handler reads the raw body and the two headers above before you trust the payload.

## How to verify on your server

Perform the following steps on your server:

<Steps>
  <Step title="Read the raw body first" icon="file-lines">
    Read the request body **before** you parse JSON. Keep the exact bytes or string Suki sent (no pretty-printing, no trimming, no changing spaces).
  </Step>

<Step title="Read the generated-at header" icon="clock">
    Read the **`generated-at`** header exactly as the string Suki sent (the millisecond timestamp).
  </Step>

<Step title="Build the string to sign" icon="link">
    Join **`generated-at` + `:` + raw body** into one long string. Example shape: `1765977748432:{"status":"success",...}` (your timestamp and JSON will differ).
  </Step>

<Step title="Run HMAC-SHA-256" icon="lock">
    Run **HMAC-SHA-256** using your **secret key** as the key and that long string as the data. **HMAC-SHA-256** is a standard "sign this text with this secret" operation; every language has a library for it.
  </Step>

<Step title="Encode the digest as hex" icon="code">
    Turn the HMAC output into **hex** the same way Suki does (usually lowercase hex; if your comparison fails, ask your Suki contact whether casing matters).
  </Step>

<Step title="Compare to X-API-Key" icon="check">
    Compare your hex to the **`X-API-Key`** header. Use a **constant-time** compare if your framework offers one, so attackers cannot guess the signature byte by byte.
  </Step>
</Steps>

If the values **do not match**, stop and return **4xx**. If they **match**, you can safely **parse the JSON** and run your business logic.

**Pseudocode**

```text theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
raw_body = read request body as received (string or bytes)
timestamp = request header "generated-at" exactly as sent
message = timestamp + ":" + raw_body

expected_signature_hex = request header "X-API-Key"
computed_signature_hex = hex( HMAC_SHA256(key = secret_key, data = message) )

if not constant_time_equal(computed_signature_hex, expected_signature_hex):
    return 401 or 400
# else: parse JSON and continue
```

<Tip>
  Read the **raw request body** before JSON parsing. Framework middleware that auto-parses JSON first will break verification because the signature covers the exact bytes Suki sent.
</Tip>

## Code examples

The examples below follow the pseudocode above line for line.

<Tabs>
  <Tab title="Python">
    ```python theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
    import hashlib
    import hmac
    import json

from flask import Flask, jsonify, request

app = Flask(__name__)

# Partner secret key from onboarding
    secret_key = "<partner_secret_key>"

@app.route("/webhooks/notification", methods=["POST"])
    def handle_webhook():
        raw_body = request.get_data(as_text=True)
        timestamp = request.headers.get("generated-at", "")
        message = timestamp + ":" + raw_body

expected_signature_hex = request.headers.get("X-API-Key", "")
        computed_signature_hex = hmac.new(
            secret_key.encode("utf-8"),
            message.encode("utf-8"),
            hashlib.sha256,
        ).hexdigest()

if not hmac.compare_digest(computed_signature_hex, expected_signature_hex):
            return jsonify({"error": "Invalid signature"}), 401  # or 400

# else: parse JSON and continue
        data = json.loads(raw_body)
        return jsonify({"message": "Notification received"}), 200
    ```
  </Tab>

<Tab title="TypeScript">
    ```typescript theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
    import crypto from "crypto";
    import express from "express";

const app = express();

// Partner secret key from onboarding
    const secret_key = "<partner_secret_key>";

app.post("/webhooks/notification", express.raw({ type: "application/json" }), (req, res) => {
      const raw_body = req.body.toString("utf8");
      const timestamp = req.headers["generated-at"] as string;
      const message = timestamp + ":" + raw_body;

const expected_signature_hex = req.headers["x-api-key"] as string;
      const computed_signature_hex = crypto
        .createHmac("sha256", secret_key)
        .update(message, "utf8")
        .digest("hex");

const signatures_match =
        computed_signature_hex.length === expected_signature_hex.length &&
        crypto.timingSafeEqual(
          Buffer.from(computed_signature_hex, "utf8"),
          Buffer.from(expected_signature_hex, "utf8"),
        );

if (!signatures_match) {
        return res.status(401).json({ error: "Invalid signature" });
      }

// else: parse JSON and continue
      const data = JSON.parse(raw_body);
      return res.status(200).json({ message: "Notification received" });
    });
    ```
  </Tab>
</Tabs>

For a full handler that branches on **`status`** and processes **`_links`**, refer to the [Asynchronous notifications (webhook)](/api-reference/asynchronous/webhook) API reference.

## After verification

Once the signature matches:

1. Parse the JSON body.
2. Read the top-level **`status`** field and branch on **`"success"`** or **`"failure"`**.
3. Use **`session_id`**, **`encounter_id`**, and **`_links`** as described in [Payload & Response](/documentation/webhook/payload-and-response).

Return **2xx** (for example, 200) after you accept the notification so Suki can consider it delivered. You can run follow-up API calls or database work after that response if needed.

## Security best practices

<AccordionGroup>
  <Accordion icon="lock" title="Verify requests are from Suki">
    Implement **HMAC-SHA-256** verification using your **secret key**, the **`generated-at`** header, the raw body, and the **`X-API-Key`** header as described above.
  </Accordion>

<Accordion icon="lock" title="Validate the payload">
    After the signature matches, check the JSON shape and **`status`**. Reject malformed or unverified requests with an appropriate **4xx** response.
  </Accordion>

<Accordion icon="lock" title="Store the secret key securely">
    Keep the partner secret key in a secrets manager (for example AWS Secrets Manager or Azure Key Vault), not in source control.
  </Accordion>

<Accordion icon="lock" title="Use HTTPS only">
    Your callback URL must use **HTTPS** with **TLS 1.2** or higher. Suki will not send webhooks to **HTTP** URLs. See [Configuration](/documentation/webhook/configuration).
  </Accordion>
</AccordionGroup>

For platform-wide guidance, refer to [Security & best practices](/api-reference/security-best-practices#webhook-security) and [Authentication FAQs](/documentation/faqs/authentication).

## Next steps

<Icon icon="file-lines" /> Refer to [Event types](/documentation/webhook/event-types) for session completion, failure, timeout, and cancellation events.

# Integration Paths Overview
Source: https://developer.suki.ai/documentation/workflows

Suki for Partners offers Ambient, Dictation, and Form Filling workflows. Learn more about each workflow and how to choose the right one for your use case

With Suki for Partners, you can create Ambient, Dictation, and Form Filling workflows. Choose the APIs or SDKs integration paths that best fit your application type, stack, and how much user interface you want to own.

## Choose your integration path

<Card title="Ambient Workflows & Use Cases" icon="waveform">
  Use ambient workflows to add ambient clinical intelligence to your application for doctor-patient conversations.

<CardGroup>
    <Card title="Ambient APIs" icon="code" href="/documentation/integration-decision-guide#ambient-apis">
      <Badge icon="code">REST</Badge> | <Badge icon="globe">WebSocket</Badge> | <Badge icon="webhook">Webhooks</Badge>
    </Card>

<Card title="Web SDK" icon="globe" href="/documentation/integration-decision-guide#web-sdk">
      <Badge icon="code">JavaScript</Badge> | <Badge icon="react">React</Badge> | <Badge icon="desktop">Headed</Badge>
    </Card>

<Card title="Mobile SDK" icon="mobile" href="/documentation/integration-decision-guide#mobile-sdk">
      <Badge icon="apple">iOS</Badge> | <Badge icon="swift">Swift</Badge>
    </Card>

<Card title="Headless Web SDK" icon="react" href="/documentation/integration-decision-guide#headless-web-sdk">
      <Badge icon="react">React</Badge> | <Badge icon="react">Headless</Badge>
    </Card>

<Card title="Dictation SDK" icon="microphone" href="/documentation/integration-decision-guide#dictation">
      <Badge icon="code">JavaScript</Badge> | <Badge icon="react">React</Badge>
    </Card>
  </CardGroup>
</Card>

<Card title="Form Filling Workflows & Use Cases" icon="file-lines">
  Use form filling workflows for ambient clinical documentation for nursing and other clinical workflows.

<CardGroup>
    <Card title="Form Filling REST APIs" icon="code" href="/documentation/form-filling-integration-decision-guide#form-filling-apis">
      <Badge icon="code">REST</Badge> | <Badge icon="globe">WebSocket</Badge> | <Badge icon="webhook">Webhooks</Badge>
    </Card>
  </CardGroup>
</Card>

## What should I use?

| Area              | Direct API calls (REST/WebSocket/Webhooks)                          | SDKs (Web SDK, Headless Web SDK, Mobile SDK, Dictation SDK)                                       |
| ----------------- | ------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------- |
| Authentication    | Build token exchange, storage, headers, and refresh logic.          | SDK-managed auth setup and token use.                                                             |
| Session lifecycle | Call create, update, status, and end endpoints directly.            | SDK methods or hooks for common session actions.                                                  |
| Audio streaming   | Manage WebSocket connections, audio chunks, events, and reconnects. | Managed recording, streaming, and session events.                                                 |
| UI                | Build every screen, control, and workflow state.                    | Web SDK includes UI; Headless Web SDK, Mobile SDK, and Dictation SDK handle integration behavior. |
| Type safety       | Validate request and response data in your code.                    | Typed methods, options, and events.                                                               |
| Error handling    | Parse HTTP status codes, error bodies, and WebSocket failures.      | SDK errors and events expose structured failure details.                                          |
| Platform fit      | Any client, backend, or multi-platform architecture.                | Supported web, React, iOS, and dictation workflows.                                               |
| Control           | Maximum control over protocol behavior.                             | Less protocol code for supported integrations.                                                    |

# Authentication API
Source: https://developer.suki.ai/form-filling-api-reference/authentication

Learn how to register providers, obtain tokens, and retrieve JSON Web Key Set (JWKS) material for the Form Filling APIs.

The authentication APIs provide the primary endpoints for connecting partners and providers to the Suki Developer Platform. Designed for security and integration, these endpoints allow you to manage user identities and secure your connection to our API gateway.

## Usage scenarios

* Onboard a provider with your partner organization
* Obtain a **Suki token** for a registered provider also known as a **`sdp_suki_token`**
* Fetch the current **JSON Web Key Set**

## What happens when you call the endpoints

* **Register** creates a new user and links it to your partner organization
* **Login** exchanges your partner credentials for a **Suki token** also known as a **`sdp_suki_token`**
* **JWKS** returns the current **JSON Web Key Set**

## Endpoints

# JWKS URL
Source: https://developer.suki.ai/form-filling-api-reference/authentication/jwks

GET /api/auth/.well-known/jwks-pub.json
Public key endpoint for JWT token verification and signature validation

Use this public endpoint to get the <Tooltip href="/Glossary/j">JWKS</Tooltip> (JSON Web Key Set) containing Suki's public keys. Use these keys to verify the signature of any <Tooltip href="/Glossary/j">JWT</Tooltip> issued by Suki, such as the `suki_token`.

This endpoint follows the **RFC 7517** standard.

<Note>
  **Authentication**

This is a public endpoint and does not require authentication.
</Note>

## Key use cases

* **Verify Tokens**: Confirm the authenticity of the `suki_token` you receive from our authentication API.

* **Handle Key Rotation**: Automatically discover new public keys when Suki rotates its signing keys.

* **Maintain Security**: Follow industry best practices for JWT validation.

## Code examples

<Tabs>
  <Tab title="Python">
    ```python theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
    import requests

url = "https://sdp.suki-stage.com/api/auth/.well-known/jwks-pub.json"

response = requests.get(url)

if response.status_code == 200:
        jwks = response.json()
        print("Public keys retrieved successfully")
        print(f"Keys: {jwks}")
    else:
        print(f"Failed to retrieve JWKS: {response.status_code}")
    ```
  </Tab>

if (response.ok) {
      const jwks = await response.json();
      console.log('Public keys retrieved successfully');
      console.log('Keys:', jwks);
    } else {
      console.error(`Failed to retrieve JWKS: ${response.status}`);
    }
    ```
  </Tab>
</Tabs>

# Login
Source: https://developer.suki.ai/form-filling-api-reference/authentication/login

POST /api/v1/auth/login
Authenticate healthcare provider and obtain access token for API usage

Use this endpoint to authenticate a <Tooltip href="/Glossary/p">provider</Tooltip>. On a successful request, this endpoint returns a <Tooltip href="/Glossary/s">Suki Token</Tooltip> (`suki_token`/`sdp_suki_token`) that you must use to authorize all subsequent API calls for that user.

The `suki_token` is a <Tooltip href="/Glossary/j">JWT</Tooltip> that is valid for **one hour**. It contains the **user**, **organization**, and <Tooltip href="/Glossary/p">Partner</Tooltip> information needed to access Suki services.

<Note>
  If you are using the JWT Bearer/Assertion authentication method, the response may also include an additional `jwt_bearer` field.
</Note>

## Code examples

<Tabs>
  <Tab title="Python">
    ```python theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
    import requests

url = "https://sdp.suki-stage.com/api/v1/auth/login"

payload = {
        "partner_id": "your-partner-id",
        "partner_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
        "provider_id": "provider-123"  # Optional
    }

response = requests.post(url, json=payload)

if response.status_code == 200:
        data = response.json()
        suki_token = data["suki_token"]
        print(f"Authentication successful. Token: {suki_token}")
    else:
        print(f"Authentication failed: {response.status_code}")
        print(response.json())
    ```
  </Tab>

<Tab title="TypeScript">
    ```typescript theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
    const response = await fetch('https://sdp.suki-stage.com/api/v1/auth/login', {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        partner_id: 'your-partner-id',
        partner_token: 'eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...',
        provider_id: 'provider-123' // Optional
      })
    });

if (response.ok) {
      const data = await response.json();
      const sukiToken = data.suki_token;
      console.log(`Authentication successful. Token: ${sukiToken}`);
    } else {
      const error = await response.json();
      console.error(`Authentication failed: ${response.status}`, error);
    }
    ```
  </Tab>
</Tabs>

# Register
Source: https://developer.suki.ai/form-filling-api-reference/authentication/register

POST /api/v1/auth/register
Register new healthcare provider or link existing provider to partner organization

Use this endpoint to register a **new healthcare <Tooltip href="/Glossary/p">provider</Tooltip>** in the Suki platform or to link an **existing provider** to a new **<Tooltip href="/Glossary/p">Partner</Tooltip>**-organization relationship.

This is a **one-time** setup call for each provider within an organization.

## Registration scenarios

This endpoint handles **three** different scenarios depending on the user's status in the Suki system.

| Scenario                          | Condition                                                                 | Actions Taken                                                                                                                            | Response     |
| --------------------------------- | ------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- | ------------ |
| **New User**                      | The provider does not exist in Suki.                                      | • Creates a new organization<br />•  Links your partner account to the organization<br />•  Creates a new user with the provided details | 201 Created  |
| **Existing User, New Link**       | The provider exists but is not yet linked to your partner account.        | • Verifies the user and organization details<br />• Links your partner account to the existing organization                              | 201 Created  |
| **Existing User, Already Linked** | The provider and organization are already linked to your partner account. | • Detects the existing link                                                                                                              | 409 Conflict |

## Code examples

<Tabs>
  <Tab title="Python">
    ```python theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
    import requests

url = "https://sdp.suki-stage.com/api/v1/auth/register"

payload = {
        "partner_id": "your-partner-id",
        "partner_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
        "provider_name": "Dr. John Smith",
        "provider_org_id": "org-123",
        "provider_id": "provider-123",  # Optional
        "provider_specialty": "CARDIOLOGY"  # Optional, defaults to FAMILY_MEDICINE
    }

response = requests.post(url, json=payload)

if response.status_code == 201:
        print("Provider registered successfully")
    elif response.status_code == 409:
        print("Provider already linked to this partner")
    else:
        print(f"Registration failed: {response.status_code}")
        print(response.json())
    ```
  </Tab>

<Tab title="TypeScript">
    ```typescript theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
    const response = await fetch('https://sdp.suki-stage.com/api/v1/auth/register', {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        partner_id: 'your-partner-id',
        partner_token: 'eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...',
        provider_name: 'Dr. John Smith',
        provider_org_id: 'org-123',
        provider_id: 'provider-123', // Optional
        provider_specialty: 'CARDIOLOGY' // Optional, defaults to FAMILY_MEDICINE
      })
    });

if (response.status === 201) {
      console.log('Provider registered successfully');
    } else if (response.status === 409) {
      console.log('Provider already linked to this partner');
    } else {
      const error = await response.json();
      console.error(`Registration failed: ${response.status}`, error);
    }
    ```
  </Tab>
</Tabs>

# Form Filling API Changelog
Source: https://developer.suki.ai/form-filling-api-reference/changelog

Release notes for the Form Filling APIs.

Suki's API versioning policy is based on the semantic versioning standard. For example, in version 1.2.3, 1 is the major version, 2 is the minor version, and 3 is the patch version.

When we release a new API version for new features or bug fixes, we increment one of these three version components depending on the type of change introduced.

<Info icon="info">
  **API version numbering policy**

All Suki REST APIs are currently in `v1` version.

**Release version**

The release version in this changelog page represents the incremental progress. It is not the API version. It tracks new optional fields, performance improvements, new endpoints, and other changes.
</Info>

<Update label="v1.1.0" description="June 2026">
  ### Enhancements

* Suki now supports **Single Auth Token authentication**: your backend can use one shared `partner_token` for all clinicians instead of a per-user token.
    The shared token proves your organization is authorized, but it does not identify who is signed in. If you use this model, you **must** send `sdp_provider_id`
    on every API call so Suki can route each call to the correct clinician.

Learn more in the [Provider authentication](/api-reference/provider-authentication) documentation.

```json JSON theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
  {
      "sdp_suki_token": "your-suki-token", // sdp_suki_token required for all API calls
      // Required with Single Auth Token auth: send sdp_provider_id on Register, Login, and every API call
      "sdp_provider_id": "doc1234567890"
  }
  ```
</Update>

<Update label="v1.0.0" description="May 2026">
  ### New endpoints

We introduced the form filling APIs to enable you to create and manage form-filling sessions, retrieve structured data, submit feedback, and get info about medical
  form templates for nursing use cases and data collection during in-person visits or virtual patient encounters.

* **Form filling APIs**: Added new endpoints to create and manage form-filling sessions, retrieve structured data, submit feedback, and get info about medical form templates.

* <Badge>POST</Badge> [/api/v1/form-filling/session/create](/form-filling-api-reference/form-filling-sessions/create)
    * <Badge>POST</Badge> [/api/v1/form-filling/session//context](/form-filling-api-reference/form-filling-sessions/context)
    * <Badge>PATCH</Badge> [/api/v1/form-filling/session//context](/form-filling-api-reference/form-filling-sessions/update-context)
    * <Badge>POST</Badge> [/api/v1/form-filling/session//end](/form-filling-api-reference/form-filling-sessions/end)
    * <Badge>GET</Badge> [/api/v1/form-filling/session//status](/form-filling-api-reference/form-filling-sessions/status)
    * <Badge>GET</Badge> [/api/v1/form-filling/session//structured-data](/form-filling-api-reference/form-filling-sessions/structured-data)
    * <Badge>POST</Badge> [/api/v1/form-filling/session///feedback](/form-filling-api-reference/form-filling-sessions/feedback)
    * <Badge>GET</Badge> [/api/v1/info/suki-medical-form-templates](/form-filling-api-reference/info/suki-medical-form-templates)

Learn more about the form filling APIs in the [Form Filling API overview](/form-filling-api-reference/overview).
</Update>

# Form Filling Content Retrieval
Source: https://developer.suki.ai/form-filling-api-reference/form-filling-content-retrieval

Retrieve content from a form-filling session

The form filling content retrieval APIs provide endpoints to retrieve content from a form-filling session. These endpoints are used to retrieve the content from a form-filling session.

## Usage scenarios

* Knowing the status of the form-filling session like if it is running, completed, or failed
* Retrieving the EHR compatible structured data from a form-filling session after the session is complete

## Endpoints

# Form Filling Feedback
Source: https://developer.suki.ai/form-filling-api-reference/form-filling-feedback

Submit feedback for a form-filling session

The form-filling feedback APIs let you submit feedback for a **form-filling ambient session**. These APIs use **SubmitFormFillingFeedback**, which is separate from the ambient **SubmitFeedback** flow.

## Usage scenarios

* Submit feedback for a generated medical form in a form-filling session

## Session requirements

* `ambient_session_id` must reference a **form-filling** session with the underlying job type `FORM_FILLING_ORCHESTRATION`.
* If the session is not a form-filling session, the API returns a `FailedPrecondition` error.

## Entity types

When `entity` is `AMBIENT_GENERATED_MEDICAL_FORM`, you must provide `feedback_metadata.form_id` with the generated medical form instance ID. The API uses this ID to load the form details before forwarding the request to the feedback service.

## Rating system

Inside **`feedback`**, the `ratingFeedback` object provides quantitative feedback. It includes the following fields:

* `min_rating`: The minimum rating value (e.g., 0).
* `max_rating`: The maximum rating value.
* `rating`: The actual rating you provide within the min-max range.

<Note>
  Configure the rating scale by setting the `min_rating` and `max_rating` values. The range is **inclusive**, so both the `min_rating` and `max_rating` values are valid ratings.

For example:

```json theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
  {
    "feedback": {
      "ratingFeedback": {
        "min_rating": 1,
        "max_rating": 5,
        "rating": 4
      }
    },
    "feedback_metadata": {
      "form_id": "018f94e8-7aa8-7bfd-bc83-046262001234"
    }
  }
  ```
</Note>

## Endpoints

# Form Filling Info
Source: https://developer.suki.ai/form-filling-api-reference/form-filling-info

Get info about a form-filling session

The form filling info APIs provide endpoints to get info about medical form templates. These endpoints are used to get info about medical form templates.

## Usage scenarios

* Getting info about medical form templates

## Supported medical form template types

Medical form templates are predefined templates that are used to collect information from the patient. Suki supports the following `MedicalFormType` values:

* `SKIN_ASSESSMENT` - Skin assessment form template
* `NEURO_ASSESSMENT` - Neuro assessment form template
* `VITALS_ASSESSMENT` - Vital signs assessment form template
* `RESPIRATORY_ASSESSMENT` - Respiratory assessment form template
* `GENITO_URINARY_ASSESSMENT` - Genitourinary assessment form template
* `GASTRO_INTESTINAL_ASSESSMENT` - Gastrointestinal assessment form template
* `CARDIAC_ASSESSMENT` - Cardiac assessment form template
* `MSK_ASSESSMENT` - Musculoskeletal assessment form template
* `IO_ASSESSMENT` - Intake and output assessment form template

These templates streamline the process of collecting information from the patient by providing a predefined set of questions and answers.

## Endpoints

# Form Filling Session Management
Source: https://developer.suki.ai/form-filling-api-reference/form-filling-session-management

Create and manage form-filling sessions: context, status, structured data, feedback, and end session

The form filling session management APIs provide endpoints to create and manage form-filling sessions. These endpoints are used to create a form-filling session, seed the session context, update the session context, check the session status, retrieve the structured data, submit feedback, and end the session.

## Usage scenarios

* Create a new form-filling ambient session for your patient encounter during in-person visits or virtual visits
* Seed the session context with the patient information, provider details, and diagnosis codes
* Update the session context with the patient information, provider details, and diagnosis codes
* End the session when the patient encounter is complete

## Endpoints

# Seed Form Filling Session Context
Source: https://developer.suki.ai/form-filling-api-reference/form-filling-sessions/context

POST /api/v1/form-filling/session/{ambient_session_id}/context
Seed form-filling session context for a form-filling session using the form-filling URL binding

Use this endpoint to provide (seed) the
<Tooltip href="/Glossary/s">session context</Tooltip> for form-filling sessions. Providing detailed context helps Suki generate a more accurate and relevant <Tooltip href="/Glossary/c">clinical note</Tooltip>.

<Note>
  The body of this request is optional. However, if you decide to provide context, you must provide **valid values** for the properties.
</Note>

## Code examples

<Note>
  The code examples below use placeholders and the stage host `sdp.suki-stage.com` only as **examples**.
  For credentials, base URLs, where to run Python or TypeScript, CORS, and **cURL**, refer to [Using code examples in your integration](/api-reference/api-guidelines#using-code-examples-in-your-integration) in the **API Reference Guidelines**.
</Note>

<Tabs>
  <Tab title="Python">
    ```python expandable theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
    from typing import Any, Optional, TypedDict

import requests

BASE_URL = "https://sdp.suki-stage.com"

class FormFillingMetadata(TypedDict):
        form_template_id: str

class FormFillingContext(TypedDict):
        values: list[FormFillingMetadata]

class FormFillingSessionContext(TypedDict, total=False):
        # Optional, but if provided, `values` and `form_template_id` are required.
        form_filling: FormFillingContext

class ApiHttpError(RuntimeError):
        def __init__(self, status: int, url: str, detail: str) -> None:
            super().__init__(f"HTTP {status} {url}: {detail}")
            self.status = status
            self.url = url

def _post_json_expect(
        url: str,
        headers: dict[str, str],
        payload: dict[str, Any],
        expect_status: int,
    ) -> Optional[dict[str, Any]]:
        r = requests.post(url, json=payload, headers=headers, timeout=60)
        if r.status_code == expect_status:
            # OpenAPI does not define a response body for 200 here, so treat it as optional.
            if not r.text:
                return None
            try:
                data = r.json()
            except ValueError:
                return None
            return data if isinstance(data, dict) else None

detail = ""
        try:
            err = r.json()
            if isinstance(err, dict) and isinstance(err.get("message"), str):
                detail = err["message"]
        except ValueError:
            detail = (r.text or "")[:500]
        raise ApiHttpError(r.status_code, url, detail or "(no body)")

def login_for_suki_token(partner_id: str, partner_token: str, *, provider_id: Optional[str] = None) -> str:
        url = f"{BASE_URL}/api/v1/auth/login"
        body: dict[str, Any] = {"partner_id": partner_id, "partner_token": partner_token}
        if provider_id is not None:
            body["provider_id"] = provider_id
        r = requests.post(url, json=body, headers={"Content-Type": "application/json"}, timeout=60)
        if r.status_code != 200:
            raise ApiHttpError(r.status_code, url, (r.text or "")[:500] or "(no body)")
        data = r.json()
        token = data.get("suki_token") if isinstance(data, dict) else None
        if not isinstance(token, str) or not token:
            raise ValueError(f"{url}: 200 response missing suki_token")
        return token

def seed_form_filling_session_context(
        suki_token: str,
        ambient_session_id: str,
        body: Optional[FormFillingSessionContext] = None,
    ) -> None:
        url = f"{BASE_URL}/api/v1/form-filling/session/{ambient_session_id}/context"
        headers = {"sdp_suki_token": suki_token, "sdp_provider_id": "<sdp_provider_id>", "Content-Type": "application/json"}
        _post_json_expect(url, headers, dict(body or {}), 200)

if __name__ == "__main__":
        try:
            token = login_for_suki_token("<partner_id>", "<partner_token>")

# Body is optional. Example shows one required form template ID inside `form_filling.values`.
            seed_form_filling_session_context(
                token,
                ambient_session_id="<ambient_session_id>",
                body={
                    "form_filling": {
                        "values": [
                            {"form_template_id": "019d4cdc-9319-7d81-ae2e-fd6de7f1b4f0"},
                        ]
                    }
                },
            )
            print("Context seeded.")
        except (ApiHttpError, ValueError) as e:
            print(e)
    ```
  </Tab>

<Tab title="TypeScript">
    ```typescript expandable theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
    const BASE_URL = "https://sdp.suki-stage.com";

type AuthenticationRequest = {
      partner_id: string;
      partner_token: string;
      provider_id?: string;
    };

type AuthenticationResponse = { suki_token: string };

type FormFillingMetadata = { form_template_id: string };
    type FormFillingContext = { values: FormFillingMetadata[] };
    type FormFillingSessionContext = {
      // Optional, but if provided, `values` and `form_template_id` are required.
      form_filling?: FormFillingContext;
    };

async function postJsonExpectOptional(
      url: string,
      init: RequestInit,
      expectStatus: number,
    ): Promise<{ json?: Record<string, unknown>; text?: string }> {
      const res = await fetch(url, init);
      const text = await res.text();

if (res.status !== expectStatus) {
        let msg = text.slice(0, 500);
        try {
          const data: unknown = text ? JSON.parse(text) : null;
          if (data && typeof data === "object" && "message" in data) {
            msg = String((data as { message?: string }).message ?? msg);
          }
        } catch {
          // keep raw text
        }
        throw new Error(`HTTP ${res.status} ${url}: ${msg || "(no body)"}`);
      }

// OpenAPI does not define a response body for 200 here, so treat it as optional.
      if (!text) return {};

try {
        const data: unknown = JSON.parse(text);
        if (data && typeof data === "object") return { json: data as Record<string, unknown>, text };
        return { text };
      } catch {
        return { text };
      }
    }

async function loginForSukiToken(body: AuthenticationRequest): Promise<string> {
      const url = `${BASE_URL}/api/v1/auth/login`;
      const { json } = await postJsonExpectOptional(
        url,
        {
          method: "POST",
          headers: { "Content-Type": "application/json" },
          body: JSON.stringify(body),
        },
        200,
      );

const token = json?.suki_token;
      if (typeof token !== "string" || !token) throw new Error(`${url}: missing suki_token`);
      return token;
    }

async function seedFormFillingSessionContext(
      sukiToken: string,
      ambientSessionId: string,
      body: FormFillingSessionContext = {},
    ): Promise<void> {
      const url = `${BASE_URL}/api/v1/form-filling/session/${ambientSessionId}/context`;
      await postJsonExpectOptional(
        url,
        {
          method: "POST",
          headers: {
            sdp_suki_token: sukiToken, sdp_provider_id: "<sdp_provider_id>",
            "Content-Type": "application/json",
          },
          body: JSON.stringify(body),
        },
        200,
      );
    }

async function main(): Promise<void> {
      try {
        const token = await loginForSukiToken({
          partner_id: "<partner_id>",
          partner_token: "<partner_token>",
        });

// Body is optional. Example shows one required form template ID inside `form_filling.values`.
        await seedFormFillingSessionContext(token, "<ambient_session_id>", {
          form_filling: {
            values: [{ form_template_id: "019d4cdc-9319-7d81-ae2e-fd6de7f1b4f0" }],
          },
        });

console.log("Context seeded.");
      } catch (e) {
        console.error(e instanceof Error ? e.message : e);
      }
    }

void main();
    ```
  </Tab>
</Tabs>

# Create Form Filling Session
Source: https://developer.suki.ai/form-filling-api-reference/form-filling-sessions/create

POST /api/v1/form-filling/session/create
Create a form-filling session and obtain an ambient session identifier for subsequent calls

Use this endpoint to create a form-filling ambient session. Suki will return a from filling ambient session identifier (id) in response for subsequent calls.

You must use the returned session identifier (id) to perform other operations for that session for example checking session status, retrieving structured data, submitting feedback, ending the session, and more.

<Note>
  **Important**:

In the documentation, both the Form Filling session ID and the [Suki Ambient API session ID](/api-reference/ambient-sessions/create) are referred to as `ambient_session_id`. However, these are two different identifiers and should not be treated as the same value.
</Note>

## Code examples

<Tabs>
  <Tab title="Python">
    ```python expandable theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
    from typing import Any, Optional, TypedDict, cast

import requests

BASE_URL = "https://sdp.suki-stage.com"

class CreateFormFillingSessionRequest(TypedDict, total=False):
        ambient_session_id: str
        correlation_id: str

class CreateFormFillingSessionResponse(TypedDict):
        ambient_session_id: str

class ApiHttpError(RuntimeError):
        """Wrong HTTP status; OpenAPI errors usually include JSON with message + code."""

def __init__(self, status: int, url: str, detail: str) -> None:
            super().__init__(f"HTTP {status} {url}: {detail}")
            self.status = status
            self.url = url

def _post_json_expect(url: str, headers: dict[str, str], payload: dict[str, Any], expect_status: int) -> dict[str, Any]:
        r = requests.post(url, json=payload, headers=headers, timeout=60)
        if r.status_code == expect_status:
            data = r.json()
            if isinstance(data, dict):
                return data
            raise ApiHttpError(expect_status, url, "response JSON was not an object")

def login_for_suki_token(partner_id: str, partner_token: str, *, provider_id: Optional[str] = None) -> str:
        """POST /api/v1/auth/login -> suki_token (HTTP 200)."""
        url = f"{BASE_URL}/api/v1/auth/login"
        body: dict[str, Any] = {"partner_id": partner_id, "partner_token": partner_token}
        if provider_id is not None:
            body["provider_id"] = provider_id
        data = _post_json_expect(url, {"Content-Type": "application/json"}, body, 200)
        token = data.get("suki_token")
        if not isinstance(token, str) or not token:
            raise ValueError(f"{url}: 200 response missing suki_token")
        return token

def create_form_filling_session(
        suki_token: str,
        body: Optional[CreateFormFillingSessionRequest] = None,
    ) -> CreateFormFillingSessionResponse:
        """POST /api/v1/form-filling/session/create (sdp_suki_token header required). HTTP 201."""
        url = f"{BASE_URL}/api/v1/form-filling/session/create"
        headers = {"sdp_suki_token": suki_token, "sdp_provider_id": "<sdp_provider_id>", "Content-Type": "application/json"}
        data = _post_json_expect(url, headers, dict(body or {}), 201)
        sid = data.get("ambient_session_id")
        if not isinstance(sid, str) or not sid:
            raise ValueError(f"{url}: 201 response missing ambient_session_id")
        return cast(CreateFormFillingSessionResponse, {"ambient_session_id": sid})

if __name__ == "__main__":
        try:
            token = login_for_suki_token("<partner_id>", "<partner_token>")
            session = create_form_filling_session(token, {})
            print(session["ambient_session_id"])
        except (ApiHttpError, ValueError) as e:
            print(e)
    ```
  </Tab>

<Tab title="TypeScript">
    ```typescript expandable theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
    const BASE_URL = "https://sdp.suki-stage.com";

type AuthenticationRequest = {
      partner_id: string;
      partner_token: string;
      provider_id?: string;
    };

type AuthenticationResponse = { suki_token: string };

type CreateFormFillingSessionRequest = {
      ambient_session_id?: string;
      correlation_id?: string;
    };

type CreateFormFillingSessionResponse = { ambient_session_id: string };

/** POST helper: reads body once, checks status, returns parsed JSON object on success. */
    async function postJsonExpect<T extends Record<string, unknown>>(
      url: string,
      init: RequestInit,
      expectStatus: number,
    ): Promise<T> {
      const res = await fetch(url, init);
      const text = await res.text();
      let data: unknown;
      try {
        data = text ? JSON.parse(text) : {};
      } catch {
        throw new Error(`HTTP ${res.status} ${url}: invalid JSON`);
      }
      if (res.status !== expectStatus) {
        const msg =
          data && typeof data === "object" && "message" in data
            ? String((data as { message?: string }).message)
            : text.slice(0, 500);
        throw new Error(`HTTP ${res.status} ${url}: ${msg || "(no body)"}`);
      }
      if (!data || typeof data !== "object") {
        throw new Error(`${url}: expected JSON object`);
      }
      return data as T;
    }

async function loginForSukiToken(body: AuthenticationRequest): Promise<string> {
      const url = `${BASE_URL}/api/v1/auth/login`;
      const data = await postJsonExpect<AuthenticationResponse>(url, {
        method: "POST",
        headers: { "Content-Type": "application/json" },
        body: JSON.stringify(body),
      }, 200);
      if (!data.suki_token) throw new Error(`${url}: missing suki_token`);
      return data.suki_token;
    }

async function createFormFillingSession(
      sukiToken: string,
      body: CreateFormFillingSessionRequest = {},
    ): Promise<CreateFormFillingSessionResponse> {
      const url = `${BASE_URL}/api/v1/form-filling/session/create`;
      const data = await postJsonExpect<CreateFormFillingSessionResponse>(url, {
        method: "POST",
        headers: {
          sdp_suki_token: sukiToken, sdp_provider_id: "<sdp_provider_id>",
          "Content-Type": "application/json",
        },
        body: JSON.stringify(body),
      }, 201);
      if (!data.ambient_session_id) throw new Error(`${url}: missing ambient_session_id`);
      return data;
    }

async function main(): Promise<void> {
      try {
        const token = await loginForSukiToken({
          partner_id: "<partner_id>",
          partner_token: "<partner_token>",
        });
        const session = await createFormFillingSession(token, {});
        console.log(session.ambient_session_id);
      } catch (e) {
        console.error(e instanceof Error ? e.message : e);
      }
    }

void main();
    ```
  </Tab>
</Tabs>

# End Form Filling Session
Source: https://developer.suki.ai/form-filling-api-reference/form-filling-sessions/end

POST /api/v1/form-filling/session/{ambient_session_id}/end
End a form-filling session

Use this endpoint to end a form-filling ambient session. Use your session identifier to identify the session you want to end.

<Note>
  At least **one template must be provided** in form-filling session context before you end the form-filling ambient session.
</Note>

## Code examples

<Tabs>
  <Tab title="Python">
    ```python expandable theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
    from typing import Any, Optional

import requests

BASE_URL = "https://sdp.suki-stage.com"

class ApiHttpError(RuntimeError):
        """Wrong HTTP status; OpenAPI errors usually include JSON with message + code."""

def __init__(self, status: int, url: str, detail: str) -> None:
            super().__init__(f"HTTP {status} {url}: {detail}")
            self.status = status
            self.url = url

def _post_expect_json_object(url: str, headers: dict[str, str], expect_status: int) -> dict[str, Any]:
        r = requests.post(url, headers=headers, timeout=60)
        if r.status_code == expect_status:
            data = r.json()
            if isinstance(data, dict):
                return data
            raise ApiHttpError(expect_status, url, "response JSON was not an object")

def end_form_filling_session(suki_token: str, ambient_session_id: str) -> None:
        """POST /api/v1/form-filling/session/{ambient_session_id}/end (sdp_suki_token header required). HTTP 200."""
        url = f"{BASE_URL}/api/v1/form-filling/session/{ambient_session_id}/end"
        headers = {"sdp_suki_token": suki_token, "sdp_provider_id": "<sdp_provider_id>"}
        _post_expect_json_object(url, headers, 200)

if __name__ == "__main__":
        try:
            end_form_filling_session("YOUR_SUKI_TOKEN", "YOUR_AMBIENT_SESSION_ID")
            print("Session ended.")
        except (ApiHttpError, ValueError) as e:
            print(e)
    ```
  </Tab>

<Tab title="TypeScript">
    ```typescript expandable theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
    const BASE_URL = "https://sdp.suki-stage.com";

class ApiHttpError extends Error {
      status: number;
      url: string;
      constructor(status: number, url: string, detail: string) {
        super(`HTTP ${status} ${url}: ${detail}`);
        this.status = status;
        this.url = url;
      }
    }

async function postExpectJsonObject(url: string, headers: Record<string, string>, expectStatus: number) {
      const res = await fetch(url, { method: "POST", headers });
      const text = await res.text();
      const json = text ? JSON.parse(text) : {};

if (res.status !== expectStatus) {
        const msg = typeof json?.message === "string" ? json.message : text?.slice(0, 500) || "(no body)";
        throw new ApiHttpError(res.status, url, msg);
      }
      if (json && typeof json === "object" && !Array.isArray(json)) return json as Record<string, unknown>;
      throw new ApiHttpError(res.status, url, "response JSON was not an object");
    }

export async function endFormFillingSession(sukiToken: string, ambientSessionId: string): Promise<void> {
      const url = `${BASE_URL}/api/v1/form-filling/session/${ambientSessionId}/end`;
      await postExpectJsonObject(url, { sdp_suki_token: sukiToken, sdp_provider_id: "<sdp_provider_id>" }, 200);
    }

// Example usage
    await endFormFillingSession("YOUR_SUKI_TOKEN", "YOUR_AMBIENT_SESSION_ID");
    console.log("Session ended.");
    ```
  </Tab>
</Tabs>

# Form Filling Session Feedback
Source: https://developer.suki.ai/form-filling-api-reference/form-filling-sessions/feedback

POST /api/v1/form-filling/session/{ambient_session_id}/{entity}/feedback
Submit feedback for a form-filling session entity

Use this endpoint to submit feedback for a **form-filling ambient session**. This endpoint calls **SubmitFormFillingFeedback**, which is separate from the ambient **SubmitFeedback** API.

## Requirements

* **`ambient_session_id`** must reference a **form-filling** session with the underlying job type **`FORM_FILLING_ORCHESTRATION`**. If the session type does not match, the API returns a **`FailedPrecondition`** error.

* Set **`entity`** to **`AMBIENT_GENERATED_MEDICAL_FORM`** when submitting feedback for a generated medical form.

* **`feedback_metadata.form_id`** is required when **`entity`** is **`AMBIENT_GENERATED_MEDICAL_FORM`**. Pass the generated medical form instance ID. The API uses this ID to load the form details before forwarding the request to the feedback service.

On success, the API returns a `feedback_id`. The value matches the provided `ambient_session_id`, consistent with the ambient feedback API behavior.

For rating scale guidance, refer to [Form filling feedback](/form-filling-api-reference/form-filling-feedback#rating-system) section.

## Code examples

<Tabs>
  <Tab title="Python">
    ```python expandable theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
    from typing import Any, TypedDict, cast

import requests

BASE_URL = "https://sdp.suki-stage.com"

ENTITY_AMBIENT_GENERATED_MEDICAL_FORM = "AMBIENT_GENERATED_MEDICAL_FORM"

class QuantitativeFeedback(TypedDict, total=False):
        max_rating: int
        min_rating: int
        rating: int

class Feedback(TypedDict, total=False):
        qualitative_comments: str
        ratingFeedback: QuantitativeFeedback

class FeedbackMetadata(TypedDict):
        form_id: str

class FormFillingFeedbackPayload(TypedDict):
        feedback: Feedback
        feedback_metadata: FeedbackMetadata

class SubmitFeedbackResponse(TypedDict):
        feedback_id: str

class ApiHttpError(RuntimeError):
        """Wrong HTTP status; OpenAPI errors usually include JSON with message + code."""

def __init__(self, status: int, url: str, detail: str) -> None:
            super().__init__(f"HTTP {status} {url}: {detail}")
            self.status = status
            self.url = url

def submit_form_filling_feedback(
        suki_token: str,
        ambient_session_id: str,
        entity: str,
        body: FormFillingFeedbackPayload,
    ) -> SubmitFeedbackResponse:
        """POST /api/v1/form-filling/session/{ambient_session_id}/{entity}/feedback (sdp_suki_token header required). HTTP 201."""
        url = f"{BASE_URL}/api/v1/form-filling/session/{ambient_session_id}/{entity}/feedback"
        headers = {"sdp_suki_token": suki_token, "sdp_provider_id": "<sdp_provider_id>", "Content-Type": "application/json"}
        data = _post_json_expect(url, headers, dict(body), 201)
        fid = data.get("feedback_id")
        if not isinstance(fid, str) or not fid:
            raise ValueError(f"{url}: 201 response missing feedback_id")
        return cast(SubmitFeedbackResponse, {"feedback_id": fid})

if __name__ == "__main__":
        try:
            out = submit_form_filling_feedback(
                "YOUR_SUKI_TOKEN",
                "YOUR_AMBIENT_SESSION_ID",
                ENTITY_AMBIENT_GENERATED_MEDICAL_FORM,
                {
                    "feedback": {
                        "qualitative_comments": "Accurate and well-structured form output.",
                        "ratingFeedback": {"min_rating": 1, "max_rating": 5, "rating": 5},
                    },
                    "feedback_metadata": {
                        "form_id": "018f94e8-7aa8-7bfd-bc83-046262001234",
                    },
                },
            )
            print(out["feedback_id"])
        except (ApiHttpError, ValueError) as e:
            print(e)
    ```
  </Tab>

<Tab title="TypeScript">
    ```typescript expandable theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
    const BASE_URL = "https://sdp.suki-stage.com";

const ENTITY_AMBIENT_GENERATED_MEDICAL_FORM = "AMBIENT_GENERATED_MEDICAL_FORM";

type QuantitativeFeedback = {
      max_rating?: number;
      min_rating?: number;
      rating?: number;
    };

type Feedback = {
      qualitative_comments?: string;
      ratingFeedback?: QuantitativeFeedback;
    };

type FeedbackMetadata = {
      form_id: string;
    };

type FormFillingFeedbackPayload = {
      feedback: Feedback;
      feedback_metadata: FeedbackMetadata;
    };

type SubmitFeedbackResponse = { feedback_id: string };

async function postJsonExpectObject(
      url: string,
      headers: Record<string, string>,
      body: Record<string, unknown>,
      expectStatus: number
    ): Promise<Record<string, unknown>> {
      const res = await fetch(url, { method: "POST", headers, body: JSON.stringify(body) });
      const text = await res.text();
      const json = text ? JSON.parse(text) : {};

if (res.status !== expectStatus) {
        const msg = typeof (json as any)?.message === "string" ? (json as any).message : text?.slice(0, 500) || "(no body)";
        throw new ApiHttpError(res.status, url, msg);
      }
      if (json && typeof json === "object" && !Array.isArray(json)) return json as Record<string, unknown>;
      throw new ApiHttpError(res.status, url, "response JSON was not an object");
    }

export async function submitFormFillingFeedback(
      sukiToken: string,
      ambientSessionId: string,
      entity: string,
      body: FormFillingFeedbackPayload
    ): Promise<SubmitFeedbackResponse> {
      const url = `${BASE_URL}/api/v1/form-filling/session/${ambientSessionId}/${entity}/feedback`;
      const data = await postJsonExpectObject(
        url,
        { sdp_suki_token: sukiToken, sdp_provider_id: "<sdp_provider_id>", "Content-Type": "application/json" },
        body as Record<string, unknown>,
        201
      );
      const feedbackId = data.feedback_id;
      if (typeof feedbackId !== "string" || !feedbackId) {
        throw new Error(`${url}: 201 response missing feedback_id`);
      }
      return { feedback_id: feedbackId };
    }

// Example usage
    const out = await submitFormFillingFeedback("YOUR_SUKI_TOKEN", "YOUR_AMBIENT_SESSION_ID", ENTITY_AMBIENT_GENERATED_MEDICAL_FORM, {
      feedback: {
        qualitative_comments: "Accurate and well-structured form output.",
        ratingFeedback: { min_rating: 1, max_rating: 5, rating: 5 },
      },
      feedback_metadata: {
        form_id: "018f94e8-7aa8-7bfd-bc83-046262001234",
      },
    });
    console.log(out.feedback_id);
    ```
  </Tab>
</Tabs>

# Get Form Filling Session Status
Source: https://developer.suki.ai/form-filling-api-reference/form-filling-sessions/status

GET /api/v1/form-filling/session/{ambient_session_id}/status
Poll processing status for a form-filling session

Use this endpoint to know the processing status for a form-filling session. Use your ambient session identifier (id) to identify the session you want to check the status of.

## Form filling session status values

Use the following status values to track session progress:

* **created**: The system creates the form-filling session but does not start it yet.

* **ready**: The form-filling session starts and is ready for audio streaming.

* **running**: The form-filling session processes audio and generates content.

* **staged**: The form-filling session is staged and is ready to be processed.

* **aborted**: The user or client cancels the form-filling session.

* **failed**: An error stops the form-filling session during processing.

* **completed**: The form-filling session completes successfully and generates the final content.

## Code examples

<Tabs>
  <Tab title="Python">
    ```python expandable theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
    from typing import Any, Literal, TypedDict

import requests

BASE_URL = "https://sdp.suki-stage.com"

StatusValue = Literal[
        "created",
        "ready",
        "running",
        "paused",
        "aborted",
        "failed",
        "completed",
        "staged",
    ]

class StatusResponse(TypedDict):
        status: StatusValue

class ApiHttpError(RuntimeError):
        """Wrong HTTP status; OpenAPI errors usually include JSON with message + code."""

def __init__(self, status: int, url: str, detail: str) -> None:
            super().__init__(f"HTTP {status} {url}: {detail}")
            self.status = status
            self.url = url

def _get_expect_json_object(url: str, headers: dict[str, str], expect_status: int) -> dict[str, Any]:
        r = requests.get(url, headers=headers, timeout=60)
        if r.status_code == expect_status:
            data = r.json()
            if isinstance(data, dict):
                return data
            raise ApiHttpError(expect_status, url, "response JSON was not an object")

def get_form_filling_session_status(suki_token: str, ambient_session_id: str) -> StatusResponse:
        """GET /api/v1/form-filling/session/{ambient_session_id}/status (sdp_suki_token header required). HTTP 200."""
        url = f"{BASE_URL}/api/v1/form-filling/session/{ambient_session_id}/status"
        data = _get_expect_json_object(url, {"sdp_suki_token": suki_token, "sdp_provider_id": "<sdp_provider_id>"}, 200)
        status = data.get("status")
        if not isinstance(status, str) or not status:
            raise ValueError(f"{url}: 200 response missing status")
        return {"status": status}  # type: ignore[return-value]

if __name__ == "__main__":
        try:
            out = get_form_filling_session_status("YOUR_SUKI_TOKEN", "YOUR_AMBIENT_SESSION_ID")
            print(out["status"])
        except (ApiHttpError, ValueError) as e:
            print(e)
    ```
  </Tab>

<Tab title="TypeScript">
    ```typescript expandable theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
    const BASE_URL = "https://sdp.suki-stage.com";

type StatusResponse = { status: StatusValue };

async function getExpectJsonObject(url: string, headers: Record<string, string>, expectStatus: number) {
      const res = await fetch(url, { method: "GET", headers });
      const text = await res.text();
      const json = text ? JSON.parse(text) : {};

export async function getFormFillingSessionStatus(sukiToken: string, ambientSessionId: string): Promise<StatusResponse> {
      const url = `${BASE_URL}/api/v1/form-filling/session/${ambientSessionId}/status`;
      const data = await getExpectJsonObject(url, { sdp_suki_token: sukiToken, sdp_provider_id: "<sdp_provider_id>" }, 200);
      const status = data.status;
      if (typeof status !== "string" || !status) {
        throw new Error(`${url}: 200 response missing status`);
      }
      return { status: status as StatusValue };
    }

// Example usage
    const out = await getFormFillingSessionStatus("YOUR_SUKI_TOKEN", "YOUR_AMBIENT_SESSION_ID");
    console.log(out.status);
    ```
  </Tab>
</Tabs>

# Get Form Filling Structured Data
Source: https://developer.suki.ai/form-filling-api-reference/form-filling-sessions/structured-data

GET /api/v1/form-filling/session/{ambient_session_id}/structured-data
Retrieve structured medical form data for a form-filling session

Use this endpoint to get the cumulative <Tooltip href="/Glossary/s">structured data</Tooltip> associated with the specified <Tooltip href="/Glossary/a">form-filling ambient session</Tooltip>.

You receive the structured data in the response of this endpoint. The response contains the following fields:

* **generated\_values**: Form data with template IDs for which Suki was able to generate the structured data
* **non\_generated\_values**: Form\_Template\_IDs for which Suki was not able to generate the structured data.

## Code examples

<Tabs>
  <Tab title="Python">
    ```python expandable theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
    from typing import Any, TypedDict, cast

import requests

BASE_URL = "https://sdp.suki-stage.com"

class MedicalFormInstanceSummary(TypedDict, total=False):
        form_template_id: str

class FormFillingStructuredData(TypedDict, total=False):
        generated_values: list[MedicalFormInstanceSummary]
        non_generated_values: list[MedicalFormInstanceSummary]

class FormFillingStructuredDataResponse(TypedDict):
        structured_data: FormFillingStructuredData

class ApiHttpError(RuntimeError):
        """Wrong HTTP status; OpenAPI errors usually include JSON with message + code."""

def __init__(self, status: int, url: str, detail: str) -> None:
            super().__init__(f"HTTP {status} {url}: {detail}")
            self.status = status
            self.url = url

def get_form_filling_structured_data(suki_token: str, ambient_session_id: str) -> FormFillingStructuredDataResponse:
        """GET /api/v1/form-filling/session/{ambient_session_id}/structured-data (sdp_suki_token header required). HTTP 200."""
        url = f"{BASE_URL}/api/v1/form-filling/session/{ambient_session_id}/structured-data"
        data = _get_expect_json_object(url, {"sdp_suki_token": suki_token, "sdp_provider_id": "<sdp_provider_id>"}, 200)
        sd = data.get("structured_data")
        if not isinstance(sd, dict):
            raise ValueError(f"{url}: 200 response missing structured_data object")
        return cast(FormFillingStructuredDataResponse, {"structured_data": sd})

if __name__ == "__main__":
        try:
            out = get_form_filling_structured_data("YOUR_SUKI_TOKEN", "YOUR_AMBIENT_SESSION_ID")
            print(out["structured_data"])
        except (ApiHttpError, ValueError) as e:
            print(e)
    ```
  </Tab>

<Tab title="TypeScript">
    ```typescript expandable theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
    const BASE_URL = "https://sdp.suki-stage.com";

type MedicalFormInstanceSummary = {
      form_template_id?: string;
    };

type FormFillingStructuredData = {
      generated_values?: MedicalFormInstanceSummary[];
      non_generated_values?: MedicalFormInstanceSummary[];
    };

type FormFillingStructuredDataResponse = {
      structured_data: FormFillingStructuredData;
    };

export async function getFormFillingStructuredData(
      sukiToken: string,
      ambientSessionId: string
    ): Promise<FormFillingStructuredDataResponse> {
      const url = `${BASE_URL}/api/v1/form-filling/session/${ambientSessionId}/structured-data`;
      const data = await getExpectJsonObject(url, { sdp_suki_token: sukiToken, sdp_provider_id: "<sdp_provider_id>" }, 200);
      const sd = data.structured_data;
      if (!sd || typeof sd !== "object" || Array.isArray(sd)) {
        throw new Error(`${url}: 200 response missing structured_data object`);
      }
      return { structured_data: sd as FormFillingStructuredData };
    }

// Example usage
    const out = await getFormFillingStructuredData("YOUR_SUKI_TOKEN", "YOUR_AMBIENT_SESSION_ID");
    console.log(out.structured_data);
    ```
  </Tab>
</Tabs>

# Update Form Filling Session Context
Source: https://developer.suki.ai/form-filling-api-reference/form-filling-sessions/update-context

PATCH /api/v1/form-filling/session/{ambient_session_id}/context
Partially update form-filling session context using the form-filling URL binding

Use this endpoint to partially update the
<Tooltip href="/Glossary/s">session context</Tooltip>
for form-filling sessions. Providing detailed context helps Suki generate a more accurate and relevant <Tooltip href="/Glossary/c">clinical note</Tooltip>.
This is a **PATCH** operation that allows partial updates to the session context.

<Note>
  The body of this request is optional. However, if you decide to provide context, you must provide **valid values** for the properties.
</Note>

<Tabs>
  <Tab title="Python">
    ```python expandable theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
    from typing import Any, Optional, TypedDict, cast

import requests

BASE_URL = "https://sdp.suki-stage.com"

class FormFillingMetadata(TypedDict):
        form_template_id: str

class FormFillingContext(TypedDict):
        values: list[FormFillingMetadata]

class FormFillingUpdateContextRequest(TypedDict, total=False):
        form_filling: FormFillingContext

class FormFillingReturnedContext(TypedDict, total=False):
        form_filling: FormFillingContext

class FormFillingUpdateContextResponse(TypedDict):
        context: FormFillingReturnedContext

def _patch_json_expect(
        url: str,
        headers: dict[str, str],
        payload: dict[str, Any],
        expect_status: int,
    ) -> dict[str, Any]:
        r = requests.patch(url, json=payload, headers=headers, timeout=60)
        if r.status_code == expect_status:
            data = r.json()
            if isinstance(data, dict):
                return data
            raise ApiHttpError(expect_status, url, "response JSON was not an object")

def update_form_filling_session_context(
        suki_token: str,
        ambient_session_id: str,
        body: FormFillingUpdateContextRequest,
    ) -> FormFillingUpdateContextResponse:
        """PATCH /api/v1/form-filling/session/{ambient_session_id}/context. HTTP 200 returns FormFillingUpdateContextResponse."""
        url = f"{BASE_URL}/api/v1/form-filling/session/{ambient_session_id}/context"
        headers = {"sdp_suki_token": suki_token, "sdp_provider_id": "<sdp_provider_id>", "Content-Type": "application/json"}
        data = _patch_json_expect(url, headers, dict(body), 200)
        ctx = data.get("context")
        if not isinstance(ctx, dict):
            raise ValueError(f"{url}: 200 response missing context")
        return cast(FormFillingUpdateContextResponse, {"context": cast(FormFillingReturnedContext, ctx)})

if __name__ == "__main__":
        try:
            token = login_for_suki_token("<partner_id>", "<partner_token>")

out = update_form_filling_session_context(
                token,
                ambient_session_id="<ambient_session_id>",
                body={
                    "form_filling": {
                        "values": [
                            {"form_template_id": "019d4cdc-9319-7d81-ae2e-fd6de7f1b4f0"},
                        ]
                    }
                },
            )
            form_filling = out["context"].get("form_filling")
            print(form_filling)
        except (ApiHttpError, ValueError) as e:
            print(e)
    ```
  </Tab>

<Tab title="TypeScript">
    ```typescript expandable theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
    const BASE_URL = "https://sdp.suki-stage.com";

type FormFillingMetadata = { form_template_id: string };
    type FormFillingContext = { values: FormFillingMetadata[] };
    type FormFillingUpdateContextRequest = { form_filling?: FormFillingContext };
    type FormFillingReturnedContext = { form_filling?: FormFillingContext };
    type FormFillingUpdateContextResponse = { context: FormFillingReturnedContext };

async function patchJsonExpectObject(
      url: string,
      init: RequestInit,
      expectStatus: number,
    ): Promise<Record<string, unknown>> {
      const res = await fetch(url, init);
      const text = await res.text();

if (res.status !== expectStatus) {
        let msg = text.slice(0, 500);
        try {
          const data: unknown = text ? JSON.parse(text) : null;
          if (data && typeof data === "object" && "message" in data) {
            msg = String((data as { message?: string }).message ?? msg);
          }
        } catch {
          // keep raw text
        }
        throw new ApiHttpError(res.status, url, msg || "(no body)");
      }

if (!text) throw new ApiHttpError(res.status, url, "(empty body)");
      const data: unknown = JSON.parse(text);
      if (data && typeof data === "object" && !Array.isArray(data)) {
        return data as Record<string, unknown>;
      }
      throw new ApiHttpError(res.status, url, "response JSON was not an object");
    }

async function loginForSukiToken(body: {
      partner_id: string;
      partner_token: string;
      provider_id?: string;
    }): Promise<string> {
      const url = `${BASE_URL}/api/v1/auth/login`;
      const json = await patchJsonExpectObject(
        url,
        {
          method: "POST",
          headers: { "Content-Type": "application/json" },
          body: JSON.stringify(body),
        },
        200,
      );
      const token = json.suki_token;
      if (typeof token !== "string" || !token) throw new Error(`${url}: missing suki_token`);
      return token;
    }

async function updateFormFillingSessionContext(
      sukiToken: string,
      ambientSessionId: string,
      body: FormFillingUpdateContextRequest,
    ): Promise<FormFillingUpdateContextResponse> {
      const url = `${BASE_URL}/api/v1/form-filling/session/${ambientSessionId}/context`;
      const json = await patchJsonExpectObject(
        url,
        {
          method: "PATCH",
          headers: {
            sdp_suki_token: sukiToken, sdp_provider_id: "<sdp_provider_id>",
            "Content-Type": "application/json",
          },
          body: JSON.stringify(body),
        },
        200,
      );
      const context = json.context;
      if (!context || typeof context !== "object" || Array.isArray(context)) {
        throw new Error(`${url}: 200 response missing context`);
      }
      return { context: context as FormFillingReturnedContext };
    }

async function main(): Promise<void> {
      try {
        const token = await loginForSukiToken({
          partner_id: "<partner_id>",
          partner_token: "<partner_token>",
        });

const out = await updateFormFillingSessionContext(token, "<ambient_session_id>", {
          form_filling: {
            values: [{ form_template_id: "019d4cdc-9319-7d81-ae2e-fd6de7f1b4f0" }],
          },
        });

console.log(out.context.form_filling);
      } catch (e) {
        console.error(e instanceof Error ? e.message : e);
      }
    }

void main();
    ```
  </Tab>
</Tabs>

# Suki Medical Form Templates
Source: https://developer.suki.ai/form-filling-api-reference/info/suki-medical-form-templates

GET /api/v1/info/suki-medical-form-templates
List Suki-defined medical form templates available for form-filling sessions

Use this endpoint to get the list of Suki-defined medical form templates available for form-filling ambient sessions.

## Code examples

<Tabs>
  <Tab title="Python">
    ```python expandable theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
    from typing import Any, TypedDict, cast

import requests

BASE_URL = "https://sdp.suki-stage.com"

class MedicalFormTemplate(TypedDict, total=False):
        description: str
        name: str
        schema: Any
        template_id: str
        type: str

class GetSukiFormTemplatesResponse(TypedDict):
        form_templates: list[MedicalFormTemplate]

class ApiHttpError(RuntimeError):
        """Wrong HTTP status; OpenAPI errors usually include JSON with message + code."""

def __init__(self, status: int, url: str, detail: str) -> None:
            super().__init__(f"HTTP {status} {url}: {detail}")
            self.status = status
            self.url = url

def get_suki_medical_form_templates(suki_token: str) -> GetSukiFormTemplatesResponse:
        """GET /api/v1/info/suki-medical-form-templates (sdp_suki_token header required). HTTP 200."""
        url = f"{BASE_URL}/api/v1/info/suki-medical-form-templates"
        data = _get_expect_json_object(url, {"sdp_suki_token": suki_token, "sdp_provider_id": "<sdp_provider_id>"}, 200)
        ft = data.get("form_templates")
        if not isinstance(ft, list):
            raise ValueError(f"{url}: 200 response missing form_templates array")
        return cast(GetSukiFormTemplatesResponse, {"form_templates": ft})

if __name__ == "__main__":
        try:
            out = get_suki_medical_form_templates("YOUR_SUKI_TOKEN")
            print(len(out["form_templates"]))
        except (ApiHttpError, ValueError) as e:
            print(e)
    ```
  </Tab>

<Tab title="TypeScript">
    ```typescript expandable theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
    const BASE_URL = "https://sdp.suki-stage.com";

type MedicalFormTemplate = {
      description?: string;
      name?: string;
      schema?: unknown;
      template_id?: string;
      type?: string;
    };

type GetSukiFormTemplatesResponse = {
      form_templates: MedicalFormTemplate[];
    };

export async function getSukiMedicalFormTemplates(sukiToken: string): Promise<GetSukiFormTemplatesResponse> {
      const url = `${BASE_URL}/api/v1/info/suki-medical-form-templates`;
      const data = await getExpectJsonObject(url, { sdp_suki_token: sukiToken, sdp_provider_id: "<sdp_provider_id>" }, 200);
      const ft = data.form_templates;
      if (!Array.isArray(ft)) {
        throw new Error(`${url}: 200 response missing form_templates array`);
      }
      return { form_templates: ft as MedicalFormTemplate[] };
    }

// Example usage
    const out = await getSukiMedicalFormTemplates("YOUR_SUKI_TOKEN");
    console.log(out.form_templates.length);
    ```
  </Tab>
</Tabs>

<Note>
  If this endpoint returns an empty list, contact [support](mailto:support@suki.ai).
</Note>

# Form Filling APIs Overview
Source: https://developer.suki.ai/form-filling-api-reference/overview

Introduction to the Suki Form Filling APIs: REST, shared Partner WebSocket audio, webhooks, sessions, and structured medical-form output

Suki provides **REST APIs** that let you add **structured medical form workflows** to your application. The APIs give you full control over your application workflows and user experience while enabling you to capture visit conversations and generate completed forms.

The Form Filling APIs support sessions for both **in-person** and **virtual** encounters. During a session, clinicians collect patient information and receive **structured form output** based on Suki-defined templates. Most operations use <Tooltip>REST</Tooltip> endpoints and return standard [HTTP status codes](/api-reference/https-guidelines).

Visit audio is streamed over the shared Partner <Tooltip>WebSocket</Tooltip> (`GET /ws/stream`) by using your form-filling session ID. <Tooltip>Webhooks</Tooltip> notify your application when processing is complete, which removes the need for continuous polling.

## Key capabilities

The Form Filling APIs expose the capabilities below so you can run voice-driven medical form workflows from template selection through structured output in your EHR or internal systems.

<CardGroup>
  <Card title="Voice-Driven Form Capture" icon="microphone">
    Stream visit audio through the shared Partner WebSocket to generate structured medical forms during in-person and virtual visits.
  </Card>

<Card title="Session Lifecycle Management" icon="waveform">
    Create and manage form-filling sessions, update session context, end visits, and monitor processing status until completion.
  </Card>

<Card title="Medical Form Templates" icon="list">
    Retrieve available Suki medical form templates to support form selection, validation, and clinician workflows in your application.
  </Card>

<Card title="Structured Form Output" icon="table">
    Retrieve generated medical form instances and structured outputs for EHR and downstream clinical workflows.
  </Card>

<Card title="Encounter Context" icon="file-lines">
    Pass patient, provider, and template information as session context when creating or updating active sessions.
  </Card>

<Card title="In-Person and Virtual Visits" icon="video">
    Use the same form-filling workflow for in-person and telehealth encounters while keeping control of the capture experience in your UI.
  </Card>

<Card title="Webhook Notifications" icon="bell">
    Receive webhook events when form processing is complete so your backend can respond without relying only on polling.
  </Card>

<Card title="Session Feedback" icon="comment">
    Collect clinician feedback and optional ratings for generated structured data to help measure form quality and user satisfaction.
  </Card>
</CardGroup>

## Requirements

Before you can use the Form Filling APIs, you need to meet the following requirements:

* You must be a Suki partner. Learn more about how to become a Suki partner in the [Partner onboarding](/documentation/partner-onboarding) documentation.
* HTTP/2.0 compliant authentication system (e.g. OAuth 2.0, JWT, etc.).
* JWT tokens with consistent user identifiers (e.g. `sub`, `email`, `userId`, etc.).
* Publicly accessible JWKS endpoint for token verification.

## What you can build

Use the Form Filling APIs to build custom workflows for voice-driven medical form capture. Control how sessions are created and ended, how context is supplied, how audio is streamed, and how structured outputs are presented or saved in your product.

You can align capture with:

* Intake and assessments
* Nursing and clinician workflows
* Medication reviews
* In-person or telehealth visits etc.

Implement your own logic for session lifecycle, structured field review, editing before save, and downstream handoff, and connect to your EHR, telehealth stack, or internal systems using the Form Filling REST APIs, the Partner WebSocket stream, and optional webhooks.

### Common use cases

<CardGroup>
  <Card title="Capture forms during in-person visits" icon="user">
    Clinicians select a form type, start recording, conduct the visit in the room, then generate a populated form for review and save to the patient record.
  </Card>

<Card title="Fill forms in virtual video visits" icon="video">
    Clinicians join a telehealth visit, start recording, collect verbal responses, then generate a digital form for verification and submission.
  </Card>

<Card title="Run template-driven sessions" icon="list">
    Discover Suki-defined templates via the medical form templates API, bind template choices in session context, and retrieve structured instances after processing.
  </Card>
</CardGroup>

## API versioning

All endpoints use the `/api/v1/` prefix. **v1** is the stable version. Non-breaking changes may ship without a major version jump. For policies and migration, refer to [API guidelines](/api-reference/api-guidelines#version-management).

<Note>
  These APIs may include Early Access features. If you are unsure what is enabled for your account, contact your Suki representative.
</Note>

## Available APIs

The following groups cover authentication, session lifecycle, retrieval, feedback, and template discovery for form-filling integrations.

<CardGroup>
  <Card title="Authentication" icon="key" href="/form-filling-api-reference/authentication">
    Endpoints for authentication and authorization.
  </Card>

<Card title="Session Management" icon="waveform" href="/form-filling-api-reference/form-filling-session-management">
    Endpoints for creating, managing, and ending form-filling sessions.
  </Card>

<Card title="Content Retrieval" icon="file-lines" href="/form-filling-api-reference/form-filling-content-retrieval">
    Endpoints for polling session status and retrieving structured medical-form output.
  </Card>

<Card title="Feedback" icon="comment" href="/form-filling-api-reference/form-filling-feedback">
    Endpoints for submitting feedback for form-filling session entities.
  </Card>

<Card title="Form Filling Info" icon="info" href="/form-filling-api-reference/form-filling-info">
    Endpoints for listing Suki-defined medical form templates for form-filling sessions.
  </Card>
</CardGroup>

## Suki Form Filling APIs workflow

To integrate with the Form Filling APIs, you follow a session-based workflow.

```mermaid actions={false} theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
flowchart TD
    Start([Start integration]) --> Auth[Authentication]
    Auth --> Check{User registered?}
    Check -->|No| Register[Register new user]
    Register --> Auth
    Check -->|Yes| Token[Get sdp_suki_token]
    Token --> Create["POST form-filling session create"]
    Create --> SessionID[Get ambient_session_id]
    SessionID --> Context{Seed or update context?}
    Context -->|Yes| AddContext["POST or PATCH context"]
    Context -->|No| EndSession
    AddContext --> EndSession["POST form-filling session end"]
    EndSession --> Poll["GET session status"]
    Poll --> Running{Terminal status?}
    Running -->|No| Poll
    Running -->|Yes| Notify{Webhook configured?}
    Notify -->|Yes| Hook[Receive notification]
    Notify -->|No| Structured["GET structured data"]
    Hook --> Structured
    Structured --> Feedback{Submit feedback?}
    Feedback -->|Optional| FB["POST entity feedback"]
    Feedback -->|Skip| Complete
    FB --> Complete([Workflow complete])

classDef authStyle fill:#FFE148,stroke:#D4A017,stroke-width:2px,color:#000000
    classDef registerStyle fill:#FFF394,stroke:#FFE148,stroke-width:2px,color:#000000
    classDef highlightStyle fill:#FFD700,stroke:#D4A017,stroke-width:3px,color:#000000

class Auth,Create,Poll,Structured authStyle
    class Register registerStyle
    class EndSession highlightStyle
```

### Developer workflow

<Steps>
  <Step title="Authenticate with Suki" icon="key">
    Authenticate with Suki to get a Suki authentication token also called `suki_token`.
  </Step>

<Step title="Create a form-filling session" icon="code">
    Create a form-filling session to start a new visit.
  </Step>

<Step title="Seed or update session context" icon="file-lines">
    Seed or update session context.
  </Step>

<Step title="Stream visit audio over WebSocket" icon="microphone">
    Stream visit audio over WebSocket to the Suki backend.
  </Step>

<Step title="End the session when the visit is complete" icon="circle-xmark">
    End the session when the visit is complete.
  </Step>

<Step title="Retrieve the structured form output after processing finishes" icon="file-lines">
    Retrieve the structured form output after processing finishes.
  </Step>
</Steps>

<Note>
  If webhooks are enabled for your partner account, your application will receive automatic completion notifications instead of relying only on polling.
</Note>

<Tip>
  **Best practices**

* Store **partner\_id**, **partner\_token**, and issued tokens securely; rotate credentials per your security policy.
  * Send API traffic over HTTPS and validate webhook signatures when your integration receives callbacks.
  * Read HTTP status and error bodies from REST responses; handle auth expiry by refreshing **`sdp_suki_token`** as documented.
</Tip>

## Next steps

<Icon icon="file-lines" /> Refer to the [Form Filling APIs quickstart](/form-filling-api-reference/quickstart) to get started.

# Form Filling API Quickstart
Source: https://developer.suki.ai/form-filling-api-reference/quickstart

Step-by-step guide to authenticate, create a session, stream audio over WebSocket, end the session, and retrieve structured form output or use webhooks

This guide walks you through the steps to use the Form Filling APIs to authenticate, create a session, provide context, stream audio through the shared Partner WebSocket (GET /ws/stream), end the session, and retrieve structured form output.

The WebSocket endpoint and message format are the same as Ambient audio streaming. Use the form-filling session ID when establishing the WebSocket connection.

**What you will do**

1. **Authenticate** to get a Suki token (and **register** the user if needed).
2. **Create** a form-filling session and optionally **seed context** for template metadata.
3. **Stream audio** over **`/ws/stream`** using your **form-filling** **`ambient_session_id`**, then **end** the session when the visit is done (details in the note after Step 3).
4. **Retrieve** structured form output by polling **status** and **structured-data**, or rely on a **webhook** when processing finishes.

<Tip>
  **Using an AI coding tool?**

npx skills add [https://developer.suki.ai](https://developer.suki.ai)

## Access and credentials

You need partner credentials to use the Suki Form Filling API.

Contact our [Partnership team](https://www.suki.ai/suki-partners/) to get your credentials. They will guide you through the [Onboarding process](/documentation/partner-onboarding) and provide what you need to get started.

### Prerequisites

To use the Suki Form Filling APIs, you must have the following:

* An OAuth-compliant authentication system
* JWT tokens with consistent user identifiers
* A publicly accessible <Tooltip href="/Glossary/j">JWKS</Tooltip> endpoint (or Okta authorization server) for token validation

Refer to the [Partner onboarding](/documentation/partner-onboarding) and [Partner authentication](/documentation/partner-authentication) guides for more details.

### Environments to use for development and testing

This guide uses **`https://sdp.suki-stage.com`** and **`wss://sdp.suki-stage.com`** for API and WebSocket examples (staging).

<Callout icon="code">
  **Important**:

* The production environment is **`https://sdp.suki.ai`** and **`wss://sdp.suki.ai`**.
  * The staging environment is **`https://sdp.suki-stage.com`** and **`wss://sdp.suki-stage.com`**.
  * Your partnership team will confirm which environment, base URL, and credentials apply for your integration.
</Callout>

## Step 1: Authenticate and get token

To begin, you must authenticate to get your access token. Send a **POST** request to the [/api/v1/auth/login](/api-reference/authentication/login) endpoint with the following parameters in the request body:

1. **partner\_id**: Your unique <Tooltip href="/Glossary/p">Partner ID</Tooltip>, which we provide to you securely offline.
2. **partner\_token**: The user's OAuth 2.0 ID token (<Tooltip href="/Glossary/p">Partner Token</Tooltip>) from your identity provider.
3. **provider\_id** (Optional): Unique identifier for the <Tooltip href="/Glossary/p">provider</Tooltip>. Required for Bearer type partners only.

Suki verifies the `partner_token` using your publicly exposed **JWKS endpoint** (or your Okta authorization server URL if you use Okta). On a successful request, the API returns a <Tooltip href="/Glossary/s">Suki Token</Tooltip> (`suki_token`) that you must include as the `sdp_suki_token` header for all subsequent API calls.

<Note>
  **Handling an unregistered user**:

* If the user is not yet registered in our system, the `/login` request will fail.
  * In this case, you must first call the [/api/v1/auth/register](/api-reference/authentication/register) endpoint to create the user, then call `/login` again.
  * You only need to call the register endpoint once for each new user.
  * Refer to the [Register API reference](/api-reference/authentication/register) for the full specification.
</Note>

<CodeGroup>
  ```bash cURL theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
  curl -X POST https://sdp.suki-stage.com/api/v1/auth/login \
    -H "Content-Type: application/json" \
    -d '{
      "partner_id": "your-partner-id",
      "partner_token": "your-jwt-token",
      "provider_id": "provider-123"
    }'
  ```
</CodeGroup>

<Tip>
  Save the `suki_token` from the response. This token is valid for **1 hour**. When it is about to expire, you can get a new one by making the same **POST** request to `/login` with a valid `partner_token`.
</Tip>

## Step 2: Create form-filling session

To start a form-filling session, send a **POST** request to the [/api/v1/form-filling/session/create](/form-filling-api-reference/form-filling-sessions/create) endpoint with the following parameters in the request body:

<Note>
  In the API reference, both the Form Filling session ID and the [Suki Ambient API session ID](/api-reference/ambient-sessions/create) are named **`ambient_session_id`**. Those identifiers refer to **different** sessions. Use only the **`ambient_session_id`** returned from **form-filling** `/session/create` for form-filling REST calls and for **`/ws/stream`**.
</Note>

1. **ambient\_session\_id** (Optional): Associate this form-filling session with an existing [Ambient API session](/api-reference/ambient-sessions/create) when applicable.
2. **correlation\_id** (Optional): Client-supplied identifier for tracing or correlating requests.

The request body itself is optional (you can send an empty JSON object). The response always includes the **`ambient_session_id`** for this form-filling session. Use that value for context, streaming, **end**, **status**, and **structured-data** calls.

<CodeGroup>
  ```bash cURL theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
  curl -X POST https://sdp.suki-stage.com/api/v1/form-filling/session/create \
    -H "sdp_suki_token: YOUR_SUKI_TOKEN" \
    -H "sdp_provider_id: <sdp_provider_id>" \
    -H "Content-Type: application/json" \
    -d '{}'
  ```
</CodeGroup>

<Tip>
  Save the **`ambient_session_id`** from the response. You need it for context, **`/ws/stream`**, **end**, **status**, and **structured-data** calls.
</Tip>

## Step 3: Seed context

After creating the session, you can send a **POST** request to the [/api/v1/form-filling/session//context](/form-filling-api-reference/form-filling-sessions/context) endpoint to provide form template metadata.

<Note>
  The request body is **optional**. If you omit it, skip this step and continue to audio capture (see the note after this step). If you include **`form_filling`**, you must send valid **`values`**: an array of objects, each with a required **`form_template_id`** (UUID for the template). Providing **context** improves the quality of structured form output for the templates you select.
</Note>

Include the following in the request body when you supply context:

* **form\_filling** (Optional): An object with **`values`**, an array of **`form_template_id`** entries that identify which medical form templates apply to this session.

Refer to the [Context API reference](/form-filling-api-reference/form-filling-sessions/context) for the full request structure. To list templates your integration can offer, use [Suki medical form templates](/form-filling-api-reference/info/suki-medical-form-templates).

<Note>
  **Audio capture:** The Form Filling APIs do not add a separate streaming endpoint. Use the Partner Ambient **`GET /ws/stream`** WebSocket on the same host as REST (for example **`wss://sdp.suki-stage.com/ws/stream`** in staging). Authenticate with your **form-filling** **`ambient_session_id`** and **`sdp_suki_token`**. Follow [Audio streaming API reference](/api-reference/ambient-sessions/audio-stream) and [Ambient audio streaming](/documentation/ambient-audio-streaming) for handshake, PCM format, message order, **`EVENT`** controls, timeouts, and the sequence **close WebSocket → end session (REST) → poll status and structured-data**. Treat REST as the source of truth for final structured output.
</Note>

## Step 4: End session

To complete the session and begin processing, send a **POST** request to the [/api/v1/form-filling/session//end](/form-filling-api-reference/form-filling-sessions/end) endpoint. This signals that no more audio will be sent for this session.

## Step 5: Poll status and retrieve structured data

When structured output is ready, Suki can notify your application. The recommended way to know when processing has finished is to use a **webhook** on the same partner callback you use for Ambient. Suki sends events such as **`session_summary_generated`** to the endpoint configured during onboarding. Payloads include **`_links`** you can follow to retrieve results. For verification, payload shapes, and examples, see [Asynchronous notifications (webhook)](/api-reference/asynchronous/webhook) and [Notification webhook for partners](/documentation/webhook/overview).

**Retrieving structured output manually**: Alternatively, poll the Form Filling REST endpoints:

1. [GET /api/v1/form-filling/session//status](/form-filling-api-reference/form-filling-sessions/status): Check the processing status of a session.
2. [GET /api/v1/form-filling/session//structured-data](/form-filling-api-reference/form-filling-sessions/structured-data): Retrieve **generated\_values** and **non\_generated\_values** for the session.

<CodeGroup>
  ```bash cURL theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
  # Check status
  curl -X GET "https://sdp.suki-stage.com/api/v1/form-filling/session/YOUR_SESSION_ID/status" \
    -H "sdp_suki_token: YOUR_SUKI_TOKEN" \
    -H "sdp_provider_id: <sdp_provider_id>"
  # Get structured data
  curl -X GET "https://sdp.suki-stage.com/api/v1/form-filling/session/YOUR_SESSION_ID/structured-data" \
    -H "sdp_suki_token: YOUR_SUKI_TOKEN" \
    -H "sdp_provider_id: <sdp_provider_id>"
  ```
</CodeGroup>

<Note>
  For complete technical specifications, please refer to the relevant API Reference pages.
</Note>

## Next steps

After completing your first session, explore these resources to deepen your integration:

<Icon icon="file-lines" /> [Form Filling API Overview](/form-filling-api-reference/overview) - Overview of the Form Filling APIs.

<Icon icon="file-lines" /> [Form Filling API Reference](/form-filling-api-reference/authentication/register) - Reference documentation for the Form Filling APIs.

<Icon icon="file-lines" /> [Audio streaming API](/api-reference/ambient-sessions/audio-stream) - WebSocket connection details and message formats for streaming audio for form-filling sessions.

<Icon icon="file-lines" /> [Webhook](/api-reference/asynchronous/webhook) - Configure webhooks to receive notifications when processing completes.

# Platform Client & Provider
Source: https://developer.suki.ai/headless-web-sdk/api-reference/platform-client

Headless Web SDK Client and Provider reference

The Suki Web SDK provides **PlatformClient** and **PlatformClientProvider** to help you integrate Suki Headless Web SDK functionality into your application.

**PlatformClient**

The `PlatformClient` acts as the shared runtime object for the SDK within your app. You should create a single instance of this object and reuse it throughout your application to ensure consistency.

**PlatformClientProvider**

The `PlatformClientProvider` is a React wrapper that makes your PlatformClient instance available to all child components.
This allows you to use Suki hooks, such as **`useAuth`**, **`useAmbient`**, and **`useAmbientSession`**, to build your integration quickly.

## PlatformClient

### Import

Before you can use the `PlatformClient`, you need to import it into your application.

```tsx React theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
import { PlatformClient } from '@suki-sdk/platform-react';

function App() {
  return <PlatformClientProvider client={platformClient}>
<YourApp />
</PlatformClientProvider>;
}
```

### Creating an instance

Create the client **once** for your app (for example at module scope or outside your root component) so it is not recreated on every render.

```tsx React  theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
const client = new PlatformClient({
  env: "staging",
  enableDebug: true,
  logLevel: "error"
});
```

<Note>
  The object you pass to `new PlatformClient({ ... })` sets how that client behaves for your app.
</Note>

### Configuration

These are the settings you pass when you call `new PlatformClient({ ... })` in your application.

<ResponseField name="env" type="string">
  The Suki environment the client targets. Examples in this documentation use **`"staging"`**.
</ResponseField>

<ResponseField name="enableDebug" type="boolean">
  When **`true`**, the client runs in a debug-oriented mode so you can troubleshoot during development. Use **`false`** when you do not want that behavior in production.
</ResponseField>

<ResponseField name="logLevel" type="string">
  The logging level for the client. Examples in this documentation use **`"error"`**.
</ResponseField>

## PlatformClientProvider

Before you can use the `PlatformClientProvider`, you need to import it into your application.

<CodeGroup>
  ```tsx Import theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
  import { PlatformClientProvider } from '@suki-sdk/platform-react';
  ```

```tsx Wrap your app theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
  import { PlatformClientProvider } from '@suki-sdk/platform-react';

function App() {
    return (
      <PlatformClientProvider client={platformClient}>
        <YourApp />
      </PlatformClientProvider>
    );
  }
  ```
</CodeGroup>

### Wrap your app

Create a single **`PlatformClient`** instance and wrap your application with **`PlatformClientProvider`**. Hooks such as `useAuth`, `useAmbient`, and `useAmbientSession` **must** run under this provider.

<Note>
  To use Headless Web SDK, you must wrap your app with **`PlatformClientProvider`** above any component that calls Headless Web SDK hooks. Those hooks read the shared **`PlatformClient`** from React context that the provider supplies.

Refer to the [Quickstart](/headless-web-sdk/quickstart) for a full component tree and **`useAuth`** example.
</Note>

## Next steps

<CardGroup>
  <Card title="Quickstart" icon="rocket" href="/headless-web-sdk/quickstart">
    Install, provider, `useAuth`, and ambient flow
  </Card>

<Card title="Types Overview" icon="brackets" href="/headless-web-sdk/api-reference/types">
    Index of all Headless Web SDK type reference pages
  </Card>

<Card title="Authentication Hook" icon="key" href="/headless-web-sdk/guides/hooks/auth-hook">
    `useAuth` configuration and behavior
  </Card>

<Card title="UseAuth Parameters" icon="brackets" href="/headless-web-sdk/api-reference/types/use-auth-params">
    TypeScript shape for `useAuth` options
  </Card>
</CardGroup>

# Headless Web SDK Types Reference
Source: https://developer.suki.ai/headless-web-sdk/api-reference/types

React type definitions and interfaces for the Suki Headless Web SDK

In React and TypeScript, **types** and **interfaces** describe the shape of objects you pass into hooks, props, and APIs. They tell your editor what fields exist, which are required, and what you get back from a function, so you catch mistakes early and autocomplete stays accurate.

This reference lists the Headless Web SDK types you will see alongside [authentication](/headless-web-sdk/guides/hooks/auth-hook), [ambient session creation](/headless-web-sdk/guides/hooks/ambient-hook), and [ambient session control](/headless-web-sdk/guides/hooks/ambient-session-hook). They are grouped below the same way you tend to use them in an app: first identity and tokens, then session context and session hook inputs and outputs.

Open a card when you need the exact field list, optional vs required flags, and how a type connects to a hook or flow.

## Authentication and tokens

Use these types when you configure `useAuth`, read results from login or registration, or type the payload when your backend refreshes a partner token.

Reach for **`UseAuthParams`** when you build the argument object for the auth hook. Use **`LoginResponse`** and **`RegistrationResponse`** when you handle success or error shapes from those flows. Use **`UpdatePartnerTokenResponse`** when you update tokens and want the SDK response typed end to end.

<CardGroup>
  <Card title="UseAuthParams" icon="brackets" href="/headless-web-sdk/api-reference/types/use-auth-params">
    Parameters for the `useAuth` hook
  </Card>

<Card title="LoginResponse" icon="key" href="/headless-web-sdk/api-reference/types/login-response">
    Response shape from the login flow
  </Card>

<Card title="RegistrationResponse" icon="user-plus" href="/headless-web-sdk/api-reference/types/registration-response">
    Response shape from registration
  </Card>

<Card title="UpdatePartnerTokenResponse" icon="arrows-rotate" href="/headless-web-sdk/api-reference/types/update-partner-token-response">
    Response from partner token updates
  </Card>
</CardGroup>

## Ambient session

Use these types when you pass patient, provider, and visit details into a session, call `useAmbientSession`, or branch UI on session status. **`SessionContext`** is the object that carries who and what visit the session is for.

**`UseAmbientSessionParams`** and **`UseAmbientSessionReturn`** match what you pass in and what the hook gives back (handlers, state, and helpers). **`AmbientSessionStatus`** is what you use when you need a narrow set of status values or related typing for recording, pausing, resuming, or finishing work.

<CardGroup>
  <Card title="SessionContext" icon="file-lines" href="/headless-web-sdk/api-reference/types/session-context">
    Patient, provider, and visit context for sessions
  </Card>

<Card title="UseAmbientSessionParams" icon="sliders" href="/headless-web-sdk/api-reference/types/use-ambient-session-params">
    Parameters for `useAmbientSession`
  </Card>

<Card title="UseAmbientSessionReturn" icon="arrow-turn-down-right" href="/headless-web-sdk/api-reference/types/use-ambient-session-return">
    Return type of `useAmbientSession`
  </Card>

<Card title="AmbientSessionStatus" icon="signal" href="/headless-web-sdk/api-reference/types/ambient-session-status">
    Session status values and related typing
  </Card>
</CardGroup>

## Next steps

<Icon icon="file-lines" /> Refer to [Provider](/headless-web-sdk/api-reference/platform-client) for more information on how to wrap your application with the `PlatformClient` and `PlatformClientProvider` before using hooks.

# AmbientSessionStatus Type
Source: https://developer.suki.ai/headless-web-sdk/api-reference/types/ambient-session-status

Status type for ambient sessions

## Type definition

Below is the type definition for the `AmbientSessionStatus` type. Use it to track the current state of a session and update your UI accordingly.

```tsx theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
type AmbientSessionStatus = 
  | "created"
  | "submitted"
  | "completed"
  | "cancelled";
```

# LoginResponse Type
Source: https://developer.suki.ai/headless-web-sdk/api-reference/types/login-response

Response type for login method

## Type definition

Below is the type definition for the `LoginResponse` type. This is the return type for the `login()` method from the `useAuth` hook. It contains authentication tokens after a successful login.

```tsx theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
type LoginResponse = {
  suki_token: string;
  jwt_bearer: string;
};
```

# RegistrationResponse Type
Source: https://developer.suki.ai/headless-web-sdk/api-reference/types/registration-response

Response type for registerUser method

## Type definition

Below is the type definition for the `RegistrationResponse` type. This is the return type for the `registerUser()` method from the `useAuth` hook. It returns an empty object `{}` when successful. After successful registration, you can sign the user in using the `login()` function.

```tsx theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
type RegistrationResponse = Record<string, never>;
```

# SessionContext Types
Source: https://developer.suki.ai/headless-web-sdk/api-reference/types/session-context

Type definitions for session context and response

## SessionContext type

Below is the type definition for the `SessionContext` type. You provide this context using the `setSessionContext` method to help Suki's AI generate more accurate and meaningful clinical notes.

```tsx theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
type SessionContext = {
  patient?: {
    dob: string;
    sex: string;
  };
  provider?: {
    specialty: string;
    role?: string;
  };
  visit?: {
    visit_type?: string;
    encounter_type?: string;
    reason_for_visit?: string;
    chief_complaint?: string;
  };
  sections?: Array<{ loinc: string }>;
  diagnoses?: {
    values: Array<{
      codes: Array<{
        code: string;
        description: string;
        type: string;
      }>;
      diagnosisNote: string;
    }>;
  };
};
```

## SessionContextResponse type

Below is the type definition for the `SessionContextResponse` type. This is the return type for the `setSessionContext` method. It returns an empty object `{}` when successful. If there's an error, the method throws a `ContextUpdateFailed` error.

```typescript theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
type SessionContextResponse = Record<string, never>;
```

# UpdatePartnerToken Type
Source: https://developer.suki.ai/headless-web-sdk/api-reference/types/update-partner-token-response

Response type for updatePartnerToken method

## Type definition

Below is the type definition for the `UpdatePartnerTokenResponse` type. This is the return type for the `updatePartnerToken()` method from the `useAuth` hook. It contains updated authentication tokens after successfully updating the partner token.

```tsx theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
type UpdatePartnerTokenResponse = {
  suki_token: string;
  jwt_bearer: string;
};
```

# UseAmbientSessionParams Type
Source: https://developer.suki.ai/headless-web-sdk/api-reference/types/use-ambient-session-params

Parameters type for useAmbientSession hook

## Type definition

Below is the type definition for the `UseAmbientSessionParams` type. This is the type definition for the parameters you pass to the `useAmbientSession` hook.

```tsx theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
type UseAmbientSessionParams = {
  ambientSessionId: string;
  config?: {
    audioBatchSize?: number;
  };
  onAudioChunkAvailable?: (audioChunk: Array<Int16Array>) => void;
};
```

# UseAmbientSessionReturn Type
Source: https://developer.suki.ai/headless-web-sdk/api-reference/types/use-ambient-session-return

Return type for useAmbientSession hook

## Type definition

Below is the type definition for the `UseAmbientSessionReturn` type. This is the type definition for what the `useAmbientSession` hook returns. It includes methods to control the session and state information about the current session.

```tsx theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
type UseAmbientSessionReturn = {
  start: () => Promise<void>;
  pause: () => Promise<void>;
  resume: () => Promise<void>;
  cancel: () => Promise<void>;
  submit: () => Promise<void>;
  setSessionContext: (sessionContext: SessionContext) => Promise<SessionContextResponse>;
  sessionStatus: AmbientSessionStatus;
  isFetching: boolean;
  refetch: () => Promise<AmbientSession>;
};
```

# UseAuthParams Type
Source: https://developer.suki.ai/headless-web-sdk/api-reference/types/use-auth-params

Parameters type for useAuth hook

## Type definition

Below is the type definition for the `UseAuthParams` type. This is the type definition for the parameters you pass to the `useAuth` hook. The type varies depending on whether auto-registration is enabled.

### With auto-registration (autoRegister: true)

```tsx theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
type UseAuthParams = {
  partnerId: string; // Required, replace with your actual partner ID
  partnerToken: string; // Required, replace with your actual partner token
  autoRegister?: true; // Default is true
  loginOnMount?: boolean; // Optional, set to true to sign in automatically when the component mounts
  providerId?: string; // Optional, replace with your actual provider ID
  providerName: string; // Required for auto-registration
  providerOrgId: string; // Required for auto-registration
  providerSpecialty?: string; // Required for auto-registration
};
```

### Without auto-registration (autoRegister: false)

```tsx theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
type UseAuthParams = {
  partnerId: string; // Required, replace with your actual partner ID
  partnerToken: string; // Required, replace with your actual partner token
  autoRegister?: false; // Default is false
  loginOnMount?: boolean; // Optional, set to true to sign in automatically when the component mounts
  providerId?: string; // Optional, replace with your actual provider ID
};
```

# Headless Web SDK Authentication
Source: https://developer.suki.ai/headless-web-sdk/authentication

Learn how to authenticate with the Suki Headless Web SDK

You must be a **Suki partner** to use the Suki Headless Web SDK. If you have not registered yet, please read our [Partner onboarding](/documentation/partner-onboarding) guide.

Once you are a partner, you can authenticate with Suki services using your own authentication system.

## Prerequisites

To configure the Headless Web SDK, you must provide the following credentials:

* **Partner ID**: The unique identifier assigned to you during onboarding.

* **Partner Token**: The access token you generate for the user from your system.

<Note>
  To understand how authentication works for partners, see [Partner authentication](/documentation/partner-authentication).
</Note>

## Authenticate with React (recommended)

In React, create a **`PlatformClient`**, wrap your app with **`PlatformClientProvider`**, then use the **`useAuth`** hook under that tree. The hook simplifies user registration and token updates.

* [Quickstart](/headless-web-sdk/quickstart) - full order of setup (provider, then `useAuth`)
* [Platform client and provider](/headless-web-sdk/api-reference/platform-client) - `PlatformClient` options and provider usage
* [Authentication hook](/headless-web-sdk/guides/hooks/auth-hook) - `useAuth` configuration and behavior

# Headless Web SDK Changelog
Source: https://developer.suki.ai/headless-web-sdk/changelog

Headless Web SDK product updates and announcements

Suki's Headless Web SDK versioning policy is based on the semantic versioning standard. For example, in version 1.2.3, 1 is the major version, 2 is the minor version, and 3 is the patch version.

When we release a new Headless Web SDK version for new features or bug fixes, we increment one of these three version components depending on the type of change introduced.

<Update label="v0.2.3" description="May 2026">
  ### Bug fixes

* Minor bug fixes.
</Update>

<Update label="v0.2.2" description="Jan 2026">
  ### Enhancements

* **Session type detection**: Added `sessionType` property to the `useAmbientSession` hook. This property indicates whether a session was submitted while online or offline. Use it to display appropriate UI indicators and handle offline sessions differently in your application.
</Update>

<Update label="v0.1.1" description="Dec 2025">
  ### New features

* **Initial beta release**: First release of the Suki Headless Web SDK. Build custom ambient intelligence integrations with complete control over your user interface. Currently in **beta** stage for you to try out and provide feedback.
</Update>

# Authentication and Session Flow
Source: https://developer.suki.ai/headless-web-sdk/example/auth-session-flow

Example code for the full flow from authentication to recording in one component

This example shows how to build a component that handles authentication, session creation, and recording in one place. It uses three hooks: `useAuth`, `useAmbient`, and `useAmbientSession`. The flow runs in order: sign in first, then create a session, then record.

## Code example

```tsx React expandable theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
import { useState, useEffect } from 'react';
import { useAuth, useAmbient, useAmbientSession } from '@suki-sdk/platform-react';

function SukiRecorder() {
  const [sessionId, setSessionId] = useState(null);

// Step 1: Authenticate
  const { isLoggedIn, isPending: authPending } = useAuth({
    partnerId: 'your-partner-id', // Required, replace with your actual partner ID
    partnerToken: 'your-partner-token', // Required, replace with your actual partner token
    autoRegister: true, // Optional, set to true to automatically register the user if they don't exist
    loginOnMount: true, // Optional, set to true to sign in automatically when the component mounts
    providerName: 'Dr. John Doe', // Required for auto-registration
    providerOrgId: 'org-123', // Required for auto-registration
    providerSpecialty: 'Cardiology' // Required for auto-registration
  });

// Step 2: Create session
  const {
    ambientSessionId,
    session: { create, isSuccess: sessionCreated }
  } = useAmbient();

useEffect(() => {
    if (isLoggedIn && !sessionCreated) {
      create();
    }
  }, [isLoggedIn, sessionCreated, create]);

useEffect(() => {
    if (ambientSessionId) {
      setSessionId(ambientSessionId);
    }
  }, [ambientSessionId]);

// Step 3: Manage recording
  const {
    start,
    pause,
    resume,
    submit,
    sessionStatus,
    sessionType, // [!code ++] New in v0.2.2
  } = useAmbientSession({
    ambientSessionId: sessionId
  });

if (authPending) {
    return <div>Authenticating...</div>;
  }

if (!isLoggedIn) {
    return <div>Please sign in</div>;
  }

if (!sessionId) {
    return <div>Creating session...</div>;
  }

return (
    <div>
      <h2>Recording Status: {sessionStatus}</h2>
      {sessionType === 'offline' && ( // [!code ++:2] added in v0.2.2
        <p>Session will sync when online</p>
      )}
      
      {sessionStatus === 'created' && (
        <button onClick={start}>Start Recording</button>
      )}
      
      {sessionStatus === 'recording' && (
        <>
          <button onClick={pause}>Pause</button>
          <button onClick={submit}>Submit</button>
        </>
      )}
      
      {sessionStatus === 'paused' && (
        <>
          <button onClick={resume}>Resume</button>
          <button onClick={submit}>Submit</button>
        </>
      )}
    </div>
  );
}
```

### Key implementation details

<AccordionGroup>
  <Accordion title="Step 1: Authentication">
    **Authentication**: The `useAuth` hook signs the user in. With `autoRegister: true` and `loginOnMount: true`, sign-in runs when the component mounts. If the user does not exist, the SDK registers them first. When using auto-registration, you must pass `providerName`, `providerOrgId`, and `providerSpecialty`. See the [Authentication hook](/headless-web-sdk/guides/hooks/auth-hook) guide.
  </Accordion>

<Accordion title="Step 2: Session Creation">
    **Session Creation**: The `useAmbient` hook creates a new ambient session. Call `session.create()` only after the user is logged in. Wait for `isSuccess` to be `true` before using `ambientSessionId`. Passing `undefined` to `useAmbientSession` will cause errors. See the [Create ambient session](/headless-web-sdk/guides/hooks/ambient-hook) guide.
  </Accordion>

<Accordion title="Step 3: Recording">
    **Recording**: The `useAmbientSession` hook controls recording. Pass the `ambientSessionId` from step 2. The hook returns `start`, `pause`, `resume`, and `submit` methods. It also returns `sessionStatus` and `sessionType` so you can update your UI. See the [Manage ambient session](/headless-web-sdk/guides/hooks/ambient-session-hook) guide.
  </Accordion>
</AccordionGroup>

<Tip>
  Always wait for `isSuccess` to be `true` before using `ambientSessionId`. Passing an undefined session ID to `useAmbientSession` will cause errors.
</Tip>

## Next steps

<Icon icon="file-lines" /> Refer to the [Manage ambient session](/headless-web-sdk/guides/hooks/ambient-session-hook) guide to learn how to add session context and improve note quality.

# Authentication Example
Source: https://developer.suki.ai/headless-web-sdk/example/authentication-example

Example code for building a component that offers manual Sign In and Register options

This example demonstrates how to build a component that offers manual **Sign In** and **Register** options. This is useful if you disable `autoRegister` and `loginOnMount` to give the user explicit control.

## Code example

```tsx React expandable theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}

import React from 'react';
import { useAuth } from '@suki-sdk/platform-react';

export const AuthManager = ({ partnerId, partnerToken, providerId }) => {
  // 1. Initialize the hook with your partner credentials.
  // We disable auto-actions to demonstrate manual control.
  const {
    login,
    registerUser,
    isLoggedIn,
    isPending,
    error
  } = useAuth({
    partnerId, //Required
    partnerToken, //Required
    providerId, //Optional
    autoRegister: false, // set to true to skip manual registration steps
    loginOnMount: false, // set to true to sign in automatically on load
  });

// 2. Handle the Sign In action
  const handleSignIn = async () => {
    try {
      // login() uses the partnerToken passed in the config above
      await login();
      console.log('User signed in successfully.');
    } catch (err) {
      // Errors are also available in the 'error' object from the hook
      console.error('Sign-in failed:', err);
    }
  };

// 3. Handle the Registration action
  const handleRegister = async () => {
    // Construct the registration request object required by the SDK
    const userDetails = {
      externalId: providerId,
      firstName: 'Jane', // In a real app, gather this from a form
      lastName: 'Doe',
    };

try {
      await registerUser(userDetails);
      console.log('User registered successfully.');
      
      // Often, you will want to sign the user in immediately after registration
      await login(); 
    } catch (err) {
      console.error('Registration failed:', err);
    }
  };

// 4. Render the UI based on authentication state
  if (isLoggedIn) {
    return (
      <div className="success-message">
        <h3>Welcome</h3>
        <p>You are connected to the Suki Platform.</p>
      </div>
    );
  }

return (
    <div className="auth-container">
      <h2>Suki Authentication</h2>
      
      {/* Display errors if they occur */}
      {error && (
        <div className="error-banner">
          <strong>Error:</strong> {error.message}
        </div>
      )}

<div className="button-group">
        {/* Button to Sign In */}
        <button 
          onClick={handleSignIn} 
          disabled={isPending}
        >
          {isPending ? 'Processing...' : 'Sign In'}
        </button>

{/* Button to Register */}
        <button 
          onClick={handleRegister} 
          disabled={isPending}
        >
          Register User
        </button>
      </div>
    </div>
  );
};
```

### Key implementation details

<AccordionGroup>
  <Accordion title="Configuration">
    **Configuration**: You pass the `partnerId` and `partnerToken` directly to the `useAuth` hook. The `login` function reads these values internally.
  </Accordion>

<Accordion title="Error handling">
    **Error handling**: The hook provides an error object (typically a [Platform error](/headless-web-sdk/guides/error-handling)) that updates automatically if an operation fails. You should display this to the user.
  </Accordion>

<Accordion title="Registration">
    **Registration**: The `registerUser` function accepts an object containing user details. The exact fields required depend on your specific partner configuration.
  </Accordion>
</AccordionGroup>

<Note>
  If you set `autoRegister: true` in the hook configuration, you generally do not need a separate Register User button. The SDK will handle account creation during the sign-in attempt if the user does not exist.
</Note>

# General
Source: https://developer.suki.ai/headless-web-sdk/faqs/general

General questions about Headless Web SDK

<Accordion title="What is the Suki Headless Web SDK?">
  The Suki Headless Web SDK is a modular SDK that allows you to embed ambient intelligence capabilities directly into your web application. Being a headless SDK, you can design your own user interface while using our SDK's functionality.
</Accordion>

<Accordion title="How can I authenticate with the Suki Headless Web SDK?">
  To use the Headless Web SDK, you must be a Suki partner. Learn more about how to become a Suki partner [here](/documentation/partner-onboarding). Once you are a Suki partner, you can authenticate with the Suki services using the following ways:

* **Your own authentication system:** Use your own authentication system to authenticate with the Suki services. You must provide the Suki SDK with the following information:
    * Your partner ID
    * Your partner token
    * Your partner secret
    * Your partner URL
    * Your partner port
    * Your partner protocol
    * Your partner path
  * **JWKS URL:** Use a JWKS URL to authenticate with Suki for Partners. Learn more about how to get the JWKS URL [here](/documentation/partner-authentication).
</Accordion>

<Accordion title="How can I use the Suki Headless Web SDK?">
  To use the Headless Web SDK, you need to follow the steps below:

1. Install the Suki Headless Web SDK
  2. Initialize the Suki Headless Web SDK
  3. Use the Suki Headless Web SDK hooks to embed ambient intelligence capabilities directly into your web application.
</Accordion>

<Accordion title="What is the difference between the Suki Headless Web SDK and the Suki Web SDK?">
  The **Suki Headless Web SDK** is a modular SDK that allows you to embed ambient intelligence capabilities directly into your web application. Being a headless SDK, you can design your own user interface while using our SDK's functionality.

The **Suki Web SDK** is a pre-built SDK that comes with a pre-built user interface. It is designed to be used as a full-stack SDK.
</Accordion>

# Implementation
Source: https://developer.suki.ai/headless-web-sdk/faqs/implementation

Implementation questions about the Suki Headless Web SDK

<Accordion title="Why doesn't the SDK replay audio chunks upon reconnection?">
  The SDK does not replay the audio chunk stream after a network recovery.
  While replaying chunks might seem like a logical way to fill gaps, it introduces significant complexity to your integration.

For example, it would create the following issues:

* **Duplication**: It would send duplicate audio ranges (the live stream plus the replayed history).

* **Complexity**: You would need to build complex logic to track chunk IDs, deduplicate data, and enforce idempotency.

* **Performance**: Replaying history creates a large set of data to process immediately upon reconnection.

You may then ask, **"How does the SDK manage data?"**

The SDK is intentionally designed to hide this complexity from you. So that you can focus on building your own user interface and features.

* **Real-time chunks**: Use the `onAudioChunkAvailable` callback only for live user interface features, such as drawing a waveform.

* **Offline robustness**: For data persistence, rely on the SDK's built-in offline manager. The SDK buffers encrypted audio in `IndexedDB` and automatically uploads it to the Suki backend server when the connection returns.

<Tip>
    We recommend you rely on the **final session artifact** (e.g., the generated note or WAV file) rather than attempting to stitch together a complete recording from the real-time chunk stream.
  </Tip>
</Accordion>

# Technical
Source: https://developer.suki.ai/headless-web-sdk/faqs/technical

Technical questions about Headless Web SDK

<Accordion title="Which commands work offline, and how are errors handled?">
  To effectively manage offline scenarios, you must understand which commands require an active network connection and which function locally.

**Commands that require a network**

The following commands **always require an active internet connection**. If you call them while offline, the SDK throws a `PlatformError` (or a wrapped network error).

* **Authentication**: `login`, `registerUser`, `updatePartnerToken`.

* **Session creation**: `session.create` (from the useAmbient hook).

* **Initial start**: The `start` method (from `useAmbientSession`) needs a connection **once** to establish the backend session stream.

**Commands that work offline**

Once you successfully start a session, the Suki SDK becomes offline-resilient.

* **Capture**: If the network drops after the session starts, the SDK continues to capture and buffer microphone audio locally in IndexedDB.

* **Pause and resume**: Use `pause` and `resume` while offline. The SDK updates the local state immediately and reconciles it eventually when the connection returns.

* **Submit**:

* **Online**: The session finalizes immediately.

* **Offline**: The SDK marks the session as "finalize-pending." It automatically starts the upload process once the network is restored.

* **Cancel**:

* **Online**: The session cancels immediately.

* **Offline**: The cancellation is queued. If the session is still valid when you reconnect, the SDK applies the cancellation.

**Error handling and status tracking**
  You should monitor the session status to handle offline behaviors correctly.

* **Errors**: Connectivity issues during online-only commands surface as `PlatformError`. You should catch these and notify the user to check their connection.

* **Status updates**: The outcome of offline actions (like `submit` or `cancel`) is reflected in the session status. Track this using the `useOfflineSessions` hook in React.

<Note>
    The initial `create` and `start` commands are the only critical points that require a network. After that, the SDK safely stores encrypted audio locally and syncs your `submit` or `cancel` actions eventually.
  </Note>
</Accordion>

<Accordion title="How long does the SDK remain in offline mode?">
  Offline mode has no fixed timeout. As long as the browser's **IndexedDB** remains intact, the SDK preserves the buffered sessions.

If you close the browser tab or window, the SDK scans the database when you re-initialize the `PlatformClient` on the next load. It then automatically starts
  uploading any offline sessions that you previously submitted. The browser's **storage settings** determine the effective lifetime of this offline data.

<Note>
    Effective lifetime of offline data is governed by browser storage and not by an internal SDK timer.
  </Note>
</Accordion>

<Accordion title="What happens if I refresh the page while a session is recording?">
  The SDK manages session persistence internally. If an ongoing session is interrupted by a refresh or relaunch, you can resume it by passing the same `ambientSessionId`.

The session continues from where it left off, and you can track updates via the `useOfflineSessions` hook.
</Accordion>

# Error Handling
Source: https://developer.suki.ai/headless-web-sdk/guides/error-handling

Learn how to handle errors and exceptions in the Suki Headless Web SDK

<span>Quick summary</span>
  </div>

<div>
    The Suki Headless SDK exposes error codes for authentication, session lifecycle, and other operations. All errors include an error code, name, and optional reason to help you diagnose issues and implement the correct handling logic.

<br />

Use this guide to understand what each error code means and how to resolve it in your application.
  </div>

<span>Last updated:</span>
    <span>May 2026</span>
  </div>
</div>

This guide details the error codes exposed by the Suki Headless SDK. Use this guide to diagnose issues and implement the correct handling logic in your application.

Use the following type of errors to find the error code you need to handle while using the Suki Headless Web SDK.

## Authentication errors (AuthError)

These errors occur during **user registration**, **sign-in**, or **token updates**.

| Error code              | Cause                                                    | Solution                                                                                                                                     |
| ----------------------- | -------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| `InvalidPartnerDetails` | You provided incorrect details during user registration. | Double-check your **partner ID**, **secret key**, and other registration details, then try again.                                            |
| `InvalidPartnerDetails` | You provided incorrect details during sign-in.           | Verify your credentials (**partner ID**, **partner token**, etc.) are correct before attempting to sign in again.                            |
| `ServiceError`          | An unexpected error occurred on the Suki server.         | This is usually a temporary issue. Retry the API call after a short delay. If the problem persists, contact support.                         |
| `UserNotFound`          | The user you are trying to access does not exist.        | Ensure the user is registered before trying to sign in. Tip: Enable auto-onboarding by setting **autoRegister: `true`** in the useAuth hook. |

## Session lifecycle errors

These errors occur when you attempt to **start**, **pause**, **resume**, **cancel**, or **submit** an ambient session.

### Starting a session (StartSessionFailed)

| Error code             | Cause                                                   | Solution                                                                                                  |
| ---------------------- | ------------------------------------------------------- | --------------------------------------------------------------------------------------------------------- |
| `InvalidSessionState`  | The session is already finalized.                       | Create a new session. You cannot modify a session once it is finalized.                                   |
| `InvalidSessionState`  | The session is already in a recording state.            | This likely indicates a bug in your logic. If you intended to restart, pause the session first.           |
| `NetworkOffline`       | The device does not have an active internet connection. | Ensure there is an active internet connection and try starting the session again.                         |
| `StreamError`          | Failed to establish a stream with the Suki backend.     | This is likely a temporary issue. Retry starting the session. If the problem persists, contact support.   |
| `AudioRecorderFailure` | Failed to access or start the microphone.               | This is likely a browser or permission issue. Check your microphone settings and permissions, then retry. |

### Pausing a session (PauseSessionFailed)

| Error code            | Cause                                        | Solution                                                                                    |
| --------------------- | -------------------------------------------- | ------------------------------------------------------------------------------------------- |
| `InvalidSessionState` | The session is already finalized.            | Create a new session. You cannot modify a session once it is finalized.                     |
| `InvalidSessionState` | The session is not in a recording state.     | This likely indicates a bug in your logic; you cannot pause a session that isn't recording. |
| `StreamError`         | Failed to close the stream with the backend. | This is likely a temporary issue. No action is usually needed.                              |

### Resuming a session (ResumeSessionFailed)

| Error code             | Cause                                         | Solution                                                                                  |
| ---------------------- | --------------------------------------------- | ----------------------------------------------------------------------------------------- |
| `InvalidSessionState`  | The session is already finalized.             | Create a new session. You cannot modify a session once it is finalized.                   |
| `InvalidSessionState`  | The session is not in a paused state.         | This likely indicates a bug in your logic; you cannot resume a session that isn't paused. |
| `StreamError`          | Failed to resume the stream with the backend. | This is likely a temporary issue. No action is usually needed.                            |
| `AudioRecorderFailure` | Failed to start the microphone.               | This is likely a browser issue. Check microphone settings and permissions, then retry.    |

### Canceling a session (CancelSessionFailed)

| Error code            | Cause                                        | Solution                                                                |
| --------------------- | -------------------------------------------- | ----------------------------------------------------------------------- |
| `InvalidSessionState` | The session is already finalized.            | Create a new session. You cannot modify a session once it is finalized. |
| `StreamError`         | Failed to close the stream with the backend. | This is likely a temporary issue. Retry cancelling the session.         |

### Submitting a session (SubmitSessionFailed)

| Error code          | Cause                                                               | Solution                                                                                                                                                               |
| ------------------- | ------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `StreamError`       | Failed to close the stream with the backend.                        | This is likely a temporary issue. Retry submitting the session.                                                                                                        |
| `ServiceError`      | Unable to update the session state to "ready" for note generation.  | This is likely a temporary issue. Retry submitting the session.                                                                                                        |
| `OfflineSaveFailed` | Failed to store the offline session in browser storage (IndexedDB). | Your browser storage may be full. Clear your cache or IndexedDB. <Warning> If the SDK is closed at this stage without saving, the session data will be lost.</Warning> |

## Context update errors (ContextUpdateFailed)

These errors occur when you call `setSessionContext` to update patient information or visit metadata during an active session.

| Error code            | Cause                                       | Solution                                                                               |
| --------------------- | ------------------------------------------- | -------------------------------------------------------------------------------------- |
| `InvalidSessionState` | The session is already finalized.           | Create a new session. You cannot modify the context of a session once it is finalized. |
| `ServiceError`        | Failed to update the context on the server. | Retry updating the session context.                                                    |

## Next steps

<Icon icon="file-lines" /> Refer to the [Offline mode](/headless-web-sdk/guides/offline-mode) guide to learn more about how to handle offline mode in the Suki Headless Web SDK.

# Create Ambient Session
Source: https://developer.suki.ai/headless-web-sdk/guides/hooks/ambient-hook

Learn how to use the useAmbient hook to create an ambient session and obtain an ambientSessionId in the Headless Web SDK

<span>Quick summary</span>
  </div>

<div>
    The `useAmbient` hook creates a new ambient session container on Suki's servers. You call `session.create()` to get a unique `ambientSessionId` that identifies your session.

<br />

The hook provides status flags (`isPending`, `isSuccess`, `isError`) so you can track the creation progress and update your UI accordingly. Once you have the `ambientSessionId`, you can use it with `useAmbientSession` to start recording.
  </div>

<span>Last updated:</span>
    <span>May 2026</span>
  </div>
</div>

The **`useAmbient`** hook allows you to create an ambient session on Suki's servers. It returns an **`ambientSessionId`** and **`session.create()`** with status flags so you know when it is safe to hand that id to **`useAmbientSession`** for recording.

### Configuration

Run the hook under **`PlatformClientProvider`** with a shared **`PlatformClient`** instance.

### Common use cases

<Steps>
  <Step title="Provision an ambient session" icon="user">
    Create an ambient session when a visit begins or when your application is ready to start the workflow. Call **`session.create()`** to send the request to the Suki backend. While the request is in progress, monitor the session state using:

* **`session.isPending`** to detect an active request
    * **`session.isSuccess`** to confirm that the session was created successfully
    * **`session.isError`** to detect request failures
  </Step>

<Step title="Pass the ambient session to downstream workflows" icon="arrow-right">
    After the session is created successfully, read the returned **`ambientSessionId`** and pass it to **`useAmbientSession`** to continue the workflow.

Only access **`ambientSessionId`** after **`session.isSuccess`** is `true`. Do not pass an undefined or incomplete session ID. For more information, refer to the warning in [Code example](#code-example) below.
  </Step>

<Step title="Handle session creation errors" icon="exclamation-triangle">
    If session creation fails, **`session.isError`** is set to `true`. Read **`session.error`** to inspect the failure and implement retry or user-facing error handling logic.

For implementation details, refer to [Error handling](/headless-web-sdk/guides/error-handling).
  </Step>
</Steps>

## useAmbient hook

### Usage

Call **`useAmbient()`** with no arguments from a component under **`PlatformClientProvider`**. Destructure **`ambientSessionId`**, **`session.create`**, and the session status fields.

```tsx theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
const {
  ambientSessionId,
  session: {
    create,
    error,
    isError,
    isPending,
    isSuccess,
  },
} = useAmbient();
```

### Returns

The hook returns **`ambientSessionId`** and a **`session`** object with **`create()`**, status flags, and **`error`**, documented under [What it returns](#what-it-returns).

### How session creation works

1. **Call the hook:** Initialize **`useAmbient()`** in your component.
2. **Create the session:** Call **`session.create()`** to request a new session from Suki's backend.
3. **Get the session ID:** When creation succeeds, use **`ambientSessionId`** for recording (typically with **`useAmbientSession`**).

The hook provides status flags (`isPending`, `isSuccess`, `isError`) so you can track the creation progress and update your UI accordingly.

<div>
  ```mermaid actions={false} theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
  flowchart TD
      A[Create ambient session] --> B{Request status}
      B -->D[Receive SessionId]
      D --> F[Pass ambientSessionId]
      F --> H[Use ambientSessionId for recording]
      
      style A fill:#FFF394,stroke:#D4A017,color:#000000
      style D fill:#FFF394,stroke:#D4A017,color:#000000
      style F fill:#FFF394,stroke:#D4A017,color:#000000
  ```
</div>

## What it returns

The hook returns the session identifier and status information about the creation request.

### Session identifier

<ResponseField name="ambientSessionId" type="string">
  The unique identifier for your ambient session. This value is `undefined` until the session is successfully created. Once `isSuccess` is `true`, you'll have a valid session ID to use with other hooks like `useAmbientSession`.
</ResponseField>

### Status flags

Use these boolean flags to control your UI and handle the creation lifecycle:

<ResponseField name="session.isPending" type="boolean">
  Check this flag to show a loading state in your UI. When `true`, display a loading spinner, disable buttons, or show a "Creating session." message. The hook sets this to `true` while creating the session.
</ResponseField>

<ResponseField name="session.isSuccess" type="boolean">
  Check this flag to proceed with recording. When `true`, the session is ready and `ambientSessionId` contains a valid session ID. Show your recording controls or pass the session ID to the next step in your workflow.
</ResponseField>

<ResponseField name="session.isError" type="boolean">
  Check this flag to display error messages in your UI. When `true`, show an error message to the user using details from `session.error`. You might want to offer a retry option or redirect to an error page.
</ResponseField>

<ResponseField name="session.error" type="SukiError">
  Use this to display specific error information to users. When `session.isError` is `true`, read this object to show error messages, error codes, or troubleshooting information in your UI. It remains `null` or `undefined` when there's no error.
</ResponseField>

### Actions

<ResponseField name="session.create()" type="function: () => void">
  Call this function to create a new ambient session. The function sends a request to Suki's backend and updates all status flags automatically. Call it when a component mounts, when a user clicks a button, or at any point in your workflow.
</ResponseField>

## Code example

This example shows how to create a session when a user starts a patient visit. The session is created automatically when the component mounts, and the session ID is passed to the parent component once ready.

```tsx React expandable theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
import { useEffect } from 'react';
import { useAmbient } from '@suki-sdk/platform-react';

export const VisitStarter = ({ onSessionReady }) => {
  const {
    ambientSessionId,
    session: { create, isPending, isSuccess, error }
  } = useAmbient();

// Create the session when component mounts
  useEffect(() => {
    create();
  }, [create]);

// Pass the session ID to parent once creation succeeds
  useEffect(() => {
    if (isSuccess && ambientSessionId) {
      onSessionReady(ambientSessionId);
    }
  }, [isSuccess, ambientSessionId, onSessionReady]);

// Show loading state while creating
  if (isPending) {
    return <div>Initializing Suki Session...</div>;
  }

// Show error if creation failed
  if (error) {
    return <div>Error creating session: {error.message}</div>;
  }

return null; 
};
```

**What this example does:**

1. **Initializes the hook** - Gets the `useAmbient` hook and its return values
2. **Creates session on mount** - Automatically calls `create()` when the component loads
3. **Handles loading state** - Shows a loading message while `isPending` is `true`
4. **Handles success** - Passes the `ambientSessionId` to the parent component once ready
5. **Handles errors** - Displays error messages if creation fails

<Warning>
  **Important**: Always wait for `isSuccess` to be `true` before using `ambientSessionId`. Passing an `undefined` session ID to `useAmbientSession` or other hooks will cause errors.
</Warning>

<Tip>
  Trigger session creation manually (e.g., on button click) instead of automatically on mount by calling `create()` when the user performs an action.
</Tip>

## Next steps

<Icon icon="file-lines" /> Once you have created an ambient session, refer to the [Manage ambient session guide](/headless-web-sdk/guides/hooks/ambient-session-hook) to start recording audio and manage the ambient session.

# Manage Ambient Session
Source: https://developer.suki.ai/headless-web-sdk/guides/hooks/ambient-session-hook

Learn how to manage an ambient session lifecycle within your application while using the Suki Headless Web SDK

<Callout title="Updates" icon="bell">
  **Updated**

The `useAmbientSession` hook now returns a `sessionType` property. This helps you determine whether the session is an online or offline session.
</Callout>

<span>Quick summary</span>
  </div>

<div>
    The `useAmbientSession` hook controls your audio recording workflow. Use it after creating a session with `useAmbient` to manage recording, pausing, and submitting audio.

<br />

The hook provides methods to `start`, `pause`, `resume`, `cancel`, and `submit` recordings. It returns session status so you can update your UI and provides real-time audio data through callbacks for building visualizations.
  </div>

<span>Last updated:</span>
    <span>May 2026</span>
  </div>
</div>

The **`useAmbientSession`** hook allows you to control the ambient recording workflow after you have an **`ambientSessionId`**. It exposes **`start`**, **`pause`**, **`resume`**, **`cancel`**, and **`submit`**, optional **`setSessionContext`**, session status, **`sessionType`** (online or offline), and optional real-time audio chunks for visualizations.

### Configuration

Pass the **`ambientSessionId`** you received from **`useAmbient`** after **`session.isSuccess`** is `true` (refer to [Create Ambient Session](/headless-web-sdk/guides/hooks/ambient-hook)). Run the hook under **`PlatformClientProvider`**.
Refer to [Platform client and provider](/headless-web-sdk/api-reference/platform-client) for more information.

### Common use cases

<Steps>
  <Step title="Control the recording lifecycle" icon="play">
    Use the recording control methods to match the behavior of your application's recording experience:

* **`start()`** to begin recording
    * **`pause()`** to temporarily stop audio capture
    * **`resume()`** to continue a paused recording
    * **`cancel()`** to discard the current session
    * **`submit()`** to finalize and submit the recording for processing
  </Step>

<Step title="Attach clinical context to a session" icon="clipboard">
    Use **`setSessionContext()`** to associate patient, provider, and visit metadata with the active session.

Call **`setSessionContext()`** after **`start()`** and before **`submit()`** to ensure the metadata is included with the session. For supported fields and examples, refer to [Session context](#session-context) below.
  </Step>

<Step title="Support online and offline session flows" icon="signal">
    Read **`sessionType`** to determine how the session is running:

* **`"online"`** for real-time workflows
    * **`"offline"`** for deferred or asynchronous processing workflows

Use this value to conditionally render UI, messaging, or workflow behavior.
  </Step>

<Step title="Process audio waveform data" icon="waveform">
    Use **`onAudioChunkAvailable`** to receive streamed audio chunks during recording. Audio data is returned as batched **`Int16Array`** chunks.

Optionally configure **`config.audioBatchSize`** to control the batch size and frequency of audio chunk delivery.
  </Step>

<Step title="Build responsive session status UI" icon="display">
    Use the returned session state values to drive UI behavior throughout the recording workflow:

* **`sessionStatus`** for displaying the current session state
    * **`isFetching`** for loading indicators and disabled states
    * **`ambientSessionId`** for identifying and tracking the active session

These values can be used to update labels, spinners, buttons, and workflow transitions in real time.
  </Step>
</Steps>

## useAmbientSession hook

### Usage

Call **`useAmbientSession`** with an object that includes **`ambientSessionId`** and optional **`config`** and **`onAudioChunkAvailable`**.

```tsx theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
const {
  start,
  pause,
  resume,
  cancel,
  submit,
  setSessionContext,
  sessionStatus,
  isFetching,
  sessionType, // [!code ++] New in v0.2.2
  ambientSessionId,
  config,
  onAudioChunkAvailable,
} = useAmbientSession({...});
```

### Returns

The hook returns control methods, session status, **`sessionType`**, and related fields. Parameter and return shapes are documented under [Configuration](#configuration) and [What it returns](#what-it-returns).

### How recording works

1. **Pass the session ID:** Provide the **`ambientSessionId`** from **`useAmbient`**.
2. **Configure options:** Optionally set **`config.audioBatchSize`** and **`onAudioChunkAvailable`** for real-time audio batches.
3. **Use the controls:** Call **`start`**, **`pause`**, **`resume`**, **`cancel`**, and **`submit`** to move through the lifecycle your UI needs.

```mermaid actions={false} theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
flowchart TD
    A[Start recording] --> B[Recording active]
    B --> C{Pause or Submit?}
    C -->|Pause| D[Paused]
    C -->|Submit| E[Submitting]
    D -->|Resume| B
    E --> F[Complete]
    C -->|Cancel| G[Session cancelled]
    
    style A fill:#FFF394,stroke:#D4A017,color:#000000
    style B fill:#FFF394,stroke:#D4A017,color:#000000
    style E fill:#FFF394,stroke:#D4A017,color:#000000
    style F fill:#FFF394,stroke:#D4A017,color:#000000
    style D fill:#e3e0e0,stroke:#8b8a8a,color:#000000
    style G fill:#e3e0e0,stroke:#8b8a8a,color:#000000
```

## Configuration

Configure the hook with these parameters:

<ResponseField name="ambientSessionId" type="string">
  Pass the unique session identifier you received from the `useAmbient` hook. This links the recording to the session you created.
</ResponseField>

<ResponseField name="config.audioBatchSize" type="number">
  **Optional**: Configure the audio batch size for the `onAudioChunkAvailable` callback.
</ResponseField>

<ResponseField name="onAudioChunkAvailable" type="function (audioChunk: Array<Int16Array>) => void">
  **Optional**: Provide a callback function that receives audio chunks as they become available. The SDK calls this function whenever a batch of audio data is ready. Use this to draw real-time waveforms, visualizers, or other audio visualizations in your UI.
</ResponseField>

```tsx theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
type UseAmbientSessionParams = {
  ambientSessionId: string;
  config?: {
    audioBatchSize?: number
  };
  onAudioChunkAvailable?: (audioChunk: Array<Int16Array>) => void;
}
```

## What it returns

The hook returns control methods and status information you use to manage recording and update your UI.

### Actions (methods)

Use these methods to control the recording workflow:

<ResponseField name="start" type="function: () => Promise<void>">
  Call this to begin recording audio. Call this when the user clicks a "Start Recording" button.
</ResponseField>

<ResponseField name="pause" type="function: () => Promise<void>">
  Call this to pause recording temporarily. Resume later with `resume()`. Call this when the user clicks a "Pause" button.
</ResponseField>

<ResponseField name="resume" type="function: () => Promise<void>">
  Call this to resume a paused recording. Call this when the user clicks a "Resume" button.
</ResponseField>

<ResponseField name="cancel" type="function: () => Promise<void>">
  Call this to stop recording and cancel the session. Call this when the user clicks a "Cancel" or "Discard" button.
</ResponseField>

<ResponseField name="submit" type="function: () => Promise<void>">
  Call this to finish recording and submit the session for note generation. Call this when the user clicks a "Finish" or "Submit" button.
</ResponseField>

<ResponseField name="setSessionContext" type="function: (context: SessionContext) => Promise<Response>">
  Call this to send patient, provider, and visit metadata to Suki. The function sends context information that helps Suki generate more accurate clinical notes. Call this after `start()` but before `submit()` for best results.
</ResponseField>

```tsx theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
type UseAmbientSessionReturn = {
  start: () => Promise<void>;
  pause: () => Promise<void>;
  resume: () => Promise<void>;
  cancel: () => Promise<void>;
  submit: () => Promise<void>;
  setSessionContext: (sessionContext: SessionContext) => Promise<SessionContextResponse>;
  sessionStatus: 
    | "created"
    | "submitted"
    | "completed"
    | "cancelled";
  sessionType: "online" | "offline";
};
```

### State (data)

Use these values to control your UI and show the current session state:

<ResponseField name="sessionStatus" type="AmbientSessionStatus">
  Check this value to display the current session state in your UI. Common values: `"created"` (session ready to start), `"submitted"` (recording finished, processing), `"completed"` (note generated), and `"cancelled"` (session cancelled). Use this to show status messages, enable/disable buttons, or change UI states based on the session status.
</ResponseField>

<ResponseField name="isFetching" type="boolean">
  Check this flag to show a loading state while syncing session information. When `true`, the SDK is currently fetching session status from Suki's backend. Display a loading indicator or disable actions while this is `true`.
</ResponseField>

<ResponseField name="sessionType" type="'online' | 'offline'">
  Use this value to determine whether the session is an online or offline session.
</ResponseField>

### Session context

The `setSessionContext` method lets you send patient, provider, and visit information to Suki. This context helps Suki's AI generate more accurate and relevant clinical notes.

#### What is session context?

Session context is metadata about the patient visit that improves note quality. Include:

* **Patient details**: Date of birth, sex
* **Provider information**: Specialty, role
* **Visit information**: Visit type, encounter type, reason for visit, chief complaint
* **Clinical sections**: [LOINC codes](/documentation/note-sections) for specific sections you want in the note
* **Diagnoses**: Pre-existing or current diagnoses with codes and descriptions

#### When to use it

Call `setSessionContext` after calling `start()` but before calling `submit()`. Providing context early helps the AI understand the clinical scenario and generate better notes.

#### Session context structure

#### Response type

```tsx theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
type SessionContextResponse = Record<string, never>;
```

The `setSessionContext` method returns an empty object when successful. If an error occurs, it throws a `ContextUpdateFailed` error. See the [Error handling guide](/headless-web-sdk/guides/error-handling#context-update-errors-contextupdatefailed) for details.

## Code example

This example shows how to build a recording interface with Start, Pause, Resume, and Submit controls. The UI updates based on `sessionStatus` to show the appropriate buttons at each stage.

```tsx React expandable theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
import { useAmbientSession } from '@suki-sdk/platform-react';

export const Recorder = ({ sessionId }) => {
  const {
    start,
    pause,
    resume,
    submit,
    sessionStatus,
    sessionType, // [!code ++] New in v0.2.2
    setSessionContext
  } = useAmbientSession({
    ambientSessionId: sessionId,
    onAudioChunkAvailable: (chunk) => {
      // Optional: Pass chunk to a waveform visualizer
      drawWaveform(chunk);
    }
  });

// Set context immediately after starting for better note quality
  const handleStart = async () => {
    await start();
    // Send patient and visit context to improve note generation
    await setSessionContext({
      patient: {
        dob: '1980-01-15',
        sex: 'M'
      },
      provider: {
        specialty: 'Cardiology',
        role: 'Attending Physician'
      },
      visit: {
        visit_type: 'Follow-up',
        encounter_type: 'Office Visit',
        reason_for_visit: 'Chest pain evaluation',
        chief_complaint: 'Chest pain'
      }
    });
  };

return (
    <div className="recorder-controls">
      <h3>Status: {sessionStatus}</h3>
      {sessionType === 'offline' && ( // [!code ++:2] added in v0.2.2
        <p className="offline-indicator">Session will sync when online</p>
      )}

<div className="button-group">
        {/* Start Button */}
        {sessionStatus === 'created' && (
          <button onClick={handleStart}>Start Recording</button>
        )}

{/* Pause/Resume Toggles - Add your own state tracking for recording/paused */}
        <button onClick={pause}>Pause</button>
        <button onClick={resume}>Resume</button>

{/* Finalize Button */}
        <button onClick={submit}>
          Finish & Submit
        </button>
      </div>
    </div>
  );
};
```

<Tip>
  Always call `setSessionContext` to provide patient and encounter details. This context helps the AI understand the clinical scenario and generates significantly higher quality clinical notes.
</Tip>

## Next steps

<Icon icon="file-lines" /> Learn production pause and submit patterns in [Session integration patterns](/headless-web-sdk/guides/integration-patterns).

<Icon icon="file-lines" /> Learn how to handle errors in the [Error handling guide](/headless-web-sdk/guides/error-handling).

# Authentication Hook
Source: https://developer.suki.ai/headless-web-sdk/guides/hooks/auth-hook

Learn how to use the useAuth hook to manage user identity, tokens, and login state in the Headless Web SDK

<span>Quick summary</span>
  </div>

<div>
    The `useAuth` hook manages user identity in the Suki Headless Web SDK. It gives your component the ability to **sign** users in, **register** new accounts, and **handle security tokens** automatically.

<br />

The hook returns status flags (`isLoggedIn`, `isPending`, `error`) and methods (`login()`, `registerUser()`) that you can use to authenticate users and manage their access to Suki services.
  </div>

<span>Last updated:</span>
    <span>May 2026</span>
  </div>
</div>

The **`useAuth`** hook allows you to manage user identity in the Suki Headless Web SDK. It exposes sign-in and registration methods, token updates, and status flags so your UI can react to authentication without wiring a low-level client through props.

In React, think of a hook as a plugin that gives your component specific abilities. In this case, `useAuth` gives your component the ability to **sign** users in,
**register** new accounts, and **handle security tokens** automatically.

## Configuration

The **`useAuth`** hook must run under **`PlatformClientProvider`** (with a shared **`PlatformClient`** at the app root). Refer to [Platform client and provider](/headless-web-sdk/api-reference/platform-client) for more information.

You also need a **`partnerId`** and **`partnerToken`**:

* **`partnerId`:** The unique ID you receive when you onboard with Suki.
* **`partnerToken`:** The secure access token for the user, generated by your EHR system.

<Note>
  If you do not have a **`partnerId`** and **`partnerToken`**, refer to the [Partner onboarding](/documentation/partner-onboarding) guide to learn how to get them.
</Note>

### Common use cases

<Steps>
  <Step title="Authenticate users" icon="user">
    Use **`login()`** when your application manages sign-in explicitly. Alternatively, enable **`loginOnMount`** to automatically attempt sign-in when the component mounts.

Use the returned authentication state values to manage UI and downstream workflows:

* **`isLoggedIn`** to determine whether the user is authenticated
    * **`isPending`** to display loading or disabled states during sign-in
    * **`data.accessToken`** to access the authenticated session token for subsequent API calls or hooks
  </Step>

<Step title="Register new users" icon="user-plus">
    Use **`registerUser()`** to implement an explicit user registration flow.

To automatically register users who do not already have an account, enable **`autoRegister`**. When **`autoRegister`** is set to `true`, you must also provide the following configuration values:

* **`providerOrgId`**
    * **`providerName`**
    * **`providerSpecialty`**

For configuration details, refer to [Configuration](#use-auth-hook-configuration) below.
  </Step>

<Step title="Refresh partner authentication tokens" icon="arrows-rotate">
    Call **`updatePartnerToken()`** whenever your host application issues a new **`partnerToken`**.

Refreshing the token ensures that active sessions remain authenticated and prevents session expiration during long-running workflows. For an implementation example, refer to [Code example](#code-example) below.
  </Step>

<Step title="Handle authentication and registration errors" icon="exclamation-triangle">
    Use **`error`** to inspect authentication and registration failures and implement retry or user-facing error handling logic.

For supported error codes and handling guidance, refer to [Error handling](/headless-web-sdk/guides/error-handling).
  </Step>
</Steps>

<Note>
  **Important:**

When **`autoRegister`** is `true`, **`providerOrgId`**, **`providerName`**, and **`providerSpecialty`** are required on the hook params so auto-registration can succeed.
</Note>

## useAuth hook

### Usage

Pass a configuration object with **`partnerId`**, **`partnerToken`**, and optional fields (`providerId`, **`autoRegister`**, **`loginOnMount`**, and provider metadata when auto-registration is on).

```tsx theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
const {
  data,
  error,
  isPending,
  isLoggedIn,
  login,
  registerUser,
  updatePartnerToken,
} = useAuth({
  partnerId, // Required
  partnerToken, // Required
  providerId, // Optional
  autoRegister, // Optional
  loginOnMount, // Optional
}); 
```

### Returns

The hook returns status fields and actions whose shapes are documented under [What you get](#what-you-get) (`isLoggedIn`, `isPending`, `data`, `error`, and `login()`, `registerUser()`, `updatePartnerToken()`).

### How the hook works

```mermaid actions={false} theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
flowchart TD
    A[Configure useAuth hook] --> B{Mounted?}
    B -->|yes| C[Call login automatically]
    B -->|no| D[Manual login]
    C --> E{Authentication status}
    D --> E
    E --> J[User authenticated]
    J --> L[Use Suki Headless Web SDK]
    
    style A fill:#FFF394,stroke:#D4A017,color:#000000
    style J fill:#FFF394,stroke:#D4A017,color:#000000
    style L fill:#FFF394,stroke:#D4A017,color:#000000
```

### Configuration

These are the settings you provide to set up the **auth** hook for Headless Web SDK in your application.

<ResponseField name="partnerId" type="string">
  The unique ID you receive when you first onboard with Suki.
</ResponseField>

<ResponseField name="partnerToken" type="string">
  The secure access token for the user, generated by your EHR system.
</ResponseField>

<ResponseField name="providerId" type="string">
  **Optional**: The unique ID of the provider in your EHR system.
</ResponseField>

<ResponseField name="autoRegister" type="boolean">
  **Optional**: If true, users will be automatically registered if they don't have an account yet. This saves you from building a separate registration flow. Default is `True`.
</ResponseField>

<ResponseField name="loginOnMount" type="boolean">
  **Optional**: If true, the hook attempts to sign the user in as soon as the component loads (mounts). Default is `True`.
</ResponseField>

<ResponseField name="providerOrgId" type="string">
  The unique ID of the organization in the Suki partner system to which the provider belongs.

This is <Badge>required</Badge> for auto-registration to work. If your `autoRegister` is set to `true`, you must provide this value.
</ResponseField>

<ResponseField name="providerName" type="string">
  The full name of the provider, including first name, middle name (if applicable), and last name separated by spaces.

This is <Badge>required</Badge> for auto-registration to work. If your `autoRegister` is set to `true`, you must provide this value.
</ResponseField>

<ResponseField name="providerSpecialty" type="string">
  The medical specialty of the provider, which helps tailor the SDK's functionality to specific clinical contexts.

This is <Badge>required</Badge> for auto-registration to work. If your `autoRegister` is set to `true`, you must provide this value.
</ResponseField>

```tsx theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
type UseAuthParams = {
  partnerId: string; // Required
  partnerToken: string; // Required
  autoRegister?: true; // This is a boolean value, Default is true
  loginOnMount?: boolean; // Optional 
  providerId?: string; // Optional
  providerName: string; // Required for auto-registration to work. If your `autoRegister` is set to `true`, you must provide this value.
  providerOrgId: string; // Required for auto-registration to work. If your `autoRegister` is set to `true`, you must provide this value.
  providerSpecialty?: string; // Required for auto-registration to work. If your `autoRegister` is set to `true`, you must provide this value.
} | {
  partnerId: string; // Required
  partnerToken: string; // Required
  autoRegister?: false; // Default is false
  loginOnMount?: boolean; // Optional
  providerId?: string; // Optional
}
```

## What you get

The hook returns everything you need to track the current status and take action.

### State

Use these values to update your UI (e.g., show a spinner while loading).

<ResponseField name="isLoggedIn" type="boolean">
  A boolean value that indicates whether the user is currently logged in. If `true`, the user is logged in and can use the Suki Headless Web SDK.
</ResponseField>

<ResponseField name="isPending" type="boolean">
  A boolean value that indicates whether the authentication process is currently in progress (e.g., logging in or registering). If `true`, the hook is working and you can show a spinner to the user.
</ResponseField>

<ResponseField name="data.accessToken" type="string">
  The active Suki session token. This is the token that is used to authenticate the user with the Suki Headless Web SDK.
</ResponseField>

<ResponseField name="error" type="PlatformError">
  An error object that contains details if something goes wrong while authenticating the user. Refer to the
  [Error handling](/headless-web-sdk/guides/error-handling) to check the possible error codes.
</ResponseField>

### Actions

Call these functions to perform tasks.

<ResponseField name="login()" type=" function: () => Promise<LoginResponse>">
  A **function** to start the login process for the user in your application. This function returns a promise that resolves to a `LoginResponse` object.

#### Login Response Example

```tsx theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
  type LoginResponse = { 
  suki_token: string;
  jwt_bearer: string
  }
  ```
</ResponseField>

<ResponseField name="registerUser" type=" function: (params: RegistrationRequest) => Promise<RegistrationResponse>">
  A **function** to start the registration process for a new user manually (using the provided partner credentials). This function returns a promise that resolves to a `RegistrationResponse` object.

#### Registration Response Example

```tsx theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
  type RegistrationResponse = Record<string, never>
  ```

<Note>
    Success results in an empty object. This means the user is registered successfully and you can now sign them in using the `login` function.
  </Note>
</ResponseField>

<ResponseField name="updatePartnerToken" type=" function: (partnerToken: string) => Promise<UpdatePartnerTokenResponse>">
  A **function** to update the partner token for the user. This function returns a promise that resolves to a `UpdatePartnerTokenResponse` object.

#### Update Partner Token Response Example

```tsx theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
  type UpdatePartnerTokenResponse = { 
  suki_token: string;
  jwt_bearer: string
  }
  ```
</ResponseField>

## Code example

Security tokens often expire and refresh while a user is working. If your application refreshes its token, you must tell the Suki Headless Web SDK so the user's voice session isn't interrupted.

You use `updatePartnerToken` to handle this seamlessly.

```tsx React expandable theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
import { useEffect } from 'react';
import { useAuth } from '@suki-sdk/platform-react';

export const SukiEmbed = ({ currentPartnerToken, partnerId }) => {
  // Initialize the hook
  const { updatePartnerToken, isLoggedIn, error } = useAuth({
    partnerId, // Required
    partnerToken: currentPartnerToken, // Required, The initial token
    loginOnMount: true,                // Optional, Sign in automatically
  });

// Listen for token changes from your parent app
  useEffect(() => {
    // If we are logged in and the parent app gives us a new token...
    if (isLoggedIn && currentPartnerToken) {
      // ...send it to Suki immediately.
      updatePartnerToken(currentPartnerToken)
        .catch((err) => console.error('Failed to update token:', err));
    }
  }, [currentPartnerToken, isLoggedIn, updatePartnerToken]);

if (error) {
    return <div>Error signing in: {error.message}</div>;
  }

return <div>Suki Assistant is ready</div>;
};
```

<Tip>
  Using `updatePartnerToken` is better than unmounting and remounting the component, as it keeps the user's connection to the Suki Headless Web SDK active and prevents dropped audio.
</Tip>

## Next steps

<Icon icon="file-lines" /> Refer to the [Ambient hook](/headless-web-sdk/guides/hooks/ambient-hook) guide to learn more about how to use it to start a voice session.

# Ambient Session Workflow Overview
Source: https://developer.suki.ai/headless-web-sdk/guides/hooks/hooks-overview

Overview of React hooks available in the Suki Headless Web SDK for authentication and ambient documentation workflows

<span>Quick summary</span>
  </div>

<div>
    The Suki Headless Web SDK provides three primary hooks to manage your ambient documentation workflow: `useAuth` for identity, `useAmbient` to create a session and obtain an `ambientSessionId`, and `useAmbientSession` to record, pause, resume, and submit audio for that session.
  </div>

<span>Last updated:</span>
    <span>April 2026</span>
  </div>
</div>

This section provides an overview of the React <Tooltip href="/Glossary/h">hooks</Tooltip> available in the Suki Headless Web SDK. Refer to the cards below for more information on each hook.

## Prerequisites

Before you begin, the following hooks require a `partnerId` and `partnerToken`:

* **`partnerId`** - The unique ID you receive when you first onboard with Suki
* **`partnerToken`** - The secure access token for the user, generated by your EHR system

<Note>
  If you do not have a `partnerId` and `partnerToken`, refer to the [Authentication guide](/headless-web-sdk/authentication) for more information.
</Note>

## Typical workflow

In React, a hook adds behavior to your components. The `useAuth`, `useAmbient`, and `useAmbientSession` hooks work together in a typical workflow:

```mermaid actions={false} theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
flowchart LR
  A[useAuth] --> B[useAmbient]
  B --> C[useAmbientSession]
  
  style A fill:#FFF394,stroke:#D4A017,color:#000000
  style B fill:#FFF394,stroke:#D4A017,color:#000000
  style C fill:#FFF394,stroke:#D4A017,color:#000000
```

## Hook implementation guides

Choose the guide for the hook you are implementing:

<CardGroup>
  <Card title="Authentication" icon="key" href="/headless-web-sdk/guides/hooks/auth-hook">
    Use this hook to manage authentication state for the Headless Web SDK.
  </Card>

<Card title="Create Ambient Session" icon="plus" href="/headless-web-sdk/guides/hooks/ambient-hook">
    Use this hook to create a session and obtain an `ambientSessionId`.
  </Card>

<Card title="Manage Ambient Session" icon="arrows-rotate" href="/headless-web-sdk/guides/hooks/ambient-session-hook">
    Use this hook to control recording and submit audio using the `ambientSessionId`.
  </Card>
</CardGroup>

# Headless Web SDK Integration Patterns
Source: https://developer.suki.ai/headless-web-sdk/guides/integration-patterns

Learn the best practices to implement recommended pause and submit patterns for useAmbientSession, and avoid mistakes that can discard audio or conflict with the Headless Web SDK

<span>Quick summary</span>
  </div>

<div>
    Use this guide to implement recommended patterns for pausing and submitting sessions with the `useAmbientSession` hook. By following these patterns, you ensure that Suki handles audio data correctly and you avoid conflicts with the Headless Web SDK.
  </div>

<span>Last updated:</span>
    <span>May 2026</span>
  </div>
</div>

The `useAmbientSession` hook provides the `pause()`, `setSessionContext()`, `submit()`, and `cancel()` methods. The Headless Web SDK manages buffering, queuing, and upload orchestration for you.

If you add custom recovery logic, you might accidentally discard valid audio or call methods in an incorrect order. Follow this guide to implement recommended patterns for pausing and submitting sessions with the `useAmbientSession` hook. By following these patterns, you ensure that Suki handles audio data correctly and you avoid conflicts with the Headless Web SDK.

## Built-in behavior

The Headless Web SDK manages buffering, queuing, and upload orchestration for you. You do not need to re-implement these features in your application:

* **Offline and network drops** - When the session is offline, the Headless Web SDK persists audio (for example in `IndexedDB`) and manages the upload queue. For details, refer to [Network transitions](/headless-web-sdk/guides/online-offline-behavior) and [Offline mode](/headless-web-sdk/guides/offline-mode) for more information.
* **Finalization with `submit()`** - Use `submit()` to complete the session and send captured audio to the Suki backend server for processing.
* **Recoverable pause errors** - A failed `pause()` call does not always mean session data or buffered audio is lost. Refer to [Pausing a session (PauseSessionFailed)](/headless-web-sdk/guides/error-handling#pausing-a-session-pausesessionfailed) in the error handling guide for more information. This guide covers how to handle these errors.

## Common mistakes to avoid

The following are common mistakes to avoid when using the `useAmbientSession` hook.

<AccordionGroup>
  <Accordion title="Retrying pause() from stale state">
    `sessionStatus` reflects the state of the last React render. If you call `pause()` again because the status has not updated yet, the API may return an `InvalidSessionState` error.

**Instead:** Call `pause()` once. If the request fails, log a warning and stop. Do not use `sessionStatus` as an immediate source of truth right after an `await pause()` call.
  </Accordion>

<Accordion title="Using cancel() as a fallback">
    The `cancel()` method is only for when a user explicitly abandons an encounter. It tears down the session and clears locally captured audio.

**Instead:** Do not call `cancel()` in a `catch` block to recover from non-abandon errors. That pattern can lead to lost submissions during offline recording.
  </Accordion>

<Accordion title="Hiding errors from destructive actions">
    If you use a destructive fallback like `cancel()` and ignore the failure, your UI may drift away from the actual SDK session state.

**Instead:** If you perform a destructive action, always surface failures to the user or your logging pipeline.
  </Accordion>
</AccordionGroup>

## Recommended flow

Follow this flow so your integration stays aligned with the Headless Web SDK:

<Steps>
  <Step title="Pause once">
    Call `pause()` a single time. On failure, log the error and stop.
  </Step>

<Step title="Set context (best effort)">
    Use `setSessionContext()` when you have fresh visit metadata. You can still call `submit()` when your product rules allow it, even if this step fails.
  </Step>

<Step title="Submit to finalize">
    Call `submit()` to upload queued chunks and complete the session.
  </Step>

<Step title="Reserve cancel() for discard">
    Only call `cancel()` when the user confirms they want to abandon the session.
  </Step>
</Steps>

## Code example

This example wraps `pause`, `setSessionContext`, and `submit` in a helper hook. Types follow [Session context](/headless-web-sdk/api-reference/types/session-context) and [UseAmbientSessionReturn](/headless-web-sdk/api-reference/types/use-ambient-session-return). Swap in your own `sessionContext`, `shouldSkipSubmit`, and callbacks.

```tsx React expandable theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
import { useCallback } from "react";

// Matches the SessionContext fields you send with setSessionContext (see API reference).
type SessionContext = {
  patient?: {
    dob: string;
    sex: string;
  };
  provider?: {
    specialty: string;
    role?: string;
  };
  visit?: {
    visit_type?: string;
    encounter_type?: string;
    reason_for_visit?: string;
    chief_complaint?: string;
  };
  sections?: Array<{ loinc: string }>;
  diagnoses?: {
    values: Array<{
      codes: Array<{
        code: string;
        description: string;
        type: string;
      }>;
      diagnosisNote: string;
    }>;
  };
};

// Empty success payload from setSessionContext; failures throw (see Session context types).
type SessionContextResponse = Record<string, never>;

// Methods and data passed in from your component that already called useAmbientSession.
type HandlersProps = {
  pause: () => Promise<void>;
  submit: () => Promise<void>;
  setSessionContext: (ctx: SessionContext) => Promise<SessionContextResponse>;
  sessionContext: SessionContext;
  shouldSkipSubmit: boolean;
  onSubmitSuccess: () => void;
  onSubmitError: (error: unknown) => void;
};

export function useAmbientSessionHandlers({
  pause,
  submit,
  setSessionContext,
  sessionContext,
  shouldSkipSubmit,
  onSubmitSuccess,
  onSubmitError,
}: HandlersProps) {
  const processSessionPause = useCallback(async () => {
    try {
      // One attempt only. Do not branch on stale sessionStatus and call pause() again.
      await pause();
    } catch (pauseError) {
      // Recoverable in many cases (for example stream close during a blip). Do not cancel() here.
      console.warn("[Suki] pause() failed", pauseError);
    }
  }, [pause]);

const handleSubmit = useCallback(async () => {
    if (shouldSkipSubmit) {
      return;
    }

try {
      // Best-effort metadata before finalize; still call submit() when your rules allow.
      await setSessionContext(sessionContext);
    } catch (contextError) {
      console.warn("[Suki] setSessionContext failed", contextError);
    }

try {
      // Authoritative finalize path: SDK uploads queued audio, including offline-captured chunks.
      await submit();
      onSubmitSuccess();
    } catch (error) {
      onSubmitError(error);
    }
  }, [
    shouldSkipSubmit,
    setSessionContext,
    sessionContext,
    submit,
    onSubmitSuccess,
    onSubmitError,
  ]);

return { processSessionPause, handleSubmit };
}
```

Pass the methods from `useAmbientSession` into the helper:

```tsx React theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
import { useAmbientSession } from "@suki-sdk/platform-react";

// ambientSessionId comes from useAmbient after session.create(); add onAudioChunkAvailable, audioBatchSize, etc. as needed.
const { pause, submit, setSessionContext } = useAmbientSession({
  ambientSessionId,
  // ...config, callbacks
});

const { processSessionPause, handleSubmit } = useAmbientSessionHandlers({
  pause,
  submit,
  setSessionContext,
  sessionContext: mySessionContext,
  shouldSkipSubmit: false,
  onSubmitSuccess: () => setSubmitted(true),
  onSubmitError: (err) => setError(String(err)),
});
```

## Next steps

<Icon icon="file-lines" /> Learn how to map errors to fixes in the [Error handling](/headless-web-sdk/guides/error-handling) guide.

<Icon icon="file-lines" /> Understand offline sessions in [Offline mode](/headless-web-sdk/guides/offline-mode).

# Offline Mode
Source: https://developer.suki.ai/headless-web-sdk/guides/offline-mode

Learn how to handle offline sessions in the Suki Headless Web SDK

<span>Quick summary</span>
  </div>

<div>
    You don't need to handle different offline scenarios separately. The `useOfflineSessions()` hook automatically manages everything, whether users have brief network interruptions or extended offline periods.

<br />

The hook tracks offline sessions, handles retries, and updates your UI with the latest status. You don't need to write complex logic for different scenarios.
  </div>

<span>Last updated:</span>
    <span>May 2026</span>
  </div>
</div>

The Suki Headless Web SDK provides a seamless offline experience for your users. It has an offline mode to keep your application working during network problems.

## Understanding offline sessions

An offline session is a recording that you have submitted but that has not yet reached the Suki backend server due to a network disconnection. The SDK detects when the device is offline and automatically queues these sessions. It distinguishes between brief hiccups and continuous outages:

* **Brief interruptions**: The SDK handles these transparently without triggering an offline session state. It uses a 15-second buffer to handle temporary connection problems.

* **Continuous disconnection**: The session is marked as offline and queued for synchronization once the connection returns.

### Estimated data usage

Audio files can be large. Use these estimates to plan for storage and bandwidth requirements:

| Recording duration | Approximate file size |
| ------------------ | --------------------- |
| 10 minutes         | \~19.2 MB             |
| 30 minutes         | \~57.6 MB             |

## Offline sessions hook (recommended)

The `useOfflineSessions` hook allows you to track the progress of sessions that are waiting to sync. You use this hook to build UI elements that show the user which files are pending, uploading, or finished.

### How it works

The hook returns a reactive list of **sessions** and a **subscription method** for listening to updates.

```javascript theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
const { sessions, on } = useOfflineSessions();
```

### What it returns

It returns the following values:

<Accordion title="Sessions">
  #### Sessions

This is an array of all current offline sessions. The array list automatically updates whenever a session's status changes (for example, when it moves from `uploading` to `complete`), so your UI always shows the latest information.

<Note>
    Each object in the array represents a single session and contains details about its submission status.
  </Note>

#### Session statuses

Sessions submitted while offline use the same `status` values as in the [Online/offline behavior](/headless-web-sdk/guides/online-offline-behavior#session-object-structure) guide. They reflect upload and backend processing:

| Session status | Description                                                                                           |
  | -------------- | ----------------------------------------------------------------------------------------------------- |
  | `idle`         | The session is queued locally and waiting for a network connection to begin uploading.                |
  | `uploading`    | The session is currently uploading to the Suki backend. Optional `progress` (0–100) may be available. |
  | `processing`   | Upload finished; the backend is processing the session (for example, generating the note).            |
  | `complete`     | Processing finished. Fetch the transcript or note using the session ID.                               |
  | `error`        | The submission or pipeline failed. The SDK may retry in the background.                               |
</Accordion>

<Accordion title="On">
  #### On

The `on` property lets you listen for session updates. Register a function that runs automatically whenever a session's status changes (for example, when it moves from `uploading` to `complete`).

<Note>
    This function returns a **cleanup function**. You must call this function to unsubscribe from the event and prevent memory leaks.
  </Note>
</Accordion>

## Example code

The following example demonstrates how to use the `useOfflineSessions` hook within a React component to display the status of sessions.

```JavaScript React expandable theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
import React, { useEffect } from 'react';
import { useOfflineSessions } from '@suki-sdk/platform-react';

function AmbientSessionMonitor() {
  // Destructure the sessions array and the 'on' subscription function
  const { sessions, on } = useOfflineSessions();

useEffect(() => {
    // Subscribe to session updates using the 'on' function
    const unsubscribe = on('ambient:offlineSessionsUpdate', (updatedSessions) => {
      console.log('Sessions updated:', updatedSessions);
      // Optionally update component state here if needed
    });

// The cleanup function is returned to unsubscribe when the component unmounts
    return () => unsubscribe();
  }, [on]); // Dependency array ensures the effect runs only if 'on' changes

return (
    <div>
      <h2>Ambient session status</h2>
      {sessions.length > 0 ? (
        <ul>
          {sessions.map(session => (
            <li key={session.id}>
              Session ID: {session.id} - Status: **{session.status}** ({session.sessionType})
            </li>
          ))}
        </ul>
      ) : (
        <p>No pending sessions.</p>
      )}
    </div>
  );
}

export default AmbientSessionMonitor;
```

## Direct subscription via PlatformClient (alternative)

We recommend using the `useOfflineSessions` hook for individual components. However, you may sometimes need to track session updates globally, for example, for **centralized logging or analytics**.

In these cases, you can subscribe to events directly on the `PlatformClient` instance using the `on` method.

### How it works

You listen for the `ambient:offlineSessionsUpdate` event. The client triggers your callback function whenever the list of offline sessions changes, providing the updated array of sessions.

### Example code

```JavaScript React expandable theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
import { PlatformClient, PlatformClientProvider } from '@suki-sdk/platform-react';

// Create a single client instance
const client = new PlatformClient({ env: 'staging', enableDebug: true, logLevel: 'error' });

function App() {

useEffect(()=>{
// Subscribe to events directly on the client instance
const unsubscribe =client.on('ambient:offlineSessionsUpdate', (sessions) => {
  console.log('Global pending sessions update:', sessions);
});
return () => unsubscribe();

},[])

return ();
}

export { App };
```

## Troubleshooting

<AccordionGroup>
  <Accordion title="How do we fetch the note later?">
    Watch for `status === 'complete'` in `useOfflineSessions()`.
  </Accordion>

<Accordion title="What if user offline for hours?">
    SDK retries every **15 minutes** plus immediately when browser goes online.
  </Accordion>

<Accordion title="Need to resubscribe after reload?">
    No - `useOfflineSessions()` auto-hydrates pending sessions.
  </Accordion>

<Accordion title="Is local audio cleaned up?">
    Yes - right after `status === 'complete'`.
  </Accordion>
</AccordionGroup>

## Next steps

<Icon icon="file-lines" /> Refer to the [Online/offline behavior](/headless-web-sdk/guides/online-offline-behavior) guide to understand how the SDK handles network connectivity and transitions between online and offline states.

# Network Transitions
Source: https://developer.suki.ai/headless-web-sdk/guides/online-offline-behavior

Understand how the Headless Web SDK handles network connectivity and transitions between online and offline states

<span>Quick summary</span>
  </div>

<div>
    The Headless Web SDK automatically manages transitions between online and offline states using a 15-second buffer. Brief network interruptions (≤15 seconds) are handled transparently without switching to offline mode.

<br />

Extended disconnections (>15 seconds) trigger offline mode, where audio chunks are stored in `IndexedDB` and queued for upload when the connection returns. This ensures your application handles network interruptions gracefully without interrupting the user experience.
  </div>

<span>Last updated:</span>
    <span>April 2026</span>
  </div>
</div>

The Headless Web SDK automatically manages transitions between online and offline states. Even if there is a brief network drop (up to around 15 seconds), Ambient will handle it automatically and continue as an online session.

Understanding how this works helps you build reliable applications that handle network interruptions gracefully.

## Online ↔ offline transitions

The SDK uses a smart buffering system (a 15 second buffer) to distinguish between brief network hiccups and actual offline periods. This prevents unnecessary interruptions to the user experience.

### How transitions work

The SDK monitors network connectivity and makes decisions based on how long the connection is lost:

| Network event                            | SDK behavior                    | Result                                                                                              |
| ---------------------------------------- | ------------------------------- | --------------------------------------------------------------------------------------------------- |
| Brief network interruption (≤15 seconds) | SDK buffers audio automatically | Session stays **ONLINE**; audio automatically resumes when connection returns                       |
| Extended disconnection (>15 seconds)     | SDK switches to offline mode    | Session switches to **OFFLINE**; audio stored locally and queued for upload when connection returns |

<Note>
  The SDK uses a **15-second buffer** to distinguish between brief network hiccups and actual offline periods. This gives the network a grace window to recover before the session fully switches to offline mode.
</Note>

### What this means for your application

* **Brief interruptions** (≤15 seconds): Even if there is a brief network drop (up to around 15 seconds), Ambient will handle it automatically and continue as an online session. The SDK buffers audio in memory and automatically streams it when the connection returns. Your users won't notice any interruption.

* **Extended disconnections** (>15 seconds): The SDK switches to offline mode, stores audio chunks in `IndexedDB`, and queues the session for upload when your network connection returns.

## Buffer size

To understand how the buffer works, it helps to know what a **"chunk"** represents:

### Chunk size calculation

The SDK processes audio in small chunks:

* **Recorder cadence**: 100 milliseconds (0.1 seconds)
* **Samples per chunk**: 16,000 Hz × 0.1 s = 1,600 PCM samples
* **Bytes per chunk**: 1,600 samples × 2 bytes (16-bit) = 3,200 bytes ≈ 3 kB before compression

### Max audio buffer size

When we say "MAX\_AUDIO\_BUFFER\_SIZE = 150", we mean:

* **150 chunks × 0.1 seconds** = 15 seconds of audio
* **150 chunks × 3 kB** = ≈450 kB raw audio (≈250 kB compressed) held in RAM

In simple terms: **"150 buffer size" = "store up to 150 consecutive 100 ms chunks"**.

This gives the network a **15-second grace window** before the session flips to OFFLINE mode.

<Note>
  The buffer is stored in RAM, which allows for fast recovery when brief network issues resolve quickly. Once the buffer exceeds 150 chunks (15 seconds), the SDK switches to offline mode and uses IndexedDB for persistent storage.
</Note>

## Observing offline sessions

To track offline sessions and their status changes, use the `useOfflineSessions` hook:

```javascript theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
import { useOfflineSessions } from '@suki-sdk/platform-react';
```

### Session object structure

Each session in the `sessions` array contains:

```javascript React  theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
{
  sessionId: string,
  status: 'idle' | 'uploading' | 'processing' | 'complete' | 'error',
  progress?: number // 0-100, available when status is 'uploading'
}
```

### Example code: monitoring session status

Iterate through sessions and react to status changes:

```javascript React expandable theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
const { sessions } = useOfflineSessions();

useEffect(() => {
  sessions.forEach(s => {
    if (s.status === 'uploading') {
      console.log(`Upload progress: ${s.progress}%`);
      // Show progress bar in your UI
    }
    
    if (s.status === 'complete') {
      fetchNote(s.sessionId);
      // Fetch the generated note/transcript
    }
  });
}, [sessions]);
```

### Event-based approach (alternative)

Subscribe to session updates using the `on` method:

```javascript React  theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
const { on } = useOfflineSessions();

useEffect(() => {
  const unsubscribe = on('ambient:offlineSessionsUpdate', (updatedSessions) => {
    console.log('Sessions updated:', updatedSessions);
    // Handle updates here
  });
  
  return () => unsubscribe();
}, [on]);
```

### Status mappings

Here's what you should do for each [session status](/headless-web-sdk/guides/offline-mode#session-statuses):

<CardGroup title="Session statuses">
  <Card title="Uploading" icon="spinner">
    Show a progress bar using the `progress` value (0-100)
  </Card>

<Card title="Complete" icon="check">
    Fetch the transcript/note using the `sessionId`
  </Card>

<Card title="Session Disappears" icon="trash">
    The SDK has automatically deleted the local copy after successful completion
  </Card>
</CardGroup>

## Important notes

<Note>
  **15-second buffer**: The SDK gives brief network interruptions time to recover before switching to offline mode.

**Automatic transitions**: You don't need to manually detect network changes — the SDK handles transitions automatically.

**Persistent storage**: Once offline mode is activated, audio is stored in IndexedDB and automatically uploaded when connectivity returns.

**Track with hooks**: Use [useOfflineSessions()](/headless-web-sdk/guides/offline-mode#offline-sessions-hook-recommended) to monitor session status and update your UI accordingly.
</Note>

# Headless Web SDK Installation
Source: https://developer.suki.ai/headless-web-sdk/installation

Install Suki Headless Web SDK in your React application

We have modularized the Suki Headless Web SDK into **framework-specific packages** so you only need to install the one that fits your environment.

The Headless Web SDK is built for modern React applications and requires an [ES6 compatible browser](https://caniuse.com/?search=es6).

## Prerequisites

For the rest of this documentation, we will assume you have completed the [Partner onboarding](/documentation/partner-onboarding) process.

Refer to the [Prerequisites](/headless-web-sdk/prerequisites) guide for more information.

## Install the package for React

For React applications, you should use the `@suki-sdk/platform-react` package. It includes React-specific hooks that make it easy to integrate Suki's headless web SDK functionality into your application.

To install the package, run one of the following commands:

<CodeGroup title="Install the @suki-sdk/platform-react package">
  ```shell pnpm theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
  pnpm add @suki-sdk/platform-react
  ```

```shell npm theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
  npm install @suki-sdk/platform-react
  ```

```shell yarn theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
  yarn add @suki-sdk/platform-react
  ```
</CodeGroup>

## Next steps

<Icon icon="file-lines" /> Read the [Quickstart guide](/headless-web-sdk/quickstart) to get started with the Suki Headless Web SDK.

# Headless Web SDK Overview
Source: https://developer.suki.ai/headless-web-sdk/introduction

A collection of React hooks and core functionality to build web applications on top of Suki ambient intelligence capabilities without pre-built UI components

The Suki Headless Web SDK provides **React hooks** and **core functionality** that let you integrate <Tooltip href="/Glossary/a">ambient</Tooltip> intelligence capabilities into your web application while maintaining complete control over your user interface.

Unlike the [Suki Web SDK](/web-sdk/overview), which includes pre-built UI components, the Headless Web SDK gives you the backend functionality and lets you design every aspect of the user experience. This approach gives you maximum flexibility to match your application's design system and user experience requirements.

## Supported platforms

The Headless Web SDK is currently supported on:

<CardGroup>
  <Card title="React" icon="react">
    The SDK provides React hooks optimized for React applications. Requires React **18.0** or higher.

Install the Headless Web SDK for React:

<div>
      <button>
        <span>Install for React</span>

<span><svg><polyline /></svg> Command Copied!</span>
      </button>
    </div>
  </Card>
</CardGroup>

## Key features

The Headless Web SDK provides all the core capabilities of the Suki platform:

<CardGroup>
  <Card title="Ambient note generation" icon="note">
    Capture clinical conversations and generate structured notes automatically
  </Card>

<Card title="Real-time audio streaming" icon="microphone">
    Receive real-time audio from the patient-provider conversation
  </Card>

<Card title="Session management" icon="clock">
    Full control over recording lifecycle (start, pause, resume, submit)
  </Card>
</CardGroup>

<CardGroup>
  <Card title="Custom UI integration" icon="paint-brush">
    Design your own recording interface, waveforms, and status indicators
  </Card>

<Card title="React hooks" icon="react">
    Simple, declarative API using React hooks for state management
  </Card>
</CardGroup>

## When to use Headless Web SDK

Choose the Headless Web SDK when:

* You want to embed ambient intelligence into your existing web application with a custom UI
* You need complete control over the user interface and user experience
* You want to match your application's existing design system and branding
* You need to optimize performance by controlling what UI components are rendered
* You're building a custom workflow that requires specific UI interactions

<Note>
  If you prefer pre-built UI components and want to get started quickly, consider using the [Suki Web SDK](/web-sdk/overview) instead.
</Note>

## How it works

The following diagram illustrates the Headless Web SDK architecture and workflow:

```mermaid actions={false} theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
%%{init: {'theme':'base', 'themeVariables': { 'primaryColor':'#FFE148','primaryTextColor':'#111827','lineColor':'#6B7280','fontSize':'14px','edgeLabelBackground':'#FFFFFF','tertiaryColor':'#F9FAFB','tertiaryTextColor':'#111827','tertiaryBorderColor':'#D1D5DB'}}}%%
graph TB
    subgraph client["Your web application"]
        direction TB
        A["Application code<br/><small>React application</small>"]
        B["Headless Web SDK<br/><small>@suki-sdk/platform-react</small>"]
        C["Your own UI<br/><small>Your design • Recording controls • Status display</small>"]
        A --> B
        B --> C
    end
    
    subgraph platform["Suki backend"]
        direction TB
        D["Authentication service<br/>"]
        E["Ambient service<br/>"]
        F["AI engine<br/>"]
    end
    
    B -->|Authenticate| D
    C -->|Stream audio| E
    E -->|Process| F
    F -->|Return results| C
    
    style client fill:#FFFADE,stroke:#D1D5DB,stroke-width:2px,color:#111827
    style platform fill:#FFF394,stroke:#FFE148,stroke-width:2px,color:#111827
    style A fill:#ffffff,stroke:#9CA3AF,stroke-width:2px,color:#111827
    style B fill:#FFE148,stroke:#111827,stroke-width:3px,color:#111827
    style C fill:#ffffff,stroke:#9CA3AF,stroke-width:2px,color:#111827
    style D fill:#ffffff,stroke:#9CA3AF,stroke-width:2px,color:#111827
    style E fill:#ffffff,stroke:#9CA3AF,stroke-width:2px,color:#111827
    style F fill:#ffffff,stroke:#9CA3AF,stroke-width:2px,color:#111827
```

### Architecture workflow

<Steps>
  <Step title="Client side (your web application)" icon="user">
    * Your React application that integrates the Headless Web SDK
    * React SDK package (`@suki-sdk/platform-react`) that provides React hooks for authentication, session management, and recording control
    * Your custom UI components built using the hook state and methods for recording controls, status display, and visualization
  </Step>

<Step title="Suki backend" icon="server">
    * **Authentication Service**: Validates user credentials and manages session tokens
    * **Ambient Service**: Handles audio streaming, session management, and real-time transcription
    * **AI Engine**: Processes audio data and generates structured clinical notes
  </Step>

<Step title="Data flow" icon="arrow-right">
    1. Create `PlatformClient`, wrap the app with `PlatformClientProvider`, then use `useAuth` with partner credentials -> Authenticate with Suki backend
    2. Create ambient session using `useAmbient` hook -> Get `ambientSessionId`
    3. Initialize `useAmbientSession` hook with the `ambientSessionId` -> Get recording controls
    4. Build custom UI using hook state and methods
    5. User starts recording using `start()` method -> SDK streams audio to Ambient Service
    6. AI Engine processes audio and generates notes
    7. Results return through hooks -> Your custom UI displays the note and transcript
  </Step>
</Steps>

## Next steps

Get started by following these steps:

<Icon icon="file-lines" /> Refer to the [Installation guide](/headless-web-sdk/installation) to add the package to your project

<Icon icon="file-lines" /> Refer to the [Quickstart](/headless-web-sdk/quickstart) for `PlatformClient` and `PlatformClientProvider`, then the [Authentication hook](/headless-web-sdk/guides/hooks/auth-hook) guide for `useAuth`

<Icon icon="file-lines" /> Refer to the [Create ambient session](/headless-web-sdk/guides/hooks/ambient-hook) guide to create an ambient session

<Icon icon="file-lines" /> Refer to the [Manage ambient session](/headless-web-sdk/guides/hooks/ambient-session-hook) guide to manage the ambient session

# Headless Web SDK Prerequisites
Source: https://developer.suki.ai/headless-web-sdk/prerequisites

Requirements and setup needed before integrating the Suki Headless Web SDK

This guide outlines the technical requirements your application must meet to integrate with the Suki Platform headless web SDK.

### Browser support

Your application must use a browser that is **ES6-compatible**. Check the full compatibility list [here](https://caniuse.com/?search=es6).

### Authentication requirements

Your authentication system must meet the following requirements:

* It must be OAuth-compliant.

* It must provide a JWT token that contains a consistent, unique user identifier.

* It must have a publicly accessible JWKS endpoint for token signature validation.

For more information on the authentication requirements, refer to the [Partner authentication](/documentation/partner-authentication) guide.

## Information you must provide

As a Suki development partner, you must provide the following items to your Suki contact before you can integrate the Suki Headless Web SDK:

* **Partner name**: A unique name that identifies your EMR/EHR.

* **JWKS endpoint**: The publicly accessible URL that Suki will use to validate the signature on user JWT tokens. This is provided by your identity provider.

* **User identifier field**: The specific key name in your JWT token that uniquely identifies a user. This can be email, username, userId, sub, or another field that represents the user uniquely in your system.

* **Host URLs**: The public URLs for your test and production client applications where you will embed the Suki Headless Web SDK. We need these URLs to add your application to our allowlist.

## Information you will receive from Suki

Before you can start the integration, your Suki contact will provide you with the following:

* **Partner ID**: A unique identifier issued by Suki. You must send this `partnerId` when you initialize the Suki Headless Web SDK.

For more information on the information you will receive from Suki, refer to the [Partner onboarding](/documentation/partner-onboarding) guide.

# Headless Web SDK Quickstart
Source: https://developer.suki.ai/headless-web-sdk/quickstart

Get started with the Suki Headless Web SDK, from installation to your first recording

This guide walks you through setting up the Suki Headless Web SDK in your React application, from installation to creating your first ambient recording session.

**What you will do**

1. **Install** `@suki-sdk/platform-react` in your React project.
2. **Wrap** your app with **`PlatformClient`** and **`PlatformClientProvider`** at the root so all SDK hooks share one client.
3. **Authenticate** with **`useAuth`** inside that tree so users are signed in and tokens are available.
4. **Create** an ambient session with `useAmbient`, then **control recording** with `useAmbientSession` (start, pause, resume, submit, and optional context).
5. **Wire up** a minimal end-to-end flow using the complete example as a reference.

<Tip>
  **Using an AI coding tool?**

npx skills add [https://developer.suki.ai](https://developer.suki.ai)

## Prerequisites

For the rest of this documentation, we assume the following setup is complete:

* You have received your `partnerId` from Suki.
* Your host URLs are on the Suki allowlist.
* Your partner configuration in the Suki Platform points to your correct JWKS endpoint.
* Your JWT token contains the key that you specified as your **User identifier field**.

Refer to the [Prerequisites](/headless-web-sdk/prerequisites) guide for more information.

## Install the package

To begin, install the Suki Headless Web SDK package in your React project:

<CodeGroup title="Install the @suki-sdk/platform-react package">
  ```shell pnpm theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
  pnpm add @suki-sdk/platform-react
  ```

```shell npm theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
  npm install @suki-sdk/platform-react
  ```

```shell yarn theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
  yarn add @suki-sdk/platform-react
  ```
</CodeGroup>

For detailed setup instructions, refer to the [Installation guide](/headless-web-sdk/installation).

## Required configuration

Create a single **`PlatformClient`** instance and wrap your entire application with **`PlatformClientProvider`**. Hooks such as `useAuth`, `useAmbient`, and `useAmbientSession` must run under this provider.

```tsx React expandable theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
import { PlatformClient, PlatformClientProvider } from '@suki-sdk/platform-react';

const client = new PlatformClient({
  env: "staging",
  enableDebug: true,
  logLevel: "error"
});

function App() {
  return (
    <PlatformClientProvider>
      <YourApp />
    </PlatformClientProvider>
  );
}
```

## Authenticate with useAuth

After the provider wraps your app, use **`useAuth`** in a child component (for example **`YourApp`**). This hook manages user identity and provides access tokens needed for all SDK operations.

```tsx React expandable theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
import { useAuth } from '@suki-sdk/platform-react';

function YourApp() {
  const {
    isLoggedIn,
    isPending,
    error,
    login
  } = useAuth({
    partnerId: 'your-partner-id', // Required: Replace with your actual partner ID
    partnerToken: 'your-partner-token', // Required: Replace with your actual partner token
    autoRegister: true, // Optional: Automatically register users if they don't exist
    loginOnMount: true, // Optional: Sign in automatically when component mounts
    providerName: 'Dr. John Doe', // Required for auto-registration
    providerOrgId: 'org-123', // Required for auto-registration
    providerSpecialty: 'Cardiology' // Required for auto-registration
  });

if (isPending) {
    return <div>Signing in...</div>;
  }

if (error) {
    return <div>Error: {error.message}</div>;
  }

if (!isLoggedIn) {
    return <button onClick={login}>Sign In</button>;
  }

return <div>Ready to use Suki Headless Web SDK</div>;
}
```

<Note>
  If you set `autoRegister: true`, you must provide `providerName`, `providerOrgId`, and `providerSpecialty`. If you prefer manual registration, set `autoRegister: false` and use the `registerUser` method. See the [Authentication hook guide](/headless-web-sdk/guides/hooks/auth-hook) for more details.
</Note>

## Create ambient session

Once authenticated, create an ambient session using the `useAmbient` hook. This creates a session container that you'll use for recording.

```tsx React expandable theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
import { useEffect } from 'react';
import { useAmbient } from '@suki-sdk/platform-react';

function SessionCreator({ onSessionReady }) {
  const {
    ambientSessionId,
    session: { create, isPending, isSuccess, error }
  } = useAmbient();

// Create session when component mounts
  useEffect(() => {
    create();
  }, [create]);

// Pass session ID to parent when ready
  useEffect(() => {
    if (isSuccess && ambientSessionId) {
      onSessionReady(ambientSessionId);
    }
  }, [isSuccess, ambientSessionId, onSessionReady]);

if (isPending) {
    return <div>Creating session...</div>;
  }

if (error) {
    return <div>Error: {error.message}</div>;
  }

return null;
}
```

<Note>
  You must wait for `isSuccess` to be `true` before attempting to use the `ambientSessionId`. Passing an undefined ID to the recording hooks will cause errors.
</Note>

## Manage recording

Use the `useAmbientSession` hook to control recording. This hook provides methods to start, pause, resume, and submit recordings, along with session status.

```tsx React expandable theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
import { useAmbientSession } from '@suki-sdk/platform-react';

function Recorder({ sessionId }) {
  const {
    start,
    pause,
    resume,
    submit,
    sessionStatus,
    sessionType, // [!code ++] New in v0.2.2
    setSessionContext
  } = useAmbientSession({
    ambientSessionId: sessionId,
    onAudioChunkAvailable: (chunk) => {
      // Optional: Use audio chunks for visualization
      console.log('Audio chunk received:', chunk);
    }
  });

// Set session context after starting
  const handleStart = async () => {
    await start();
    // Provide context to improve note generation
    await setSessionContext({
      patient: {
        dob: '1980-01-15',
        sex: 'M'
      },
      provider: {
        specialty: 'Cardiology',
        role: 'Attending Physician'
      },
      visit: {
        visit_type: 'Follow-up',
        encounter_type: 'Office Visit',
        reason_for_visit: 'Chest pain evaluation',
        chief_complaint: 'Chest pain'
      }
    });
  };

return (
    <div>
      <h3>Status: {sessionStatus}</h3>
      {sessionType === 'offline' && ( // [!code ++:2] added in v0.2.2
        <p>Session will sync when online</p>
      )}
      
      {sessionStatus === 'created' && (
        <button onClick={handleStart}>Start Recording</button>
      )}
      
      {sessionStatus === 'recording' && (
        <>
          <button onClick={pause}>Pause</button>
          <button onClick={submit}>Finish & Submit</button>
        </>
      )}
      
      {sessionStatus === 'paused' && (
        <>
          <button onClick={resume}>Resume</button>
          <button onClick={submit}>Finish & Submit</button>
        </>
      )}
    </div>
  );
}
```

<Tip>
  Always use `setSessionContext` to provide relevant patient or encounter details. This context acts as a hint for the AI, resulting in significantly higher quality clinical notes.
</Tip>

## Complete example

Here's a complete example that brings everything together:

```tsx React expandable theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
import { useState, useEffect } from 'react';
import {
  PlatformClient,
  PlatformClientProvider,
  useAuth,
  useAmbient,
  useAmbientSession
} from '@suki-sdk/platform-react';

const client = new PlatformClient({
  env: 'staging',
  enableDebug: true,
  logLevel: 'error'
});

function App() {
  return (
    <PlatformClientProvider>
      <SukiRecorder />
    </PlatformClientProvider>
  );
}

function SukiRecorder() {
  const [sessionId, setSessionId] = useState(null);

// Step 1: Authenticate (under PlatformClientProvider)
  const { isLoggedIn, isPending: authPending } = useAuth({
    partnerId: 'your-partner-id', // Required: Replace with your actual partner ID
    partnerToken: 'your-partner-token', // Required: Replace with your actual partner token
    autoRegister: true, // Optional: Automatically register users if they don't exist
    loginOnMount: true, // Optional: Sign in automatically when component mounts
    providerName: 'Dr. John Doe', // Required for auto-registration
    providerOrgId: 'org-123', // Required for auto-registration
    providerSpecialty: 'Cardiology' // Required for auto-registration
  });

// Step 2: Create session
  const {
    ambientSessionId,
    session: { create, isSuccess: sessionCreated }
  } = useAmbient();

useEffect(() => {
    if (isLoggedIn && !sessionCreated) {
      create();
    }
  }, [isLoggedIn, sessionCreated, create]);

useEffect(() => {
    if (ambientSessionId) {
      setSessionId(ambientSessionId);
    }
  }, [ambientSessionId]);

if (authPending) {
    return <div>Authenticating...</div>;
  }

if (!isLoggedIn) {
    return <div>Please sign in</div>;
  }

if (!sessionId) {
    return <div>Creating session...</div>;
  }

## Next steps

Refer to the following guides to learn more:

<Icon icon="file-lines" /> [Platform client and provider](/headless-web-sdk/api-reference/platform-client) - Understand how to use `PlatformClient` and `PlatformClientProvider`

<Icon icon="file-lines" /> [Authentication hook](/headless-web-sdk/guides/hooks/auth-hook) - Learn more about authentication options and token management

<Icon icon="file-lines" /> [Create ambient session](/headless-web-sdk/guides/hooks/ambient-hook) - Understand session creation in detail

<Icon icon="file-lines" /> [Manage ambient session](/headless-web-sdk/guides/hooks/ambient-session-hook) - Explore all recording controls and session context

<Icon icon="file-lines" /> [Error handling](/headless-web-sdk/guides/error-handling) - Learn how to handle errors gracefully

<Icon icon="file-lines" /> [Offline mode](/headless-web-sdk/guides/offline-mode) - Understand how the SDK handles network interruptions

# Clearing Sessions
Source: https://developer.suki.ai/mobile-sdk/ambient-guides/clearing-sessions

Learn how to clear all locally stored Suki sessions from the device in the mobile SDK

<span>Quick summary</span>
  </div>

<div>
    The `clear()` method removes all locally stored Suki sessions from the device. The primary use case is to clear user-specific data when a user signs out of your application, ensuring data privacy and preparing the SDK for a new user session.

<br />

You cannot call `clear()` during an active session; it will throw an error. Always ensure no sessions are active before calling this method.
  </div>

<span>Last updated:</span>
    <span>May 2026</span>
  </div>
</div>

**What will you learn?**

In this guide, you will learn how to:

* Clear all locally stored Suki sessions from the device by calling the `clear()` method.
* Handle errors from the `clear()` method.

## Clear all sessions

Remove all locally stored Suki sessions from the device by calling the `clear()` method.

The primary use case for this method is to **clear user-specific data** when a user **signs out** of your application. This ensures data privacy and prepares the SDK for a new user session.

<Warning>
  Do not call the `clear()` method during an **active session**; this will throw an error.
</Warning>

<CodeGroup>
  ```swift Swift theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
  do {
      // Removes all persisted session data from the device.
      try SukiAmbientCore.shared.clear()
  } catch {
      // Handle potential errors.
      print(error)
  }
  ```
</CodeGroup>

## FAQs

<AccordionGroup>
  <Accordion title="Why can't I call the `clear()` method during an active session?">
    The `clear()` method is used to clear all locally stored Suki sessions from the device. If you call this method during an active session, it will throw an error.
  </Accordion>

<Accordion title="`clear()` method is not working">
    The `clear()` method is not working because the SDK is not initialized. You must ensure that the SDK is initialized before calling the `clear()` method.
  </Accordion>

<Accordion title="How do I know if the `clear()` method has been called?">
    Check the `sessionState` property to determine the current state of the session.
  </Accordion>

<Accordion title="`clear()` method is clearing all sessions but the data is not being deleted">
    The data is not being deleted because the SDK is not initialized. You must ensure that the SDK is initialized before calling the `clear()` method.
  </Accordion>

<Accordion title="How to Initialize the SDK?">
    Initialize the SDK by calling the `initialize()` method.
  </Accordion>
</AccordionGroup>

## Next steps

<Icon icon="file-lines" /> After you clear the sessions, proceed to our [Session events & delegates](/mobile-sdk/ambient-guides/events-and-delegates) guide to listen to the session events.

# Create Session
Source: https://developer.suki.ai/mobile-sdk/ambient-guides/create-session

Learn how to create an ambient session and enrich it with detailed clinical context in the iOS SDK

<span>Quick summary</span>
  </div>

<div>
    The `createSession(withSessionInfo:)` method creates a new ambient session and returns a `sessionId` that you use for all subsequent operations. Optionally provide session context like patient information, provider specialty, and note sections to improve note quality. The method handles the session creation asynchronously and returns a result that you can use to track success or handle errors. Store the `sessionId` securely as you'll need it for recording controls and content retrieval.
  </div>

<span>Last updated:</span>
    <span>May 2026</span>
  </div>
</div>

Before you can start recording audio and generating clinical notes, you must create an ambient session. This guide shows you how to create a session and provide clinical context that helps Suki generate more accurate notes.

**What will you learn?**

In this guide, you will learn how to:

* Create an ambient session using the `createSession(withSessionInfo:)` method
* Store the session ID returned from session creation for future operations

## Create an ambient session

To start capturing audio and generating notes, you must first create a session. The session acts as a container that holds all the audio data and context for a single patient encounter.

***

Call the `createSession(withSessionInfo:)` method to create a new session. When successful, this method returns a `sessionId` that you **must store** to use for recording and retrieving content later.

<CodeGroup>
  ```swift Swift theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
  let createSession = [
      SukiAmbientConstant.kSessionId: <encounter-id>,
      SukiAmbientConstant.kIsMultilingual: isMultilingual
  ] as [String : AnyHashable]

SukiAmbientCoreManager.shared.createSession(with: sessionContext, onCompletion: { result in
      switch result {
      case .success(let sessionResponse):
          // Store the sessionId from sessionResponse for future use
          let sessionId = sessionResponse.sessionId
          print("Session created successfully: \(sessionId)")
      case .failure(let error):
          print("Error creating session: \(error)")
      }
  })
  ```
</CodeGroup>

### Session info parameters

The `withSessionInfo` dictionary accepts the following optional parameters:

<ResponseField name="SukiAmbientConstant.kSessionId" type="string">
  An optional unique identifier for the session. If you don't provide this, the SDK automatically generates a session ID for you. Use this if you want to use your own encounter ID or session identifier.
</ResponseField>

<ResponseField name="SukiAmbientConstant.kMultilingual" type="boolean">
  Enables multilingual processing for the session. Set this to `true` if the conversation will be in languages other than English. The default value is `false` (English only). Once set, this cannot be changed for the session.
</ResponseField>

<Note>
  **Important**: Always store the `sessionId` returned from `createSession`. You'll need it to:

* Start recording
  * Check session status
  * Retrieve generated content
  * Update session context
</Note>

## Next steps

<Icon icon="file-lines" /> Refer to the [Provide clinical context](/mobile-sdk/ambient-guides/provide-clinical-context) guide to learn how to provide clinical context to the ambient session for better note quality in the iOS SDK.

<Icon icon="file-lines" /> After you create a session and optionally set context, proceed to the [Recording controls](/mobile-sdk/ambient-guides/recording) guide to learn how to start recording and manage the recording lifecycle.

# Session Events & Delegates
Source: https://developer.suki.ai/mobile-sdk/ambient-guides/events-and-delegates

Learn how to use the session events and delegates to handle the session lifecycle in the mobile SDK

<span>Quick summary</span>
  </div>

<div>
    The SDK uses a delegate pattern to broadcast important events during a session's lifecycle. By conforming to the `SukiAmbientSessionDelegate` protocol and implementing `sukiAmbient(sessionEvent:for:)`, you receive real-time updates about session state changes.

<br />

Use a switch statement to handle specific events like `.started`, `.paused`, `.suggestionsGenerated`, or `.convertedToOfflineSession` to update your UI or handle errors accordingly.
  </div>

<span>Last updated:</span>
    <span>April 2026</span>
  </div>
</div>

The SDK uses a delegate pattern to broadcast important events that occur during a session's lifecycle. By conforming to the `SukiAmbientSessionDelegate` protocol, you can receive real-time updates and respond to state changes in your application, such as updating your UI or handling errors.

**What will you learn?**

In this guide, you will learn how to:

* Use the `SukiAmbientSessionDelegate` protocol.
* Implement the `sukiAmbient(sessionEvent:for:)` method.
* Handle the events that are relevant to your application using a switch statement.

## How to implement the session delegate

#### 1. Conform to the protocol

First, declare that your class conforms to the `SukiAmbientSessionDelegate` protocol. You must also pass an **instance** of this delegate class when you initialize the SDK.

#### 2. Implement the delegate method

Next, implement the `sukiAmbient(sessionEvent:for:)` method. The SDK calls this method every time a new session event occurs, providing the event type and the associated `recordingId`.

Use a **switch statement** within this method to handle the events that are relevant to your application.

<CodeGroup>
  ```swift Swift theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
  extension YourViewController: SukiAmbientSessionDelegate {
      func sukiAmbient(sessionEvent event: SukiAmbientCore.SessionEvent, for recordingId: SukiAmbientCore.RecordingId) {
          // This method receives all session events for a given recording ID.
          print("Received event: \(event) for recording ID: \(recordingId)")

// Use a switch statement to handle specific events.
          switch event {
          case .started:
              // Update your UI to show that recording has started.
              break
          case .suggestionsGenerated:
              // Notify the user that their note is ready.
              break
          case .convertedToOfflineSession:
              // Inform the user about the network issue.
              break
          // Handle other cases as needed for your app's logic.
          default:
              break
          }
      }
  }
  ```
</CodeGroup>

## Available session events

The `SessionEvent` enum provides the following cases, which are grouped by category for clarity.

#### Recording lifecycle

<ResponseField name="SessionEvent" type="enum">
  Recording lifecycle events for ambient sessions.

<Expandable title="cases">
    <ResponseField name="started" type="case">
      Triggered when the recording starts.
    </ResponseField>

<ResponseField name="resumed" type="case">
      Triggered when the recording resumes after being paused.
    </ResponseField>

<ResponseField name="paused" type="case">
      Triggered when the recording is paused.
    </ResponseField>

<ResponseField name="ended" type="case">
      Triggered when the recording ends.
    </ResponseField>

<ResponseField name="cancelled" type="case">
      Triggered when the recording is cancelled.
    </ResponseField>
  </Expandable>
</ResponseField>

#### Content generation

<ResponseField name="SessionEvent" type="enum">
  Content generation events for note suggestions.

<Expandable title="cases">
    <ResponseField name="suggestionGenerationInProgress" type="case">
      Triggered when suggestion generation begins.
    </ResponseField>

<ResponseField name="suggestionsGenerated" type="case">
      Triggered when suggestions are successfully generated.
    </ResponseField>

<ResponseField name="suggestionsGenerationFailed" type="case">
      Triggered when suggestion generation fails.
    </ResponseField>
  </Expandable>
</ResponseField>

#### Offline mode & uploading

<ResponseField name="SessionEvent" type="enum">
  Offline mode and audio upload events.

<Expandable title="cases">
    <ResponseField name="convertedToOfflineSession" type="case">
      Triggered when session is converted to offline mode.
    </ResponseField>

<ResponseField name="pendingOfflineUpload" type="case">
      Triggered when offline audio is pending upload.
    </ResponseField>

<ResponseField name="preparingOfflineUpload" type="case">
      Triggered when preparing offline audio for upload.
    </ResponseField>

<ResponseField name="uploadingAudio" type="case">
      Triggered when audio upload is in progress.
    </ResponseField>

<ResponseField name="audioUploaded" type="case">
      Triggered when audio is successfully uploaded.
    </ResponseField>

<ResponseField name="audioUploadFailed" type="case">
      Triggered when audio upload fails.
    </ResponseField>

<ResponseField name="audioUploadAllRetryFailed" type="case">
      Triggered when all audio upload retry attempts fail.
    </ResponseField>

<ResponseField name="processingUpload" type="case">
      Triggered when uploaded audio is being processed.
    </ResponseField>

<ResponseField name="processingUploadFailed" type="case">
      Triggered when upload processing fails.
    </ResponseField>
  </Expandable>
</ResponseField>

#### Audio interruptions

<ResponseField name="SessionEvent" type="enum">
  Audio interruption events during recording.

<Expandable title="cases">
    <ResponseField name="audioInterruptionStarted" type="case">
      Triggered when audio interruption begins (e.g., phone call).
    </ResponseField>

<ResponseField name="audioInterruptionEnded" type="case">
      Triggered when audio interruption ends.
    </ResponseField>
  </Expandable>
</ResponseField>

#### All available session events cases

Below is the complete list of all available session events cases:

<CodeGroup>
  ```swift Swift theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
  public enum SessionEvent {
      case started
      case resumed
      case paused
      case ended
      case cancelled
      case suggestionGenerationInProgress
      case suggestionsGenerated
      case suggestionsGenerationFailed
      case audioInterruptionStarted
      case audioInterruptionEnded
      case convertedToOfflineSession
      case pendingOfflineUpload
      case preparingOfflineUpload
      case uploadingAudio
      case audioUploadFailed
      case audioUploadAllRetryFailed
      case audioUploaded
      case processingUpload
      case processingUploadFailed
      case clearingBufferredAudio
      case clearedBufferredAudio
      case audioBufferFilled(withPercentage: Double) // [!code ++] New in v2.4.0
  }
  ```
</CodeGroup>

## FAQs

<AccordionGroup>
  <Accordion title="Do I have any other events to listen to?">
    Yes, you can listen to the following events:

* `sessionEvent`
    * `recordingId`
  </Accordion>

<Accordion title="Can I create a new case inside the `SessionEvent` enum?">
    No, you cannot create a new case inside the `SessionEvent` enum. You must use the existing cases.
  </Accordion>

<Accordion title="Why do we need so many cases for the `SessionEvent` enum?">
    We have so many cases because we want to be able to handle all the possible events that can occur during a session.
  </Accordion>
</AccordionGroup>

# Offline Mode
Source: https://developer.suki.ai/mobile-sdk/ambient-guides/offline-mode

Learn how the Mobile SDK handles network interruptions and enters offline mode in the mobile SDK

<span>Quick summary</span>
  </div>

<div>
    The Mobile SDK has an offline mode to keep your application working during network problems. When the SDK enters offline mode, it continues to record and store audio securely on the device, saves all session events, and automatically uploads everything when the connection returns.

<br />

The SDK uses a 15-second buffer to handle temporary connection problems before switching to offline mode. This gives you time to show a notification in your UI before the session goes fully offline.
  </div>

<span>Last updated:</span>
    <span>April 2026</span>
  </div>
</div>

The **Mobile SDK** has an **offline** mode to keep your application working during network problems. This ensures a session is not interrupted if the device loses its internet connection.

**What will you learn:**

In this guide, you will learn how to:

* Handle network interruptions gracefully using the offline mode.
* Understand the network buffer feature and its importance.
* Identify the common causes for offline mode.

## What happens in offline mode

When the SDK enters **offline** mode, it handles everything in the background so the user is not interrupted. The SDK will:

* Continue to record and store audio securely on the device.

* Save all session events that happen during the outage.

* Automatically upload all saved audio and events when the connection returns.

The SDK notifies your app about these status changes using **session delegate** events.

### Network buffer feature

Before, the SDK used to directly jump into offline mode when it detected a small network issue. This was not ideal as it would interrupt the user experience.

To address this, the mobile SDK uses a **15-second buffer** to handle temporary connection problems. This gives you time to show a notification in your UI, like **Connection unstable**, before the session goes fully offline. This is important to ensure a smooth user experience.

## Common causes for offline mode

A session can enter **offline** mode for several reasons:

* Poor or lost Wi-Fi or cellular connectivity.

* The device switches between networks (e.g., Wi-Fi to cellular).

* A temporary problem with the backend service.

* A dropped connection while streaming audio.

* An issue with an authentication token.

<Tip>
  **Important notes**

Keep the following key features of **offline** mode in mind:

* The SDK manages all transitions between **offline** and **online** modes automatically.

* Audio quality and session integrity are always maintained.

* The SDK can **queue multiple offline** sessions and will upload them in order once a connection is available.

* All data stored locally on the device is encrypted and secure.

* Offline recording is optimized to conserve battery life.
</Tip>

# Provide Additional Clinical Context
Source: https://developer.suki.ai/mobile-sdk/ambient-guides/provide-clinical-context

Learn how to provide additional clinical context to the ambient session in the iOS SDK for better note generation

<Callout type="updates" icon="bell">
  **Updated:**

Starting with Mobile SDK `v2.6.0+` on iOS SDK, you can attach structured **medication orders** to an ambient session's context by passing `SukiAmbientConstant.kOrdersInfo` into `setSessionContext(with:)` after you create the session.

Learn more in the [Medication orders](/mobile-sdk/ambient-guides/provide-clinical-context#orders-info) section.
</Callout>

<span>Quick summary</span>
  </div>

<div>
    The `setSessionContext(with:)` method in the mobile SDK allows you to provide optional clinical context to the ambient session for better note generation. This context helps Suki generate more accurate and relevant clinical notes.
    Call `setSessionContext(with:)` multiple times. Each call updates or adds to the existing context. This allows you to provide information as it becomes available in your app.
  </div>

<span>Last updated:</span>
    <span>May 2026</span>
  </div>
</div>

After creating a session, you can provide additional clinical information using the `setSessionContext(with:)` method. This context helps Suki's AI generate more accurate and relevant clinical notes.

<Note>
  All context parameters mentioned below are **optional**. Use one or more of these parameters to help Suki generate more accurate and relevant clinical notes. The absence of any parameter will not break existing functionality.
</Note>

**Why provide context?**

* **Better note quality**: More accurate sections and diagnoses
* **Specialty-specific formatting**: Notes match your medical specialty
* **Structured organization**: Notes organized by the sections you need
* **Diagnosis accuracy**: Better identification of conditions discussed

## Set session context (optional but recommended)

After the session is created, call `setSessionContext(with:)` and pass a dictionary of optional parameters. In one call you can mix patient info, provider context, visit context, EMR info, note sections, diagnosis info, and medication orders, or send just one of them. For each parameter, see the keys and types in [Additional context parameters](/mobile-sdk/ambient-guides/provide-clinical-context#additional-context-parameters). If you do not have data for a parameter yet, leave it out of the dictionary; call `setSessionContext(with:)` again when you want to add or change values.

<Note>
  Call `setSessionContext(with:)` multiple times. Each call updates or adds to the existing context. This allows you to provide information as it becomes available in your app.
</Note>

<CodeGroup>
  ```swift Swift expandable theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
  do {
      let contextDetail: [String: AnyHashable] = [
          SukiAmbientConstant.kPatientInfo: [
              SukiAmbientConstant.kBirthdate: Date(), // Use yyyy-mm-dd format
              SukiAmbientConstant.kGender: "MALE"
          ],
          SukiAmbientConstant.kProviderContext: [
              SukiAmbientConstant.kSpeciality: "FAMILY_MEDICINE",
              SukiAmbientConstant.kProviderRole: "PRIMARY/ATTENDING" // [!code ++] New in v2.5.0: Optional provider role (Primary/Attending or Consulting)
          ],
          SukiAmbientConstant.kVisitContext: [ 
            // [!code ++:5] New in v2.5.0: Visit context parameters for improved note generation
              SukiAmbientConstant.kVisitType: "ESTABLISHED_PATIENT", // Optional: New Patient / Intake, Established patient, Wellness, ED
              SukiAmbientConstant.kEncounterType: "AMBULATORY", // Optional: ambulatory, inpatient, ED
              SukiAmbientConstant.kReasonForVisit: "Annual checkup", // Optional: String, max 255 characters
              SukiAmbientConstant.kChiefComplaint: "Routine follow-up" // Optional: String, max 255 characters
          ],

SukiAmbientConstant.kEmrInfo: [ // [!code ++:2] New in v2.6.0: Optional EMR info (string)
              SukiAmbientConstant.kTargetEmr: "<emr_identifier>" // Required: which EMR this session uses (string)
          ],
          SukiAmbientConstant.kSections: [
              [SukiAmbientConstant.kCode: "51848-0", SukiAmbientConstant.kCodeType: "loinc"],
              [SukiAmbientConstant.kCode: "11450-4", SukiAmbientConstant.kCodeType: "loinc"]
          ],
          SukiAmbientConstant.kDiagnosisInfo: [
              [
                  SukiAmbientConstant.kDiagnosisNote: "Patient presents with chest pain",
                  SukiAmbientConstant.kCodes: [
                      [
                          SukiAmbientConstant.kCodeType: "ICD-10",
                          SukiAmbientConstant.kCode: "R06.02",
                          SukiAmbientConstant.kCodeDescription: "Shortness of breath"
                      ]
                  ]
              ]
          ],
          // [!code ++:23] New in v2.6.0: medication orders context parameter for suggesting medication orders
          SukiAmbientConstant.kOrdersInfo: [ 
              MedicationOrderKeys.kMedicationOrders: [
                  [
                      MedicationOrderKeys.kDrugName: "Atorvastatin",
                      MedicationOrderKeys.kMedicationCode: [
                          SukiAmbientConstant.kCodeType: "<code_type>", // required; coded values must match a supported catalog in your SDK version
                          SukiAmbientConstant.kCode: "<code>" // required
                      ],
                      MedicationOrderKeys.kStrength: "10 mg", // required
                      MedicationOrderKeys.kFormat: "tablet", // required
                      MedicationOrderKeys.kRoute: "oral", // required
                      MedicationOrderKeys.kLinkedDiagnosisCodes: [
                          [
                              SukiAmbientConstant.kCodeType: "ICD-10",
                              SukiAmbientConstant.kCode: "E78.5"
                          ]
                      ],
                      MedicationOrderKeys.kMetadata: [
                          MedicationOrderKeys.kOrigin: "EMR",
                          MedicationOrderKeys.kEncounterRelation: "CURRENT_ENCOUNTER"
                      ]
                      // Optional: MedicationOrderKeys.kDosage, kFrequency, kMedicationTiming, kStatus, kQuantityDispensed, kNumberOfRefills, kStartDate, kEndDate, kDurationInDays, kInstructions, etc

]
              ]
          ]
      ]
      
      try SukiAmbientCore.shared.setSessionContext(with: contextDetail) { result in
          switch result {
          case .success:
              print("Context updated successfully")
          case .failure(let error):
              print("Error updating context: \(error)")
          }
      }
  } catch {
      print(error)
  }
  ```
</CodeGroup>

<Warning>
  Call `setSessionContext(with:)` only **after** a session has been successfully created. Call `createSession` first and wait for it to succeed before calling `setSessionContext`.
</Warning>

<Tip>
  **Retrieve the generated note and structured data**

After you call `setSessionContext` with your additional clinical context (such as provider, patient, or visit details), you can use the Suki Mobile SDK to retrieve your results.

Use the `content(for:)` method to retrieve the generated clinical note and extracted blocks. To pull structured output once processing completes, call `getStructuredData(for:)`. The structured output includes all data the service produces from your specific context, including diagnoses and medication order payloads.

For more information on how to retrieve these elements, read our guide on [Session status and content retrieval](/mobile-sdk/ambient-guides/session-status-and-content-retrieval#get-structured-data).
</Tip>

## Additional context parameters

### Patient info

<ResponseField name="SukiAmbientConstant.kPatientInfo" type="dictionary">
  Use this parameter to provide demographic information that helps personalize the note generation.

<Expandable title="properties">
    <ResponseField name="SukiAmbientConstant.kBirthdate" type="date">
      Patient's date of birth in yyyy-mm-dd format.
    </ResponseField>

<ResponseField name="SukiAmbientConstant.kGender" type="string">
      Patient's gender. Valid values: "MALE" or "FEMALE".
    </ResponseField>
  </Expandable>
</ResponseField>

### Provider context

<ResponseField name="SukiAmbientConstant.kProviderContext" type="dictionary">
  Use this parameter to provide information about the healthcare provider to tailor note generation to your specialty and role.

<Expandable title="properties">
    <ResponseField name="SukiAmbientConstant.kSpeciality" type="string">
      The provider's medical specialty (e.g., "FAMILY\_MEDICINE", "CARDIOLOGY"). This helps format notes according to your specialty's conventions.
    </ResponseField>

<ResponseField name="SukiAmbientConstant.kProviderRole" type="string">
      The provider's role in the encounter. Valid values: "Primary/Attending" or "Consulting". This helps distinguish between primary care providers and consulting specialists.
    </ResponseField>
  </Expandable>
</ResponseField>

### Visit context

<ResponseField name="SukiAmbientConstant.kVisitContext" type="dictionary">
  Use this parameter to provide visit-related metadata that provides context about the type and purpose of the encounter.

<Expandable title="properties">
    <ResponseField name="SukiAmbientConstant.kVisitType" type="string">
      The type of patient visit. Valid values: "New Patient / Intake", "Established patient", "Wellness", "ED". This helps format notes appropriately for the visit type.
    </ResponseField>

<ResponseField name="SukiAmbientConstant.kEncounterType" type="string">
      The setting where the encounter occurs. Valid values: "ambulatory", "inpatient", "ED". This helps structure notes for the appropriate care setting.
    </ResponseField>

<ResponseField name="SukiAmbientConstant.kReasonForVisit" type="string">
      A free-text description explaining why the patient is visiting. Maximum 255 characters. This helps focus the note on the primary reason for the visit.
    </ResponseField>

<ResponseField name="SukiAmbientConstant.kChiefComplaint" type="string">
      The patient's primary complaint or concern. Maximum 255 characters. This helps structure the note's chief complaint section.
    </ResponseField>
  </Expandable>
</ResponseField>

### EMR info

<ResponseField name="SukiAmbientConstant.kEmrInfo" type="dictionary">
  Use this parameter to identify which EMR applies to an ambient session. Provide a string identifier that matches what your integration and Suki use for that EMR (for example a vendor code or environment-specific label).

<Expandable title="properties">
    <ResponseField name="SukiAmbientConstant.kTargetEmr" type="string">
      The target EMR for this encounter. Provide a string identifier that matches what your integration and Suki use for that EMR (for example a vendor code or environment-specific label).
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="SukiAmbientConstant.kSections" type="array of dictionaries">
  An array of LOINC codes that specify which clinical note sections you want in the generated note. Each dictionary contains a LOINC code.

<Note>
    You only need to provide LOINC codes. The SDK automatically generates the appropriate clinical section titles based on the codes you provide.
  </Note>

**Code example**:

```swift Swift  theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
  SukiAmbientConstant.kSections: [
      [SukiAmbientConstant.kCode: "51848-0", SukiAmbientConstant.kCodeType: "loinc"],
      [SukiAmbientConstant.kCode: "11450-4", SukiAmbientConstant.kCodeType: "loinc"]
  ]
  ```
</ResponseField>

### Diagnosis info

<ResponseField name="SukiAmbientConstant.kDiagnosisInfo" type="array of dictionaries">
  Structured diagnosis information that helps the AI identify and code conditions discussed during the encounter. Each dictionary represents one diagnosis.

<Expandable title="properties">
    <ResponseField name="SukiAmbientConstant.kDiagnosisNote" type="string">
      A text note describing the diagnosis or condition.
    </ResponseField>

<ResponseField name="SukiAmbientConstant.kCodes" type="array of dictionaries">
      An array of diagnosis codes. Each code dictionary must contain:

<Expandable title="code properties">
        <ResponseField name="SukiAmbientConstant.kCodeType" type="string">
          The coding system used (e.g., "ICD-10", "IMO", "SNOMED").
        </ResponseField>

<ResponseField name="SukiAmbientConstant.kCode" type="string">
          The actual diagnosis code.
        </ResponseField>

<ResponseField name="SukiAmbientConstant.kCodeDescription" type="string">
          A human-readable description of what the code represents. Recommended for clarity.
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

### Orders info

<Warning>
  This feature is not enabled by default. To enable it, contact Suki to request access (if not already enabled).
</Warning>

<ResponseField name="SukiAmbientConstant.kOrdersInfo" type="dictionary">
  Use this parameter to provide information about medications relevant to a patient visit, such as existing prescriptions or the patient's current medication list.

The data is structured as a single bundle. On the wire, the outer payload key is `orders`. Inside this bundle, you must include a single list keyed by `MedicationOrderKeys.kMedicationOrders` (wire string `medication_orders`). Each entry in this list represents a single medication order and must be formatted as an individual dictionary.

You can skip `kOrdersInfo` entirely if it is not required for your workflow. If you do send the `MedicationOrderKeys.kMedicationOrders` list, each order in that list must satisfy the following requirements.

<Warning>
    Missing information or incomplete metadata fails with `invalidMedicationOrder`. If you include `origin` or `encounter_relation` under `metadata`, each value must be non-empty and match one of the allowed choices. Values that do not match can fail parsing with `invalidOrderMetadata`.
  </Warning>

**Payload keys**

You must include the following payload (wire) keys for every order in the `MedicationOrderKeys.kMedicationOrders` array:

* `medication_code`: You must include both `code_type` and `code`.

* `linked_diagnosis_codes`: You must include at least one item containing both `code_type` and `code`.

* `metadata.origin` and `metadata.encounter_relation`: You must use only the approved values for these fields.

<Warning>
    When you use optional fields that carry **codes** (`medication_code.code_type`, `dosage.unit`, `frequency`, `medication_timing`, `status`), the SDK checks them against its own supported lists.
    Use only values that your SDK already accepts to avoid validation errors.
  </Warning>

**Code example**:

```swift Swift  theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
  SukiAmbientConstant.kOrdersInfo: [
      MedicationOrderKeys.kMedicationOrders: [
          [
              MedicationOrderKeys.kDrugName: "Atorvastatin", // required
              MedicationOrderKeys.kMedicationCode: [
                  SukiAmbientConstant.kCodeType: "<code_type>", // required
                  SukiAmbientConstant.kCode: "<code>" // required
              ],
              MedicationOrderKeys.kStrength: "10 mg", // required
              MedicationOrderKeys.kFormat: "tablet", // required
              MedicationOrderKeys.kRoute: "oral", // required
              MedicationOrderKeys.kLinkedDiagnosisCodes: [
                  [SukiAmbientConstant.kCodeType: "ICD-10", SukiAmbientConstant.kCode: "E78.5"]
              ],
              MedicationOrderKeys.kMetadata: [
                  MedicationOrderKeys.kOrigin: "EMR",
                  MedicationOrderKeys.kEncounterRelation: "CURRENT_ENCOUNTER"
              ]
          ]
      ]
  ]
  ```

<Expandable title="properties">
    Each object in the `MedicationOrderKeys.kMedicationOrders` array can include the following. The **payload keys** checklist above defines the minimum; the `ResponseField` entries use Swift constant names for the same rules.

<ResponseField name="MedicationOrderKeys.kDrugName" type="string">
      The medication name. Required when this order is included in the array.
    </ResponseField>

<ResponseField name="MedicationOrderKeys.kMedicationCode" type="dictionary">
      The coded medication identifier. Required when this order is included.

<Expandable title="medication_code properties">
        <ResponseField name="SukiAmbientConstant.kCodeType" type="string">
          The coding system for the medication code. Required for validation. Must match a supported catalog when you send a coded value.
        </ResponseField>

<ResponseField name="SukiAmbientConstant.kCode" type="string">
          The medication code. Required for validation. Must match a supported catalog when you send a coded value.
        </ResponseField>
      </Expandable>
    </ResponseField>

<ResponseField name="MedicationOrderKeys.kStrength" type="string">
      The medication strength (for example dosage amount with unit). Required when this order is included.
    </ResponseField>

<ResponseField name="MedicationOrderKeys.kFormat" type="string">
      The dose form (for example tablet, capsule). Required when this order is included.
    </ResponseField>

<ResponseField name="MedicationOrderKeys.kRoute" type="string">
      The route of administration. Required when this order is included.
    </ResponseField>

<ResponseField name="MedicationOrderKeys.kDosage" type="dictionary">
      Optional structured dosage information.

<Expandable title="dosage properties">
        <ResponseField name="MedicationOrderKeys.kRawValue" type="string">
          Free-text dosage as entered in your system.
        </ResponseField>

<ResponseField name="MedicationOrderKeys.kQuantity" type="number">
          Numeric quantity for the dose.
        </ResponseField>

<ResponseField name="MedicationOrderKeys.kUnit" type="string">
          Unit for the quantity. When used as a coded field, must match a supported catalog.
        </ResponseField>
      </Expandable>
    </ResponseField>

<ResponseField name="MedicationOrderKeys.kFrequency" type="dictionary">
      Optional dosing frequency. Uses the same inner keys as `MedicationOrderKeys.kMedicationTiming`.

<Expandable title="frequency properties">
        <ResponseField name="MedicationOrderKeys.kRawValue" type="string">
          Free-text frequency.
        </ResponseField>

<ResponseField name="MedicationOrderKeys.kStructuredValue" type="string">
          Structured frequency value. When used as a coded field, must match a supported catalog.
        </ResponseField>
      </Expandable>
    </ResponseField>

<ResponseField name="MedicationOrderKeys.kQuantityDispensed" type="string">
      Quantity dispensed.
    </ResponseField>

<ResponseField name="MedicationOrderKeys.kNumberOfRefills" type="integer">
      Number of refills.
    </ResponseField>

<ResponseField name="MedicationOrderKeys.kStartDate" type="date">
      Start date for the order when you supply it through context bridging.
    </ResponseField>

<ResponseField name="MedicationOrderKeys.kEndDate" type="date">
      End date for the order.
    </ResponseField>

<ResponseField name="MedicationOrderKeys.kDurationInDays" type="integer">
      Duration of therapy in days.
    </ResponseField>

<ResponseField name="MedicationOrderKeys.kInstructions" type="string">
      Patient- or pharmacy-facing instructions.
    </ResponseField>

<ResponseField name="MedicationOrderKeys.kMedicationTiming" type="dictionary">
      Optional timing details for the medication. Same shape as `MedicationOrderKeys.kFrequency`.

<Expandable title="medication_timing properties">
        <ResponseField name="MedicationOrderKeys.kRawValue" type="string">
          Free-text timing.
        </ResponseField>

<ResponseField name="MedicationOrderKeys.kStructuredValue" type="string">
          Structured timing value. When used as a coded field, must match a supported catalog.
        </ResponseField>
      </Expandable>
    </ResponseField>

<ResponseField name="MedicationOrderKeys.kLinkedDiagnosisCodes" type="array of dictionaries">
      Required for validation: at least one object. Each array element uses `code_type` and `code` (`SukiAmbientConstant.kCodeType` and `SukiAmbientConstant.kCode` in Swift).

<Expandable title="code properties">
        <ResponseField name="SukiAmbientConstant.kCodeType" type="string">
          The coding system for the diagnosis (for example "ICD-10"). Must match a supported catalog when you send a coded value.
        </ResponseField>

<ResponseField name="SukiAmbientConstant.kCode" type="string">
          The diagnosis code. Must match a supported catalog when you send a coded value.
        </ResponseField>
      </Expandable>
    </ResponseField>

<ResponseField name="MedicationOrderKeys.kStatus" type="string">
      Order status. When used as a coded field, must match a supported catalog.
    </ResponseField>

<ResponseField name="MedicationOrderKeys.kMetadata" type="dictionary">
      Provenance for the order. Required when this order is included. You must set both `origin` and `encounter_relation` under `metadata` (use `MedicationOrderKeys.kOrigin` and `MedicationOrderKeys.kEncounterRelation` in Swift). Each value must be non-empty after trim and must be one of the allowed strings below.

<Expandable title="metadata properties">
        <ResponseField name="MedicationOrderKeys.kOrigin" type="string">
          **Payload key** `origin`. Where the order came from. Valid values: `SUKI_AMBIENT`, `EMR`.
        </ResponseField>

<ResponseField name="MedicationOrderKeys.kEncounterRelation" type="string">
          **Payload key** `encounter_relation`. How the order relates to the encounter. Valid values: `PRIOR_ENCOUNTER`, `CURRENT_ENCOUNTER`.

<Note>
            This field is **required** if the origin is EMR.
          </Note>
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

## Best practices

Follow these practices to ensure reliable session management:

<Tip>
  * **Always initialize the SDK first**: Make sure `SukiAmbientCore.shared.initialize()` has been called successfully before creating a session.

* **Store the session ID**: Save the `sessionId` returned from `createSession` immediately. You'll need it for all subsequent operations.

* **Handle errors properly**: Use the completion handler's result to check for success or failure. Display appropriate error messages to users.

* **Provide context when available**: Call `setSessionContext` with any clinical information you have. Even partial context improves note quality.

* **Medication orders**: If you send `MedicationOrderKeys.kMedicationOrders` under `kOrdersInfo`, include every required field per order and valid metadata values, or the SDK can reject the update.

* **Call setSessionContext after createSession**: Wait for `createSession` to succeed before calling `setSessionContext`.

* **Handle background limitations**: On iOS, you cannot start a recording while the app is in the background. Ensure your app is active before starting a recording.
</Tip>

## FAQs

<AccordionGroup>
  <Accordion title="Why is session creation failing?">
    Session creation can fail for several reasons:

**Common causes:**

* SDK not initialized: Make sure you've called `initialize()` before creating a session
    * Invalid partner information: Check that your partner ID and provider information are correct
    * Network connectivity issues: Ensure the device has an active internet connection
    * Authentication token problems: Verify your token provider is returning valid tokens
    * Missing microphone permissions: Ensure your app has microphone access permissions

**How to debug:**
    Check the error returned in the completion handler's `.failure` case. The error will indicate the specific reason for failure.
  </Accordion>

<Accordion title="Why isn't my session context updating?">
    The session context may not update if:

* **Session not created**: You must call `createSession` first and wait for it to succeed
    * **Method not called**: Ensure you're actually calling `setSessionContext` after session creation
    * **Invalid parameters**: Check that specialty strings and codes match the expected formats. For medication orders, confirm every required field per order, valid `metadata` values, and at least one linked diagnosis code object
    * **Network error**: The update request may have failed due to connectivity issues

**How to verify:**
    Check the completion handler result. If it returns `.failure`, examine the error to understand what went wrong.
  </Accordion>

<Accordion title="Can I start recording immediately after creating a session?">
    Yes, once `createSession` succeeds and returns a `sessionId`, you can start recording. However, it's recommended to call `setSessionContext` first if you have clinical context available, as this improves note quality.

The typical flow is:

1. Create session → Get sessionId
    2. Set session context (optional but recommended)
    3. Start recording
  </Accordion>
</AccordionGroup>

## Next steps

# Recording Controls
Source: https://developer.suki.ai/mobile-sdk/ambient-guides/recording

Learn how to manage the full lifecycle of an ambient session using the recording controls in the mobile SDK

<span>Quick summary</span>
  </div>

<div>
    The Mobile SDK provides recording control methods to manage the full lifecycle of an ambient session. Use `start`, `pause`, `resume`, `end`, and `cancel` to control recordings with full state management.

<br />

Each method handles errors and returns results asynchronously. The SDK manages session state transitions automatically, so you can update your UI based on the current state and handle errors appropriately.
  </div>

<span>Last updated:</span>
    <span>May 2026</span>
  </div>
</div>

The **Mobile SDK** provides you the capability to manage the full lifecycle of an ambient session using the following recording controls. These methods allow you to **start**, **pause**, **resume**, and **stop** a recording with full state management.

**What will you learn?**

In this guide, you will learn how to:

* Handle the recording lifecycle using the `start`, `pause`, `resume`, `end`, and `cancel` methods.
* Handle errors from the recording control methods.
* Understand the best practices for handling user interactions with the recording controls.

## Prerequisites

Before calling any of these methods, always ensure the SDK is **initialized** and a session has been **created** to prevent runtime errors.

<Warning>
  iOS does not allow an app to start a recording while it is in the background. If you attempt this, the SDK will throw an `appIsNotActive` error. You should handle this case by notifying the user.
</Warning>

## Recording controls

These are the recording controls that are available in the **Mobile SDK**:

### Start recording

Begin capturing audio by calling the `start` method. This transitions the session into the `Recording` state.

***

<CodeGroup>
  ```swift Swift theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
  do {
      // Begins the recording process for the active session.
      try SukiAmbientCore.shared.start()
  } catch {
      // Handle potential errors, e.g., session not initialized.
      print(error)
  }
  ```
</CodeGroup>

### Pause recording

To temporarily stop capturing audio while keeping the session active, call the `pause` method. This transitions the session into the `Paused` state.

<CodeGroup>
  ```swift Swift theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
  do {
      // Pauses the current recording. The session remains active.
      try SukiAmbientCore.shared.pause()
  } catch {
      // Handle errors, e.g., no active recording to pause.
      print(error)
  }
  ```
</CodeGroup>

### Resume recording

If a session is paused, you can call the `resume` method to continue capturing audio. This transitions the session into the `Recording` state.

<CodeGroup>
  ```swift Swift theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
  do {
      // Resumes a paused recording.
      try SukiAmbientCore.shared.resume()
  } catch {
      // Handle errors, e.g., the session was not in a paused state.
      print(error)
  }
  ```
</CodeGroup>

### End session

To stop the recording and begin the content generation process, call the `end` method. This is the standard way to complete a session successfully.

<CodeGroup>
  ```swift Swift theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
  do {
      // Ends the recording and triggers the note generation process.
      try SukiAmbientCore.shared.end()
  } catch {
      // Handle errors, e.g., the session was already ended.
      print(error)
  }
  ```
</CodeGroup>

### Cancel session

To stop the recording and discard all captured data, call the `cancel` method. This action cannot be **undone**.

<CodeGroup>
  ```swift Swift theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
  do {
      // Stops the recording and aborts the session. No content will be generated.
      try SukiAmbientCore.shared.cancel()
  } catch {
      // Handle potential errors.
      print(error)
  }
  ```
</CodeGroup>

## Error handling

All recording control methods can throw a `SukiAmbientCoreError`. You must use a **do-catch** block to handle potential issues, such as calling a method from an invalid state.

## FAQs

<AccordionGroup>
  <Accordion title="Why can't I start a recording in the background?">
    iOS does not allow an app to start a recording while it is in the background. If you attempt this, the SDK will throw an `appIsNotActive` error. You should handle this case by notifying the user.
  </Accordion>

<Accordion title="What happens if I call a method from an invalid state?">
    All recording control methods can throw a `SukiAmbientCoreError`. You must use a **do-catch** block to handle potential issues, such as calling a method from an invalid state.
  </Accordion>

<Accordion title="How do I handle errors from the recording control methods?">
    All recording control methods can throw a `SukiAmbientCoreError`. You must use a **do-catch** block to handle potential issues, such as calling a method from an invalid state.
  </Accordion>

<Accordion title="Do I need to call the `end` method to generate a note?">
    Yes, you must call the `end` method to generate a note. The `end` method transitions the session into the `Ended` state, which is required for note generation.
  </Accordion>

<Accordion title="Can I cancel a session after it has been ended?">
    No, you cannot cancel a session after it has been ended. The `cancel` method transitions the session into the `Canceled` state, and a canceled session cannot generate a note.
  </Accordion>

<Accordion title="Can I pause and resume a session?">
    Yes, you can pause and resume a session. The `pause` and `resume` methods transition the session into the `Paused` and `Recording` states, respectively.
  </Accordion>

<Accordion title="Can I start a recording after it has been ended?">
    No, you cannot start a recording after it has been ended. The `start` method transitions the session into the `Recording` state, which is required for note generation.
  </Accordion>

<Accordion title="As a developer, how do I know if a session has been ended?">
    Check the `sessionState` property to determine the current state of the session.
  </Accordion>

<Accordion title="What is the best way to handle user interactions with the recording controls?">
    You should use the `sessionState` property to determine the current state of the session and only enable the recording controls when the session is in the `Recording` state.
  </Accordion>

<Accordion title="If the user cancels a session, what happens to the audio and session data?">
    If the user cancels a session, the audio and session data will be discarded.
  </Accordion>
</AccordionGroup>

## Next steps

<Icon icon="file-lines" /> After you have started a recording, you can proceed to the [Session status & retrieve content](/mobile-sdk/ambient-guides/session-status-and-content-retrieval) guide to check the status of the session and retrieve the generated content.

# Session Status & Retrieve Content
Source: https://developer.suki.ai/mobile-sdk/ambient-guides/session-status-and-content-retrieval

Learn how to check the processing status and retrieve the generated content of a session in the mobile SDK

<Callout type="updates" icon="bell">
  **Updated:**

Starting with Mobile SDK `v2.6.0+` on iOS SDK, you can retrieve Medication orders using the `getStructuredData(for:)` method.

Learn more in the [Get structured data API](/mobile-sdk/ambient-guides/session-status-and-content-retrieval#get-structured-data) section.
</Callout>

<span>Quick summary</span>
  </div>

<div>
    The Mobile SDK provides methods to check processing status and retrieve generated content after a session ends. Check status using `status(for:)`, retrieve clinical notes with `content(for:)`, get transcripts with `transcript(for:)`, and access structured data with `getStructuredData(for:)`.

<br />

All methods are asynchronous and require a valid `recordingId`. Submit user feedback on AI-generated content using `submitFeedback(_:for:onCompletion:)` to help improve future note generation.
  </div>

<span>Last updated:</span>
    <span>May 2026</span>
  </div>
</div>

The Suki Mobile SDK provides methods to check the processing status and retrieve the generated content of a session. Use these methods to track the progress of your session and retrieve the generated content after it has been completed.

**What will you learn?**

In this guide, you will learn how to:

* Check the processing status of a session using the `status(for:)` method.
* Retrieve generated content by calling the `content(for:)` method to get clinical note suggestions.
* Retrieve the full transcript of the conversation using the `transcript(for:)` method.
* Get structured data, such as generated diagnoses and entities, using the `getStructuredData(for:)` method.
* Submit user feedback on AI-generated content using the `submitFeedback(_:for:onCompletion:)` method, including both quantitative and qualitative data.
* Handle asynchronous results using a completion handler for all retrieval methods.
* Understand and adhere to constraints for submitting feedback, including providing feedback only once per entity type per session.

<Note>
  Before calling any of these methods, you must ensure that the mobile SDK is **initialized** and that you are using a valid `recordingId` from an active or completed session.
</Note>

## Check status and retrieve content

After you end a session, you can asynchronously check its processing status and retrieve the generated content. You must provide a valid `recordingId` for the session you want to query.

***

The diagram below illustrates the process of retrieving the generated content of a session.

```mermaid actions={false} theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
%%{init: {'theme':'base', 'themeVariables': { 'primaryColor':'#FFF394','primaryTextColor':'#1a1a1a','primaryBorderColor':'#FFE148','lineColor':'#FFE148','secondaryColor':'#FFE148','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':'#1a1a1a','nodeTextColor':'#1a1a1a'}}}%%
graph TD
    A[Start: You have a valid recordingId] --> B{Call a retrieval method, passing the ID}
    B --> C[SDK performs an asynchronous operation...]
    C --> D{Completion Handler is called with a Result}
    D -->|Success| E[Process the returned content<br/>e.g., display suggestions, transcript]
    D -->|Failure| F[Handle the returned error]
    E --> G[End]
    F --> G[End]
    
    style A fill:#FFF394,stroke:#FFE148,stroke-width:2px,color:#1a1a1a
    style B fill:#FFE148,stroke:#FFE148,stroke-width:2px,color:#1a1a1a
    style C fill:#FFF394,stroke:#FFE148,stroke-width:2px,color:#1a1a1a
    style D fill:#FFE148,stroke:#FFE148,stroke-width:2px,color:#1a1a1a
    style E fill:#FFF394,stroke:#FFE148,stroke-width:2px,color:#1a1a1a
    style F fill:#FFF394,stroke:#FFE148,stroke-width:2px,color:#1a1a1a
    style G fill:#FFF394,stroke:#FFE148,stroke-width:2px,color:#1a1a1a
```

***

All retrieval methods are **asynchronous**. The result is returned in a <Tooltip>
Completion handler
</Tooltip>, which provides either the requested content or an error.

### Check the processing status

Use the `status(for:)` method to get the current content generation status of a session.

<CodeGroup>
  ```swift Swift theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
  SukiAmbientCore.shared.status(for: recordingId) { result in
      // The completion handler returns a result type.
      switch result {
      case .success(let status):
          // On success, the status object contains the current state.
          print("Session status: \(status)")
      case .failure(let error):
          // On failure, an error object is returned.
          print("Error fetching status: \(error)")
      }
  }
  ```
</CodeGroup>

### Get generated suggestions

To retrieve the main clinical note content, call the `content(for:)` method.

<CodeGroup>
  ```swift Swift theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
  SukiAmbientCore.shared.content(for: recordingId) { result in
      switch result {
      case .success(let suggestions):
          // The suggestions object contains the generated note content.
          print("Generated Suggestions: \(suggestions)")
      case .failure(let error):
          print("Error fetching content: \(error)")
      }
  }
  ```
</CodeGroup>

### Get the audio transcript

Retrieve the full transcript of the conversation using the `transcript(for:)` method.

<CodeGroup>
  ```swift Swift theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
  SukiAmbientCoreManager.shared.transcript(for: recordingId) { result in
      switch result {
      case .success(let response):
          // The response object contains transcript segments.
          // This example joins them into a single string.
          let transcriptText = (response.finalTranscript ?? []).compactMap { $0.transcript }.joined(separator: " ")
          print(transcriptText)
      case .failure(let error):
          print("Error fetching transcript: \(error)")
      }
  }
  ```
</CodeGroup>

### Get structured data

Use the `getStructuredData(for:)` method to retrieve structured output, such as diagnoses and other entities generated from the session.

<CodeGroup>
  ```swift Swift theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
  SukiAmbientCoreManager.shared.getStructuredData(for: recordingId) { result in // [!code ++:19]
      switch result {
      case .success(let response):
          let data = response.structuredData
          // Diagnoses
          for d in data.diagnoses.diagnoses {
              print(d.note)
          }
          // Medication orders (optional) [!code ++:6] if Medication orders are enabled
          if let orders = data.orders?.medicationOrders {
              let all = orders.values + orders.partialValues
              for order in all {
                  print(order.drugName, order.instructions)
              }
          }
      case .failure(let error):
          print(error)
      }
  }
  ```
</CodeGroup>

### Submit user feedback

<Note>
  `New` Submit user feedback for the AI-generated content.
</Note>

Use the `submitFeedback(_:for:onCompletion:)` to collect and submit user feedback on AI-generated content by using the `QuantitativeFeedback` and `QualitativeFeedback` structs.

This allows you to capture both quantitative (ratings) and qualitative (comments) feedback. Your feedback helps Suki **improve** the quality of its AI-generated content.

#### Function signature

<CodeGroup>
  ```swift Swift theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
  public func submitFeedback(
      _ submission: FeedbackSubmission,
      for recordingId: RecordingId,
      onCompletion completionHandler: @escaping ((Result<String, Error>) -> Void)
  )
  public typealias RecordingId = String
  ```
</CodeGroup>

#### Required data structures

Submitting feedback requires you to construct a `FeedbackSubmission` object. This object uses the `FeedbackEntity` and `QuantitativeFeedback` data structures.

<CodeGroup>
  ```swift Swift theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
  public struct FeedbackSubmission {
      public let entity: FeedbackEntity
      public let quantitative: QuantitativeFeedback
      public let comments: String?
      
      public init(entity: FeedbackEntity,
                  quantitative: QuantitativeFeedback,
                  comments: String? = nil)
  }

public enum FeedbackEntity: String {
      case content = "content"
  }

public struct QuantitativeFeedback {
      public let minRating: Int
      public let maxRating: Int
      public let rating: Int
      
      public init(minRating: Int, maxRating: Int, rating: Int)
  }
  ```
</CodeGroup>

#### Implementation example

To submit feedback, you first create the `FeedbackSubmission` object and then pass it to the `submitFeedback` method along with the `recordingId`.

The method is **asynchronous**. The completion handler returns a `Result` containing either a success message with the unique feedbackId or an error if the submission failed.

<CodeGroup>
  ```swift Swift theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
  // 1. Create the quantitative feedback object.
  let quantitativeFeedback = QuantitativeFeedback(minRating: 1, maxRating: 5, rating: 4)

// 2. Create the full feedback submission object.
  let submission = FeedbackSubmission(
      entity: .content,
      quantitative: quantitativeFeedback,
      comments: "The patient's history was captured accurately."
  )

// 3. Call the submit method with the submission object and recording ID.
  SukiAmbientCoreManager.shared.submitFeedback(submission, for: recordingId) { result in
      switch result {
      case .success(let feedbackId):
          print("Feedback submitted successfully with ID: \(feedbackId)")
      case .failure(let error):
          print("Error submitting feedback: \(error)")
      }
  }
  ```
</CodeGroup>

<Warning>
  * Provide feedback for each entity type **once per session** only.

* At present feedback submissions are only supported for the `.content` entity. This may be expanded in the future.

* Submitting feedback for the same entity type a second time in the same session will be considered invalid.
</Warning>

#### Rating system

* The `maxRating` must be greater than the `minRating`.

* The rating must be within the inclusive range of `minRating` and `maxRating`.

* The `comments` string is optional and has a maximum length of **2000** characters.

<Note>
  - Configure any integer rating scale. For example, create a 1 to 5 scale by setting `minRating` to 1 and `maxRating` to 5, or a binary scale by setting the values to 0 and 1.

- Suki recommends using a scale of 1 to 5 for ratings.
</Note>

## FAQs

<AccordionGroup>
  <Accordion title="Why is the content not being generated?">
    The content is not being generated because the session is not in a completed state or the session was too short. We require a **minimum of 1 minute of audio** to generate content. You must ensure that the session is in a completed state before retrieving the content.
  </Accordion>

<Accordion title="Why is the content not being retrieved?">
    The content is not being retrieved because the `recordingId` is not valid. You must ensure that you are using a valid `recordingId` from an active or completed session.
  </Accordion>

<Accordion title="How do I know if the content has been generated?">
    Check the status of the session to determine if the content has been generated.
  </Accordion>

<Accordion title="How do I know if the content has been retrieved?">
    Check the status of the session to determine if the content has been retrieved.
  </Accordion>

<Accordion title="What happens if the internet connection is lost?">
    If the internet connection is lost, the content will be retrieved when the connection is restored. Please refer to the [Offline mode](/mobile-sdk/ambient-guides/offline-mode) guide for more information.
  </Accordion>

<Accordion title="What happens if the session is not completed?">
    The content will not be retrieved if the session is not completed. You must ensure that the session is in a completed state before retrieving the content.
  </Accordion>
</AccordionGroup>

## Next steps

<Icon icon="file-lines" /> After you have retrieved the content, you can proceed to the [Clear session](/mobile-sdk/ambient-guides/clearing-sessions) guide to create a new session.

# Mobile SDK Configuration
Source: https://developer.suki.ai/mobile-sdk/configuration

How to configure the Suki Mobile SDK

To use the Suki **mobile SDK**, you must configure it when your application starts. Follow these steps to **initialize** the SDK.

## Configure the SDK

Follow these steps to configure the Suki Mobile SDK:

<Steps>
  <Step title="Import the framework">
    In the Swift file where you will manage the SDK, **import** the framework:

<CodeGroup>
      ```swift Import Framework theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
      import SukiAmbientCore
      ```
    </CodeGroup>
  </Step>

<Step title="Set the SDK environment">
    Set the SDK environment by assigning a value to the `SukiAmbientCoreManager.shared.environment` property. The recommended environments are `.stage` and `.prod`.

<CodeGroup>
      ```swift Set Environment theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
      // Set the SDK environment (recommended: .stage or .prod)
      SukiAmbientCoreManager.shared.environment = .stage
      ```
    </CodeGroup>
  </Step>

<Step title="Initialize the SDK">
    Call the `initialize` method to configure the SDK. Call this method after a user signs in. If sign-in sessions persist, call it in your application delegate's `didFinishLaunchingWithOptions` method.

<CodeGroup>
      ```swift Initialize SDK theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
      func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
          do {
              let partnerInfo: [String: AnyHashable] = [
                  SukiAmbientConstant.kPartnerId: "123",
                  SukiAmbientConstant.kProviderInfo: [
                      SukiAmbientConstant.kOrgId: "provider_org_id",
                      SukiAmbientConstant.kName: "Patrick Smith", // replace this with the provider's name
                      SukiAmbientConstant.kId: "providerId",
                      SukiAmbientConstant.kSpeciality: "FAMILY_MEDICINE"
                  ]
              ]
              try SukiAmbientCore.shared.initialize(
                  withPartnerInfo: partnerInfo,
                  with: true, // Set to true if your app supports background recording
                  onCompletion: { result in
                      // Handle initialization result
                  },
                  withSessionDelegate: self,
                  withTokenProvider: self
              )
          } catch {
              print(error)
          }
      }
      ```
    </CodeGroup>
  </Step>
</Steps>

### Initialization parameters

The `initialize` method takes the following parameters:

<ResponseField name="partnerInfo" type="dictionary">
  A dictionary containing partner and provider details.

<Tip>
    These parameters are not actively used in the current version, as the SDK is designed for a single user with one specialty. The method signature may change in a future release.
  </Tip>
</ResponseField>

<ResponseField name="backgroundRecording" type="boolean">
  Set this to `true` if your app supports background recording. If `true`, recording continues when the app is in the background. Otherwise, recording pauses and you must resume it when the app returns to the foreground.
</ResponseField>

<ResponseField name="onCompletion" type="completionHandler">
  A completion handler that is called with the result of the initialization, indicating success or failure.
</ResponseField>

<ResponseField name="sessionDelegate" type="delegateObject">
  An optional delegate object to receive callbacks for recording-level events.
</ResponseField>

<ResponseField name="tokenProvider" type="TokenProvider">
  An object that conforms to the `tokenProvider` protocol. Your application (client application) is responsible for providing a valid token when the SDK requests one through this protocol.

<Note>
    The `tokenProvider` is used for authenticating the mobile SDK. You must implement this `tokenProvider` protocol to get authentication tokens when needed.
  </Note>
</ResponseField>

## Error handling

The `initialize` method can throw a `SukiAmbientCoreError`. You should use a **do-catch** block, as shown in the example above, to handle any potential errors during initialization.

## Next steps

<Icon icon="file-lines" /> After you configure the SDK, proceed to our [Ambient guides](/mobile-sdk/ambient-guides/create-session) to start using the mobile SDK features.

# Content Retrieval
Source: https://developer.suki.ai/mobile-sdk/faqs/content-retrieval

Retrieving generated clinical content, transcripts, and structured data from sessions

<Accordion title="How do I retrieve generated clinical content?">
  After ending a session, retrieve content using the session's recording ID:

After ending a session, wait for the suggestionsGenerated event through the session delegate, then use the SDK's content retrieval methods with the session's recording ID.
</Accordion>

<Accordion title="What does the retrieved content contain?">
  The retrieved content includes:

* **Clinical sections**: Structured documentation organized by medical sections (e.g., History of Present Illness, Review of Systems)
  * **Timestamps**: When the content was generated
  * **Session metadata**: Information about the session, patient, and provider
  * **Confidence scores**: AI confidence levels for different content sections
  * **Structured data**: Formatted clinical information ready for EHR integration
</Accordion>

<Accordion title="How long does content generation take?">
  Content generation time varies based on:

* **Session length**: Longer sessions take more time to process
  * **Audio quality**: Clear audio processes faster
  * **Network conditions**: Affect upload and processing speed
  * **Server load**: Peak times may have longer processing

Typical generation times range from 30 seconds to a few minutes. Use session delegates to get real-time updates.
</Accordion>

<Accordion title="Can I retrieve content multiple times for the same session?">
  Yes, you can retrieve content multiple times using the same recording ID. The content remains available on the server for a specified retention period. Each retrieval call returns the same generated content.

Retrieve content multiple times using the same recording ID. Each retrieval call returns the same generated content during the retention period.
</Accordion>

<Accordion title="What happens if content generation fails?">
  If content generation fails, you'll receive a `contentGenerationFailed` event through the session delegate:

If content generation fails, you'll receive a generation failed event through the session delegate. Handle this by showing appropriate error messages and potentially creating a new session.

Common causes include poor audio quality, network issues during processing, or server errors.
</Accordion>

<Accordion title="How do I check if content is ready without retrieving it?">
  Use session status methods to check processing status:

Use session status methods to check processing status before attempting content retrieval. This helps determine if content generation is complete.
</Accordion>

<Accordion title="Can I retrieve partial content during generation?">
  No, content retrieval returns the complete generated clinical documentation once processing is finished. Partial content isn't available during the generation process. Use session delegates to monitor progress and retrieve content only after receiving the `suggestionsGenerated` event.
</Accordion>

<Accordion title="What should I do if content retrieval fails?">
  Handle content retrieval failures gracefully:

Handle content retrieval failures gracefully by implementing proper error handling for various failure scenarios like network issues or content not being ready.

Implement retry logic with exponential backoff for transient errors.
</Accordion>

<Accordion title="How long is generated content stored on the server?">
  Generated content is typically stored for a defined retention period (usually 30-90 days, depending on your agreement with Suki). After this period, content may be automatically deleted. Check with your Suki partnership team for specific retention policies.
</Accordion>

<Accordion title="Can I retrieve content for offline sessions?">
  Yes, once offline sessions are uploaded and processed, you can retrieve their content using the same methods. The SDK automatically handles the upload process when connectivity is restored, and content generation begins once the upload completes.

Monitor the upload and generation progress through session delegate events.
</Accordion>

# General
Source: https://developer.suki.ai/mobile-sdk/faqs/general

General questions about Mobile SDK features, compatibility, and implementation

<Accordion title="What is the Suki Mobile SDK?">
  The Suki Mobile SDK is a native iOS framework that enables healthcare applications to integrate AI-powered clinical documentation capabilities. It lets you embed ambient intelligence features directly into your mobile application, including conversation capture, AI-generated clinical notes, and session management.
</Accordion>

<Accordion title="What platforms does the Mobile SDK support?">
  Currently, the Suki Mobile SDK supports iOS applications. Android support may be available in future releases. The SDK is distributed as a `.framework` file that can be integrated into Xcode projects.
</Accordion>

<Accordion title="What are the main capabilities of the Mobile SDK?">
  The Mobile SDK provides several key capabilities:

* **Session management**: Create, start, pause, resume, end, and cancel clinical documentation sessions
  * **Offline mode**: Continue recording during network interruptions with automatic sync when connection is restored
  * **AI-generated content**: Transform conversations into structured clinical notes using Suki's AI
  * **Real-time events**: Receive session updates through delegate callbacks
  * **Security**: HIPAA-compliant with end-to-end encryption for all data
</Accordion>

<Accordion title="Do I need special permissions or access to use the Mobile SDK?">
  Yes, you need to contact Suki's partnership team to get access to the Mobile SDK. Additionally, your iOS app must request microphone permissions since the SDK needs to record audio for clinical documentation.
</Accordion>

<Accordion title="What iOS versions are supported?">
  The Mobile SDK requires iOS 13.0 or later. Make sure your app's deployment target is set to iOS 13.0 or higher to use the SDK features.
</Accordion>

<Accordion title="Can I use the Mobile SDK in multiple apps?">
  Yes, you can integrate the Mobile SDK into multiple iOS applications. Each app will need to be configured with the appropriate partner information and authentication tokens.
</Accordion>

<Accordion title="Is the Mobile SDK HIPAA compliant?">
  Yes, the Mobile SDK is designed with healthcare-grade security features and HIPAA compliance in mind. All audio data and clinical content is encrypted both in transit and when stored locally on the device.
</Accordion>

<Accordion title="How does the Mobile SDK handle different medical specialties?">
  The SDK supports various medical specialties through the provider configuration. Specify the specialty during initialization, and the AI will generate content appropriate for that specialty.
</Accordion>

# Installation & Setup
Source: https://developer.suki.ai/mobile-sdk/faqs/installation-setup

Mobile SDK installation requirements, setup process, and configuration questions

<Accordion title="How do I install the Mobile SDK in my iOS project?">
  Follow these steps to install the SDK:

1. Download the `SukiAmbientCore.framework` file from Suki
  2. Drag the framework into your Xcode project navigator
  3. Select "Copy items if needed" when prompted
  4. In your target settings, set the framework to "Embed & Sign"
  5. Add `NSMicrophoneUsageDescription` to your Info.plist

You must add the NSMicrophoneUsageDescription key to your Info.plist file with a user-friendly explanation.
</Accordion>

<Accordion title="What should I put in the NSMicrophoneUsageDescription?">
  You must provide a clear explanation of why your app needs microphone access. Here's a recommended description:

Provide a clear, user-friendly explanation that describes why your app needs microphone access for clinical documentation purposes.

Apple requires this description to be user-friendly and explain the specific use case for microphone access.
</Accordion>

<Accordion title="How do I configure the SDK after installation?">
  Configuration involves three main steps:

Configuration involves three main steps: importing the SukiAmbientCore framework, setting the environment (stage or prod), and initializing the SDK with partner information, session delegate, and token provider.
</Accordion>

<Accordion title="What environments are available for testing?">
  The Mobile SDK supports multiple environments:

* **`.stage`**: For development and testing purposes
  * **`.prod`**: For production use

Always start with the `.stage` environment during development and testing before moving to production.
</Accordion>

<Accordion title="Do I need to implement TokenProvider protocol?">
  Yes, you must implement the `TokenProvider` protocol to provide authentication tokens to the SDK. The SDK will request tokens through this protocol when needed.

You must implement the TokenProvider protocol to provide authentication tokens to the SDK. The SDK will request tokens through this protocol when needed for API authentication.
</Accordion>

<Accordion title="Can I test the SDK without a backend integration?">
  The Mobile SDK requires a valid authentication token and partner configuration to function. You'll need to work with Suki's partnership team to get the necessary credentials for testing, even in the staging environment.
</Accordion>

<Accordion title="What happens if initialization fails?">
  If initialization fails, the SDK will throw a `SukiAmbientCoreError`. Common causes include:

* Invalid partner information
  * Network connectivity issues
  * Authentication token problems
  * Missing required permissions

Always wrap initialization in a do-catch block to handle these errors gracefully.
</Accordion>

<Accordion title="Should I initialize the SDK on app launch or when needed?">
  It's recommended to initialize the SDK after user authentication is complete. Do this in your app delegate's `didFinishLaunchingWithOptions` if user sessions persist, or after successful login if they don't.
</Accordion>

# Offline & Networking
Source: https://developer.suki.ai/mobile-sdk/faqs/offline-networking

Offline mode, network handling, and connectivity features in the Mobile SDK

<Accordion title="How does offline mode work in the Mobile SDK?">
  The Mobile SDK automatically handles network interruptions with a smart offline mode:

1. **15-second buffer**: The SDK waits 15 seconds before entering offline mode, giving temporary connection issues time to resolve
  2. **Local storage**: Audio and session data are encrypted and stored securely on the device
  3. **Automatic sync**: When connection is restored, all offline data is automatically uploaded
  4. **Session continuity**: Recording continues uninterrupted during network outages

The SDK notifies your app about offline/online transitions through session delegate events.
</Accordion>

<Accordion title="What triggers offline mode?">
  Several scenarios can trigger offline mode:

* Poor or lost Wi-Fi connectivity
  * Cellular network issues
  * Network switching (Wi-Fi to cellular or vice versa)
  * Backend service temporary unavailability
  * Authentication token expiration
  * Dropped connections during audio streaming

The SDK automatically detects these conditions and handles the transition.
</Accordion>

<Accordion title="How do I handle the 15-second network buffer?">
  Use the network buffer period to show user-friendly notifications:

Use the network buffer period to show user-friendly notifications about connection status. The SDK provides session events to notify when sessions convert to offline mode.
</Accordion>

<Accordion title="Is data secure when stored offline?">
  Yes, all offline data is highly secure:

* **End-to-end encryption**: Audio and session data are encrypted before local storage
  * **Device-level protection**: Leverages iOS security features for data protection
  * **Automatic cleanup**: Data is removed from device after successful upload
  * **HIPAA compliance**: Meets healthcare data security requirements

No sensitive data is stored in plain text on the device.
</Accordion>

<Accordion title="Can I queue multiple offline sessions?">
  Yes, the SDK supports queuing multiple offline sessions:

* Sessions are stored locally with unique identifiers
  * Upload occurs in chronological order when connection returns
  * Each session maintains its own context and metadata
  * Progress tracking available through session delegates

The SDK supports queuing multiple offline sessions, with each session maintaining its own context and metadata for ordered processing when connection returns.
</Accordion>

<Accordion title="How do I know when offline data has been uploaded?">
  Monitor session events for upload completion:

Monitor session events for upload completion status. The SDK provides events for upload started, completed, and failed states to track offline data synchronization progress.
</Accordion>

<Accordion title="What happens if the device runs out of storage during offline mode?">
  The SDK monitors available storage and will:

1. Alert your app through delegate events if storage is low
  2. Prioritize the most recent session data
  3. Attempt to upload older sessions first when connection returns
  4. Provide error callbacks if storage becomes critically low

Implement storage monitoring in your app for the best user experience.
</Accordion>

<Accordion title="Can I manually trigger sync of offline data?">
  The SDK automatically handles offline data synchronization, but you can check sync status through session delegates. Manual triggering isn't available as the SDK optimizes upload timing based on network conditions and device resources.
</Accordion>

<Accordion title="How does offline mode affect battery life?">
  The SDK is optimized for battery efficiency during offline mode:

* **Reduced processing**: Minimal background processing during offline recording
  * **Efficient encoding**: Audio compression optimized for battery life
  * **Smart sync**: Upload scheduling considers device charging state
  * **Background limits**: Respects iOS background execution limits

Battery impact is minimized while maintaining recording quality.
</Accordion>

<Accordion title="What network conditions are considered 'stable' by the SDK?">
  The SDK considers network conditions stable when:

* Consistent connectivity for data transmission
  * Adequate bandwidth for real-time audio streaming
  * Low latency for API communications
  * Successful authentication token validation

The 15-second buffer accommodates temporary fluctuations in these conditions.
</Accordion>

# Session Management
Source: https://developer.suki.ai/mobile-sdk/faqs/session-management

Managing ambient sessions, lifecycle, and data handling in the Mobile SDK

<Accordion title="How do I create a new session?">
  Create a session by providing patient information and clinical sections:

Create a session by providing patient information (name, birthdate, gender), clinical sections for content generation, optional session ID, and multilingual settings through the createSession method.
</Accordion>

<Accordion title="What patient information is required for session creation?">
  The minimum required patient information includes:

* **Name**: Patient's full name
  * **Birthdate**: Date of birth in Date format
  * **Gender**: "MALE" or "FEMALE"

Additional optional information can be provided through the `setSessionContext` method.
</Accordion>

<Accordion title="Can I update session information after creation?">
  Yes, use the `setSessionContext` method to update patient information, provider details, or add diagnosis codes after session creation:

Use the setSessionContext method to update patient information, provider details, or add diagnosis codes after session creation.
</Accordion>

<Accordion title="Does the Mobile SDK support Problem-Based Charting (PBC)?">
  Yes. Pass existing patient diagnoses with `SukiAmbientConstant.kDiagnosisInfo` in `setSessionContext`, configure LOINC sections for the note, and retrieve structured diagnoses after the session with `getStructuredData(for:)`. Behavior matches the Ambient APIs for reconciliation and output. Refer to [Problem-Based Charting](../../api-reference/capabilities/problem-based-charting), [Create session](../ambient-guides/create-session), and [Session status and content retrieval](../ambient-guides/session-status-and-content-retrieval#get-structured-data).
</Accordion>

<Accordion title="What are the different session states?">
  Sessions can be in the following states:

* **NotCreated**: No session has been initialized
  * **Recording**: Session is actively recording audio
  * **Paused**: Recording is temporarily paused
  * **Ended**: Session completed, content generation in progress
  * **Canceled**: Session was canceled, no content will be generated

Check the current state using `SukiAmbientCore.shared.sessionState`.
</Accordion>

<Accordion title="Can I pause and resume a recording session?">
  Yes, you can pause and resume sessions:

The SDK provides pause and resume methods to temporarily stop and restart recording while keeping the session active.

Note that you can only pause an active recording and only resume a paused session.
</Accordion>

<Accordion title="What's the difference between ending and canceling a session?">
  * **End**: Stops recording and begins AI content generation. Use this for completed sessions.
  * **Cancel**: Stops recording and discards all data. No content will be generated. This action cannot be undone.

End stops recording and begins AI content generation for completed sessions, while Cancel stops recording and discards all data with no content generation.
</Accordion>

<Accordion title="Can I have multiple active sessions?">
  The current SDK version supports one active session at a time. You must end or cancel the current session before creating a new one.
</Accordion>

<Accordion title="How do I handle session errors?">
  All session methods can throw `SukiAmbientCoreError`. Always use do-catch blocks:

All session methods can throw SukiAmbientCoreError. Use do-catch blocks to handle errors like session not initialized or attempting to record in the background.
</Accordion>

<Accordion title="What happens if I try to start recording in the background?">
  iOS doesn't allow apps to start recording while in the background. The SDK will throw an `appIsNotActive` error. You should:

1. Handle this error gracefully
  2. Notify the user to bring the app to the foreground
  3. Retry the operation once the app is active
</Accordion>

<Accordion title="How do I know when content generation is complete?">
  Use the session delegate to receive real-time updates:

Use the session delegate to receive real-time updates about content generation completion and handle events like suggestions generated or generation failures.
</Accordion>

# Troubleshooting
Source: https://developer.suki.ai/mobile-sdk/faqs/troubleshooting

Common Mobile SDK issues, error codes, and troubleshooting solutions

<Accordion title="Why am I getting 'appIsNotActive' error when starting recording?">
  This error occurs when you try to start recording while your app is in the background. iOS doesn't allow apps to begin audio recording in the background.

**Solution:**
  Handle the appIsNotActive error by catching it specifically and showing an alert asking the user to bring the app to the foreground before attempting to start recording.

Ensure your app is in the foreground before attempting to start recording.
</Accordion>

<Accordion title="Why is my session initialization failing?">
  Session initialization can fail for several reasons:

**Common causes:**

* Invalid partner information
  * Network connectivity issues
  * Authentication token problems
  * Missing microphone permissions

**Debugging steps:**
  Debug initialization failures by checking the completion handler result and catching initialization errors. Verify partner information, network connectivity, and required permissions.
</Accordion>

<Accordion title="Why is content generation taking too long?">
  Content generation delays can be caused by:

**Common causes:**

* Long session duration (more audio to process)
  * Poor audio quality requiring additional processing
  * Network issues during upload
  * High server load during peak times
  * Large session context or metadata

**Solutions:**

1. Monitor session events for real-time updates
  2. Implement timeout handling
  3. Check network connectivity
  4. Ensure good audio recording conditions

Monitor content generation progress through session events. Show progress indicators during processing and handle both success and failure scenarios appropriately.
</Accordion>

<Accordion title="Why am I not receiving session delegate events?">
  If you're not receiving delegate events, check:

**Common issues:**

1. Delegate not properly set during initialization
  2. Delegate object deallocated
  3. Not implementing the protocol method correctly

**Solution:**
  Ensure your class conforms to SukiAmbientSessionDelegate protocol, pass the delegate during initialization, and implement the required delegate method to receive session events.
</Accordion>

<Accordion title="Why is audio quality poor in my recordings?">
  Poor audio quality can affect AI-generated content accuracy:

**Common causes:**

* Background noise interference
  * Device microphone obstruction
  * Poor recording environment
  * Low device volume settings
  * Hardware issues

**Solutions:**

1. Record in quiet environments
  2. Ensure microphone isn't blocked
  3. Test with different devices
  4. Check device audio settings
  5. Implement audio level monitoring

Improve audio quality by recording in quiet environments, ensuring the microphone isn't blocked, and monitoring for audio-related session events that may indicate quality issues.
</Accordion>

<Accordion title="How do I debug token provider issues?">
  Token provider problems can prevent SDK functionality:

**Common issues:**

* Token expiration
  * Invalid token format
  * Network issues during token fetch
  * Authentication service problems

**Debugging approach:**
  Debug token provider issues by adding logging to track when tokens are requested, validating token format before returning, and handling token fetch failures appropriately.
</Accordion>

<Accordion title="Why is offline mode not working correctly?">
  Offline mode issues can include:

**Common problems:**

* Data not syncing when back online
  * Sessions lost during offline mode
  * Storage space issues
  * Incorrect offline state detection

**Troubleshooting steps:**

1. Check available device storage
  2. Monitor offline/online events
  3. Verify network state detection
  4. Test offline functionality in controlled conditions

Debug offline mode issues by monitoring session events for offline transitions, upload progress, and sync completion. Check available device storage and verify network state detection.
</Accordion>

<Accordion title="How do I handle memory issues with the SDK?">
  Memory management best practices:

**Common causes:**

* Not properly ending sessions
  * Retaining large audio buffers
  * Memory leaks in delegate implementations
  * Multiple concurrent sessions

**Solutions:**

1. Always end or cancel sessions when done
  2. Implement proper delegate cleanup
  3. Monitor memory usage during development
  4. Use Instruments to profile memory usage

Manage memory properly by cleaning up active sessions in deinit, ending sessions when done, implementing proper delegate cleanup, and monitoring memory usage during development.
</Accordion>

# Mobile SDK Capabilities
Source: https://developer.suki.ai/mobile-sdk/features

Core features and capabilities of the Suki Mobile SDK for iOS healthcare applications

<span>Quick summary</span>
  </div>

<div>
    The Suki Mobile SDK lets you add AI-powered clinical documentation to your iOS healthcare app. It's a headless SDK, which means you build your own user interface
    while using Suki's backend features for recording conversations and generating clinical notes.
  </div>

<span>Last updated:</span>
    <span>June 2026</span>
  </div>
</div>

The Suki Mobile SDK lets you add AI-powered clinical documentation to your iOS healthcare app. It's a **headless SDK**, which means you build your own user interface while using Suki's backend features for recording conversations and generating clinical notes.

**What can you do with the Mobile SDK?**

* **Record conversations**: Capture patient-provider conversations using the device microphone
* **Generate clinical notes**: Automatically create structured clinical documentation from conversations
* **Work offline**: Continue recording even when the network is unstable or unavailable
* **Manage sessions**: Control when recording starts, stops, pauses, and resumes
* **Stay secure**: All data is encrypted and HIPAA-compliant

**How it works:**

The Mobile SDK handles the complex parts, audio recording, transcription, and note generation, while you focus on building your app's user interface. You call SDK methods to start and stop recording, and the SDK handles everything else in the background.

## Core capabilities

### Session management

You control the entire lifecycle of clinical documentation sessions:

**What you can do:**

<CardGroup>
  <Card title="Create sessions" icon="plus">
    Start a new session with patient information, clinical sections (LOINC codes), and provider details
  </Card>

<Card title="Control recording" icon="microphone">
    Start, pause, resume, end, or cancel recording at any time
  </Card>

<Card title="Update context" icon="user">
    Change patient information or session details during an active session
  </Card>

<Card title="Support multiple languages" icon="globe">
    Enable multilingual support so patients can speak in their preferred language
  </Card>
</CardGroup>

**Example 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':'#FFE148','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[Create Session<br/>Patient: John Doe<br/>Sections: History & Assessment] --> B[Start Recording<br/>Visit Begins]
    B --> C{Need to Pause?<br/>e.g., Private Conversation}
    C -->|Yes| D[Pause Recording]
    D --> E[Resume Recording]
    E --> C
    C -->|No| F[Continue Recording]
    F --> G[Visit Complete]
    G --> H[End Session]
    H --> I[Retrieve Generated<br/>Clinical Note]
    
    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
    style H fill:#FFF394,stroke:#FFE148,stroke-width:2px,color:#111827
    style I fill:#FFF394,stroke:#FFE148,stroke-width:2px,color:#111827
```

<Tip>
  Always provide **complete patient context** (demographics, visit type, etc.) when creating sessions. This helps Suki generate more accurate and relevant clinical notes.
</Tip>

### Offline mode

The Mobile SDK keeps working even when the network is unstable or unavailable.

**How offline mode works:**

```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':'#FFE148','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[Network Connection Active] --> B[Network Drops]
    B --> C[15-Second Buffer<br/>Wait for Reconnection]
    C --> D{Network<br/>Restored?}
    D -->|Yes| A
    D -->|No| E[Go Fully Offline]
    E --> F[Local Storage<br/>Encrypted Audio & Session Data<br/>Stored on Device]
    F --> G[Network Returns]
    G --> H[Automatic Sync<br/>Upload Stored Data]
    H --> I[Queue Management<br/>Process Multiple Sessions<br/>in Order]
    I --> A
    
    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
    style H fill:#FFF394,stroke:#FFE148,stroke-width:2px,color:#111827
    style I fill:#FFF394,stroke:#FFE148,stroke-width:2px,color:#111827
```

**Why this matters:**

Clinicians often work in areas with poor network coverage (hospitals, clinics, remote locations). Offline mode ensures they can continue documenting without interruption, and their data syncs automatically when connectivity returns.

<Note>
  The **15-second** buffer gives you time to show a "Connection unstable" message in your UI before the session enters full offline mode.
</Note>

### AI-powered note generation

Suki's AI automatically transforms conversations into structured clinical notes.

**What gets generated:**

<CardGroup>
  <Card title="Structured sections" icon="list">
    Notes organized by clinical sections you specify (using LOINC codes)
  </Card>

<Card title="Real-time updates" icon="clock">
    See content being generated as the conversation happens
  </Card>

<Card title="Medical accuracy" icon="heart">
    Uses healthcare-specific terminology and context
  </Card>

<Card title="Formatted output" icon="file-text">
    Clean, professional notes ready for EHR integration
  </Card>
</CardGroup>

**Example:**

<Callout>
  During a conversation, the AI might generate:

* **History of Present Illness**: "Patient presents with 3-day history of chest pain..."
  * **Assessment**: "Acute coronary syndrome, rule out myocardial infarction"
  * **Plan**: "Order EKG, cardiac enzymes, consider cardiac catheterization"
</Callout>

The SDK handles all the complex AI processing; you just retrieve the final note when the session ends.

### Problem-Based Charting (PBC)

When your integration uses **Problem-Based Charting**, pass the patient's existing diagnoses with `SukiAmbientConstant.kDiagnosisInfo` in `setSessionContext`, and retrieve suggested diagnoses after the session with `getStructuredData(for:)`.

### Configuration options

The SDK offers flexible configuration to match your app's needs:

**Environment settings:**

* Choose development, staging, or production environments
* Configure endpoints and API URLs

**Recording options:**

* Enable or disable background recording (when app is minimized)
* Control audio quality and encoding settings

**Authentication:**

* Secure token management with automatic refresh
* Partner ID and provider information setup

**Event handling:**

* Use delegate patterns to receive real-time session updates
* Subscribe to events like recording started, paused, or note generated

**Example:**

```swift Swift theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
// Set environment
SukiAmbientCoreManager.shared.environment = .production

// Configure background recording
let partnerInfo: [String: AnyHashable] = [
    SukiAmbientConstant.kPartnerId: "your-partner-id",
    // ... other config
]
```

This flexibility lets you adapt the SDK to your specific workflow and requirements.

### Security and HIPAA compliance

The Mobile SDK is built with healthcare-grade security to protect patient data.

**Security features:**

* **End-to-end encryption**: All audio and clinical data is encrypted during transmission and when stored
* **HIPAA compliant**: Designed to meet healthcare privacy and security requirements
* **Secure authentication**: Tokens are handled securely with automatic refresh
* **Device protection**: Offline data stored on the device is also encrypted

<Check>
  All audio data and clinical content is encrypted both in transit and when stored locally on the device.
</Check>

### Real-time monitoring

Track session status and respond to events as they happen.

**What you can monitor:**

```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':'#FFE148','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'}}}%%
graph LR
    SDK[Mobile SDK] -->|Session State| A[Recording Starts<br/>Pauses<br/>Resumes<br/>Ends]
    SDK -->|Content Updates| B[Note Content<br/>Generated]
    SDK -->|Network Status| C[Goes Offline<br/>Comes Back Online]
    SDK -->|Errors| D[Error Information<br/>Detailed Messages]
    
    style SDK fill:#FFF394,stroke:#FFE148,stroke-width:3px,color:#111827
    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
```

**How it works:**

The SDK uses a delegate pattern to broadcast events during a session's lifecycle. You conform to the `SukiAmbientSessionDelegate` protocol and implement the `sukiAmbient(sessionEvent:for:)` method to receive real-time updates.

**Example events:**

* `.started` - Recording starts
* `.paused` - Recording is paused
* `.resumed` - Recording resumes
* `.ended` - Recording ends
* `.suggestionsGenerated` - Note content is ready
* `.convertedToOfflineSession` - Session goes offline
* `.suggestionsGenerationFailed` - Note generation fails

### Easy integration

The Mobile SDK is designed to be simple to integrate and use.

**Developer-friendly features:**

* **Swift APIs**: Native Swift interfaces that feel natural to iOS developers
* **Clear documentation**: Comprehensive guides and code examples
* **Sensible defaults**: Works out of the box with minimal configuration
* **Production ready**: Battle-tested SDK used in real healthcare applications
* **Scalable**: Works for small clinics or large hospital systems

## Next steps

<Icon icon="file-lines" /> Learn how to [Install the Mobile SDK](/mobile-sdk/installation) and [Create your first session](/mobile-sdk/ambient-guides/create-session).

# Mobile SDK Installation
Source: https://developer.suki.ai/mobile-sdk/installation

Learn how to install and set up the Suki Mobile SDK

To use the Suki Mobile SDK, you need to download the `SukiAmbientCore.framework` file and add it to your Xcode project. Learn how to install and set up the Suki Mobile SDK in this guide.

## Set up your environment

Follow the steps below to install the **Suki Mobile SDK** and set up your development environment.

<Steps>
  <Step title="Download the framework">
    Download the `SukiAmbientCore.framework` file.
  </Step>

<Step title="Add the framework to your project">
    Drag the `SukiAmbientCore.framework` file into your **Xcode project navigator**. In the dialog box that appears, select the **Copy items if needed** checkbox and click **Finish**.

<Step title="Embed the framework">
    In your app's target settings, navigate to the **General** tab and find the **Frameworks, Libraries, and Embedded Content** section. Change the setting for `SukiAmbientCore.framework` to **Embed & Sign**.

<Step title="Add the NSMicrophoneUsageDescription key">
    Add the `NSMicrophoneUsageDescription` key to your `Info.plist` file. You **must provide** a value for this key that explains to the user why your app needs microphone access.

<Note>
      Apple requires this key and a descriptive string to access the device's microphone for recording conversations.
    </Note>
  </Step>
</Steps>

## Next steps

<Icon icon="file-lines" /> After you install the SDK, proceed to our [Configuration guide](/mobile-sdk/configuration) to start using the mobile SDK features.

# Mobile SDK Overview
Source: https://developer.suki.ai/mobile-sdk/overview

A collection of iOS libraries to build native iOS applications on top of Suki ambient intelligence capabilities

Suki Mobile SDK is a headless SDK for iOS applications. It provides <Tooltip href="/Glossary/a">ambient</Tooltip> intelligence capabilities that you can integrate directly into your native iOS app.

Use the mobile SDK to capture clinical conversations, generate notes automatically, and streamline documentation workflows.

## Mobile SDK capabilities

With just a few lines of code, you can use the SDK to:

* **Capture Conversations**: Enable hands-free, real-time ambient transcription of clinical conversations.

* **Generate Notes**: Automatically transform conversations into structured clinical documentation using Suki's AI.

* **Problem-Based Charting (PBC)**: Support problem-oriented notes and structured diagnoses by passing diagnosis context in `setSessionContext` and reading structured output when the session completes.

* **Manage Sessions**: Handle the entire session lifecycle seamlessly within your application.

* **Ensure Security**: All data processing is handled with HIPAA-grade privacy and security.

Refer to the [Mobile SDK capabilities](/mobile-sdk/features) page for more details on the capabilities of the Mobile SDK.

## Guide navigation

To get started with the Mobile SDK, you can follow the guides in the following order:

| Guide                                                                                                     | Purpose                                     | Key capabilities                                                             |
| --------------------------------------------------------------------------------------------------------- | ------------------------------------------- | ---------------------------------------------------------------------------- |
| **[Create session](/mobile-sdk/ambient-guides/create-session)**                                           | Session initialization and context setup    | Patient info, clinical sections, multilingual support, PBC diagnosis context |
| **[Recording controls](/mobile-sdk/ambient-guides/recording)**                                            | Recording lifecycle management              | Start, pause, resume, end, cancel operations                                 |
| **[Session status & content retrieval](/mobile-sdk/ambient-guides/session-status-and-content-retrieval)** | Content generation monitoring and retrieval | Status checking, content fetching, error handling                            |
| **[Offline mode](/mobile-sdk/ambient-guides/offline-mode)**                                               | Network resilience and offline capabilities | 15-second buffer, local storage, auto-sync                                   |
| **[Session events & delegates](/mobile-sdk/ambient-guides/events-and-delegates)**                         | Real-time event handling                    | Delegate pattern, event types, UI integration                                |
| **[Clearing sessions](/mobile-sdk/ambient-guides/clearing-sessions)**                                     | Session cleanup and data privacy            | User logout, data clearing, memory management                                |

## Mobile SDK workflow

The diagram below shows the complete ambient session workflow and how you can use the Mobile SDK to manage the session lifecycle.

```mermaid theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
sequenceDiagram
    actor User
    participant SDK as Mobile SDK
    participant Backend as Suki Backend

Note over User,Backend: 1. Initialize & create session
    User->>SDK: Initialize SDK
    SDK->>Backend: Create new session
    Backend-->>SDK: Session created

Note over User,Backend: 2. Start recording
    User->>SDK: Start recording
    SDK->>Backend: Begin audio capture

Note over User,Backend: 3. Recording controls
    User->>SDK: Pause/Resume/Stop
    SDK->>Backend: Update recording state

Note over User,Backend: 4. Offline mode
    SDK->>SDK: Network Lost - Buffer locally
    SDK->>Backend: Network Restored - Auto-Sync

Note over User,Backend: 5. Complete session
    User->>SDK: End session
    SDK->>Backend: Finalize recording
    Backend-->>SDK: Generate Clinical notes
    SDK-->>User: Return notes

Note over User,Backend: 6. Cleanup
    User->>SDK: Cancel/Clear session
    SDK->>Backend: Delete session data
```

## Next steps

<Icon icon="file-lines" /> To begin the integration, follow our [Installation guide](/mobile-sdk/installation).

<Icon icon="file-lines" /> If you need access to the SDK, please contact our [Partnership team](https://www.suki.ai/suki-partners/).

<Icon icon="file-lines" /> Once you have installed the SDK, start with [Create session](/mobile-sdk/ambient-guides/create-session) to begin implementing the ambient session workflow, then follow the guides in sequence to build a complete integration.

# Mobile SDK Changelog
Source: https://developer.suki.ai/mobile-sdk/product-updates/changelog

Mobile SDK product updates and announcements

Suki's Mobile SDK versioning policy is based on the semantic versioning standard. For example, in version 1.2.3, 1 is the major version, 2 is the minor version, and 3 is the patch version.

When we release a new Mobile SDK version for new features or bug fixes, we increment one of these three version components depending on the type of change introduced.

<Update label="v2.6.0" description="April 2026">
  ### Enhancements

<Warning>
    **Configuration required**

You can provide Medication orders context through **Orders info** only after Suki enables the **`enable_generated_orders`** feature flag for your organization.

To participate in the alpha rollout, contact Suki to request access.
  </Warning>

* **Orders info**: Added support to provide **optional** orders info context parameter while creating an ambient session using the `SukiAmbientConstant.kOrdersInfo` key in the iOS SDK.

**Required:** If you provide `SukiAmbientConstant.kOrdersInfo`, each medication order must include the following payload keys:

* `drug_name`: The medication name
    * `medication_code`: The medication code
    * `strength`: The medication strength
    * `format`: The medication format
    * `route`: The medication route
    * `linked_diagnosis_codes`: The medication diagnosis codes
    * `metadata`: The medication metadata

**Optional:** Everything else in the medical order object (for example dosage, how often to take it, timing, status, dates, instructions, how much was dispensed, refills).

* **EMR info**: Added support to provide **optional** EMR info context parameter while creating an ambient session using the `SukiAmbientConstant.kEmrInfo` key in the iOS SDK.
    <Note>
      If you provide `SukiAmbientConstant.kEmrInfo`, you must provide the `SukiAmbientConstant.kTargetEmr` key with a string identifier for the target EMR.
    </Note>
</Update>

<Update label="v2.5.0" description="Dec 2025">
  ### Enhancements

* **Enhanced visit context**: Added support for visit-related metadata parameters in the `setSessionContext` method, including visit type, encounter type, provider role, reason for visit, and chief complaint. These parameters provide additional context to improve note generation accuracy and clinical relevance.

### API changes

* Extended `setSessionContext` method to accept new optional visit context parameters:
    * `visitType`: Enum values include "New Patient / Intake", "Established patient", "Wellness", "ED"
    * `encounterType`: Enum values include "ambulatory", "inpatient", "ED"
    * `providerRole`: Enum values include "Primary/Attending", "Consulting"
    * `reasonForVisit`: String parameter with a maximum of 255 characters
    * `chiefComplaint`: String parameter with a maximum of 255 characters
  * All new parameters are **optional**; existing flows continue to work without these parameters
  * Free text fields (`reasonForVisit` and `chiefComplaint`) enforce a 255-character limit
</Update>

<Update label="v2.4.0" description="Oct 2025">
  ### New features

* **User feedback collection**: Added `submitFeedback(_:for:onCompletion:)` method to collect user feedback on AI-generated content, helping you gather insights on note quality and user satisfaction.

* **Audio buffer monitoring**: Added `audioBufferFilled(withPercentage: Double)` case to the session delegate to notify you when the audio buffer reaches a certain fill percentage. This helps you display connection status indicators in your UI.

### Enhancements

* **Improved offline handling**: Offline mode now includes a 15-second buffer to handle temporary connection problems. This gives you more time to show connection status notifications in your UI before the session fully transitions to offline mode.

* **Enhanced getting started guide**: Improved the getting started guide with a workflow diagram to help you understand the process of using the Suki Mobile SDK.
</Update>

<Update label="v2.3.0" description="Jul 2025">
  ### New features

* **Personalization preferences**: Added `setPersonalizationPreferences(_:completionHandler:)` method to configure clinical note generation preferences. Customize verbosity levels and note section styles to match your clinical documentation needs.

### Enhancements

* **Note customization options**: Configure verbosity levels (concise, balanced, detailed) and note section styles (narrative or bulleted) for supported LOINC sections including History of Present Illness, Assessment, Plan, and Assessment & Plan.

### API changes

* New `setPersonalizationPreferences(_:completionHandler:)` method for configuring note generation preferences
  * Preferences are persisted and automatically applied to all future note generations
</Update>

<Update label="v2.2.1" description="Jul 2025">
  ### New features

* **Diagnosis context support**: Added `SukiAmbientConstant.kDiagnosisInfo` parameter to `setSessionContext` for structured diagnosis context, improving note accuracy by providing relevant diagnosis information.

* **Structured data retrieval**: Introduced `getStructuredData(for:onCompletion:)` method to retrieve structured output data and diagnoses from completed sessions, enabling better integration with EHR systems.

### API changes

* Extended `setSessionContext` with diagnosis information support
  * New `getStructuredData` method for accessing structured session output
  * Supports ICD-10, IMO, and SNOMED code types
</Update>

<Update label="v2.2.0" description="June 2025">
  ### New features

* **Session context method**: Introduced `setSessionContext(with:onCompletion:)` method for setting patient, provider context, and LOINC codes after session creation, providing more flexibility in when you provide context information.

### Enhancements

* **Improved session workflow**: Separated patient, provider, and section context from `createSession` to a dedicated `setSessionContext` method, making the session creation process more streamlined.

* **Enhanced LOINC integration**: Enhanced section generation using LOINC codes with automatic clinical section creation. LOINC codes alone are sufficient: the SDK automatically generates appropriate clinical sections.

### API changes

* `createSession` method now focuses solely on session initialization
  * Patient, provider, and section context should be set using `setSessionContext`
  * LOINC codes alone are sufficient: SDK automatically generates appropriate clinical sections
</Update>

<Update label="v2.1.0" description="May 2025">
  ### New features

* **Audio buffering**: Implemented audio buffering to reduce the number of offline sessions caused by brief internet interruptions, improving session continuity during temporary network issues.

* **Multilingual support**: Added `SukiAmbientConstant.kMultilingual` parameter to session creation for multilingual processing support, enabling accurate note generation for conversations in multiple languages.

### Enhancements

* **Background recording handling**: Added proper error handling when attempting to start recording while the app is backgrounded, providing clearer error messages and preventing unexpected behavior.

### Bug fixes

* Fixed "No record exists for offline upload" failure category identified through note failure tracing dashboard
  * Improved session recovery reliability during network transitions
</Update>

# Release notes rss
Source: https://developer.suki.ai/scripts/release-notes-rss

# Release notes hub RSS (Mintlify)

## Root cause (why the hub had no `<item>` elements)

The visual hub (`updates/release-notes.mdx`) uses **`mode: frame`**. On staging we verified:

* `…/updates/release-notes/rss.xml` had a `<channel>` but **no `<item>`** elements.
* `…/web-sdk/product-updates/changelog/rss.xml` and `…/updates/mar2026-release-notes/rss.xml` **did** include items.

So Mintlify’s RSS builder **does not pull `<Update>` entries from frame-mode pages**, even if those components appear in the MDX source. It is **not** caused by CSS hiding; moving `<Update>` blocks outside the layout did not fix it while `mode: frame` stayed on that file.

## Fix: separate RSS source page (no frame)

1. **`updates/release-notes-rss-feed.mdx`**
   * **`rss: true`**, **`hidden: true`** (sidebar), **no** `mode: frame`.
   * Holds the combined monthly **`<Update>`** list (newest first).
   * Feed URL: **`/updates/release-notes-rss-feed/rss.xml`**

2. **`updates/release-notes.mdx`**
   * Keeps **`mode: frame`** and the custom timeline UI.
   * **No** `rss: true` on this file (so we do not publish an empty feed at `…/release-notes/rss.xml`).
   * The **RSS** control links to **`/updates/release-notes-rss-feed/rss.xml`** (the combined XML feed). The human-readable source page is **`/updates/release-notes-rss-feed`** (hidden from the nav).

## When you add a new month

1. Update the timeline on **`release-notes.mdx`** as usual (newest month first under the year heading).
2. Add a matching **`<Update>`** at the top of the list in **`release-notes-rss-feed.mdx`** (same pattern as existing entries; see **April 2026** / **`updates/apr2026-release-notes`**).
3. Add the page path to **`docs.json`** under Release Notes (e.g. **`updates/apr2026-release-notes`** before older months).
4. For the monthly MDX page, include **`rss: true`** in frontmatter when that month’s page should participate in per-page RSS (see **`updates/apr2026-release-notes.mdx`**).

## How to test

After deploy, open **`https://<host>/updates/release-notes-rss-feed/rss.xml`** and confirm `<item>` entries.

## RSS `<link>` and `<guid>` (Mintlify behavior)

For each `<Update>`, Mintlify sets **`<link>`** and **`<guid isPermaLink="true">`** to:

**`https://<your-domain>/updates/release-notes-rss-feed#<label-as-kebab-case>`**

For example, `label="April 2026"` becomes `#april-2026`. This matches how Mintlify documents changelog RSS (same page URL plus anchor), see [Changelogs](https://www.mintlify.com/docs/guides/changelogs) and the [Update](https://mintlify.com/docs/components/update) component docs.

The **`rss={{ title, description }}`** object only overrides the **item title** and **item description** in the feed. It does **not** change `<link>` or `<guid>`. The markdown link inside the `<Update>` body (for example `[View April 2026…](/updates/apr2026-release-notes)`) is what appears in **`<content:encoded>`**, not in `<link>` / `<guid>`.

So **`https://developer.suki.ai/updates/apr2026-release-notes`** as the permalink for a combined-feed item is **not something this repo can set** with current Mintlify MDX alone. Options:

1. **Ask Mintlify** for a supported field (for example `rss.url` or `rss.link`) on `<Update>` if you need canonical monthly URLs in `<item><link>`.
2. **Rely on `<content:encoded>`** for the real article URL (consider **absolute** `https://developer.suki.ai/updates/...` links so feed readers resolve them reliably).
3. **Per-month RSS** instead of (or in addition to) the combined feed: each page like **`/updates/apr2026-release-notes/rss.xml`** uses that page as the item base URL when `<Update>` blocks live on that page (still `page#anchor` per item, but the page is already the month URL). A single combined feed with canonical month URLs may require a **custom-built RSS** outside Mintlify unless the product adds the feature.

## Email subscribe (Option A, no custom backend)

The hub (**`updates/release-notes.mdx`**) includes a **Subscribe** button next to **RSS**. Clicking it opens a **modal** with an **iframe** whose `src` is set at build time from Mintlify **`docs.json` → `variables` → `releaseNotesSubscribeEmbedUrl`** on **`data-embed-src="https://docs.google.com/forms/d/e/1FAIpQLSe6JMb3k2z5Vrp_w8JMEGRzGXfto2EGo9eko-pHnVbgLDyw_w/viewform?embedded=true"`** (see [Mintlify variables](https://www.mintlify.com/docs/organize/settings-reference#variables)). Partners type their email in the embedded form (supplied by your email vendor). **Do not put API keys or list secrets in the repo;** only the **public HTTPS embed URL** for that form belongs in the variable.

**Mailchimp “Classic” embed code** (the big HTML + `<script>` block) is **not** what goes in **`releaseNotesSubscribeEmbedUrl`**. That variable must be a **single https URL** that loads in an iframe. Examples: **Google Forms**: in **Send → embed HTML**, copy the iframe **`src`** (`https://docs.google.com/forms/d/e/<id>/viewform?embedded=true`). Mailchimp **hosted signup page** `https://<subdomain>.us<number>.list-manage.com/subscribe?u=…&id=…` (use **`/subscribe?`**, not **`/subscribe/post`**; see [Host your own signup forms](https://mailchimp.com/help/host-your-own-signup-forms/)), or **Brevo** / Sendinblue: copy the **`src`** URL from the **Iframe** embed code (`https://….sibforms.com/serve/…`).

**`/scripts/release-notes-subscribe.js`** (loaded from **`docs.json` → `scripts`**) only assigns **`https:`** URLs to the iframe (no `javascript:`, `data:`, or `http:`). The iframe **`src`** is set when the user opens the modal so third-party scripts do not load until then. If the variable is empty or invalid, the modal shows a short **fallback** with an RSS link. The UI uses a **fixed overlay** (not `<dialog>`) because Mintlify MDX output may not expose a working **`HTMLDialogElement.showModal`**.

### What you configure in your email tool (not in this repo)

1. **Audience** and **embedded signup form** (Mailchimp, Brevo, Customer.io, and others all expose an embed or iframe URL). Turn on **double opt-in** so subscribers get a **confirmation email** after they submit the form.
2. Paste that form’s **HTTPS embed URL** into **`releaseNotesSubscribeEmbedUrl`** in **`docs.json`**, then rebuild or redeploy the docs site.
3. **RSS-to-email** (or equivalent) in the same tool: point the recurring campaign at **`https://developer.suki.ai/updates/release-notes-rss-feed/rss.xml`** so when you add a new top **`<Update>`** in **`release-notes-rss-feed.mdx`** and deploy, subscribers receive the **monthly update email**. Design the template there (**Suki for Partner Update**, logo, formatted summary, link to the latest monthly release notes page).
4. Tune **`rss.title`** and **`rss.description`** on each **`<Update>`** in **`release-notes-rss-feed.mdx`** so RSS-driven emails stay readable.

**Compliance:** enable **confirmed opt-in** where required, include **unsubscribe** in every send, and link your **privacy policy** from the signup flow and email footer.

# Suki SDKs Overview
Source: https://developer.suki.ai/sdk-overview/overview

Overview of the Web SDK, Headless Web SDK, Mobile SDK, and Dictation SDK on the Suki Developer Platform, with links to quickstarts, changelogs, and integration guidance.

<p>
          Suki provides npm packages and native SDKs to integrate Suki's ambient intelligence capabilities. Features and integrations vary by SDK, so review changelogs and migration notes before upgrading.
        </p>

<div>
          <div>
            <h2>Introduction</h2>

<p>
              Suki SDKs help you add ambient documentation, form filling, and dictation to web and mobile applications. Choose
              the Web SDK, Headless Web SDK, Mobile SDK, or Dictation SDK based on your platform, UI needs, and workflow.
            </p>

<br />

<p>
              Install the SDK package, follow the product guide, and review the changelog before you upgrade. Use Suki APIs
              with SDKs when your backend needs server-side workflows or webhook integrations.
            </p>
          </div>

<div>
            <h2>How it works</h2>

<p>
              Configure authentication, initialize the SDK, then create or resume a session. Depending on the SDK, you stream
              audio, capture dictation, or retrieve generated clinical output.
            </p>

<br />

<p>
              Each SDK has its own authentication flow, supported features, and integration pattern. Review the SDK-specific guide before you deploy to staging or production.
            </p>
          </div>

<div>
            <h2>Authentication</h2>

<p>
              SDK access is available only to approved partners. Complete

<a href="/documentation/partner-onboarding">
                Partner onboarding
              </a>
            </p>

<p>
              For credentials, staging access, or production rollout support, contact

<a href="/documentation/support">
                Support
              </a>

or your Suki partnership contact.
            </p>
          </div>
        </div>

<div>
          <a href="/sdk-overview/quickstart">
            Get Started
          </a>

<a href="/documentation/partner-authentication">
            Authentication
          </a>
        </div>
      </div>

<div aria-label="SDK installation commands, support contact, best practices, and initialize examples">
        <div>
          <div>
            <h3>Installation Commands</h3>

<ul>
              <li>
                <button type="button" aria-label="Copy Web npm install command">
                  <span>
                    <span>Web</span>
                    <code>npm install @suki-sdk/react @suki-sdk/core</code>
                  </span>

<li>
                <button type="button" aria-label="Copy Mobile Xcode setup reminder">
                  <span>
                    <span>Mobile</span>

<code>
                      # Xcode: SukiAmbientCore.framework (Embed & Sign). See Mobile SDK installation.
                    </code>
                  </span>

<li>
                <button type="button" aria-label="Copy Headless npm install command">
                  <span>
                    <span>Headless</span>
                    <code>npm install @suki-sdk/platform-react</code>
                  </span>

<li>
                <button type="button" aria-label="Copy Dictation npm install command">
                  <span>
                    <span>Dictation</span>

<code>
                      npm install @suki-sdk/core @suki-sdk/dictation-react @suki-sdk/dictation
                    </code>
                  </span>

<div>
            <h3>Support & Best Practices</h3>

<div>
              <div>
                <span>SDK support</span>

<div>
                  <a href="mailto:support@suki.ai">
                    [support@suki.ai](mailto:support@suki.ai)
                  </a>

<a href="mailto:support@suki.ai" title="Email support@suki.ai">
                      <span>Email support</span>

<div>
              <Tip>
                #### Best practices

* Store **partnerId**, **partnerToken**, and issued tokens securely; rotate credentials per your security policy.
                * Request microphone permission before capture starts; handle denial and prompts clearly in your UI.
                * Send SDK traffic over HTTPS; surface authentication failures and network errors using the patterns in each SDK guide.
                * Test across devices, OS versions, and network conditions before production rollout.
                * Always use the **latest versions of the SDKs** to get the latest features and bug fixes.
              </Tip>
            </div>
          </div>

<div>
            <h3>Languages</h3>

<span>React</span>
                </button>

<span>JavaScript</span>
                </button>

<span>Swift</span>
                </button>
              </div>

<div>
                <div>
                  ```tsx theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
                  import { SukiProvider } from '@suki-sdk/react';

export function App() {
                    return (
                      <SukiProvider>
                        {/* Your app */}
                      </SukiProvider>
                    );
                  }
                  ```
                </div>

<div>
                  ```javascript theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
                  import { SukiAuthManager } from '@suki-sdk/core';
                  import { initialize } from '@suki-sdk/js';

const authManager = new SukiAuthManager({
                    partnerId: 'your-partner-id',
                    partnerToken: 'your-partner-token',
                    providerName: 'Jane Doe',
                    providerOrgId: 'org-123',
                    environment: 'production',
                    loginOnInitialize: true,
                  });

const sdkClient = initialize({ authManager });
                  ```
                </div>

<div>
                  ```swift theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
                  import SukiAmbientCore

SukiAmbientCoreManager.shared.environment = .stage

let partnerInfo: [String: AnyHashable] = [
                      SukiAmbientConstant.kPartnerId: "your-partner-id",
                      SukiAmbientConstant.kProviderInfo: [
                          SukiAmbientConstant.kOrgId: "your-org-id",
                          SukiAmbientConstant.kName: "Provider name",
                          SukiAmbientConstant.kId: "provider-id",
                          SukiAmbientConstant.kSpeciality: "FAMILY_MEDICINE",
                      ],
                  ]

try SukiAmbientCore.shared.initialize(
                      withPartnerInfo: partnerInfo,
                      with: true,
                      onCompletion: { _ in },
                      withSessionDelegate: self,
                      withTokenProvider: self
                  )
                  ```
                </div>
              </div>
            </div>
          </div>
        </div>
      </div>
    </div>
  </div>

<section>
    <div>
      <p>Choose your SDK workflow</p>

<h2>
        Available SDKs
      </h2>

<p>
        Pick the SDK for your use case and workflow and start building your integration.
      </p>
    </div>

<span>Ambient</span>
        </button>

<span>Dictation</span>
        </button>

<span>Form filling</span>
        </button>
      </div>

<p>
                    Pre-built UI for headed ambient sessions in the browser. Available for React and JavaScript.
                  </p>
                </div>

<div>
            <span>JavaScript</span>
            <span>React</span>
            <span>Headed</span>
          </div>
        </div>

<a href="/mobile-sdk/overview" aria-label="Mobile SDK documentation">
              <div>
                <div>
                  <h3>Mobile SDK</h3>

<p>
                    Native iOS integration with headless APIs for ambient sessions in your healthcare app.
                  </p>
                </div>

<div>
            <span>Swift</span>
            <span>iOS</span>
          </div>
        </div>

<a href="/headless-web-sdk/introduction" aria-label="Headless Web SDK documentation">
              <div>
                <div>
                  <h3>Headless Web SDK</h3>

<p>
                    React hooks and a platform client for custom UI and maximum control over ambient flows.
                  </p>
                </div>

<div>
            <span>React</span>
            <span>Headless</span>
          </div>
        </div>

<a href="/dictation-sdk/introduction" aria-label="Dictation SDK documentation">
              <div>
                <div>
                  <h3>Dictation SDK</h3>

<p>
                    Hosted iframe dictation for clinical speech-to-text; separate from full ambient note generation.
                  </p>
                </div>

<div>
            <span>React</span>
            <span>IFRAME</span>
          </div>
        </div>

<div aria-label="Form filling SDK (coming soon)">
              <div>
                <div>
                  <h3>Form Filling SDK</h3>
                  <p>Under development, we will release it soon. Stay tuned for updates.</p>
                </div>

<div>
            <span>Coming soon</span>
          </div>
        </div>
      </div>
    </div>
  </section>

<div>
    <a href="/documentation/workflows" aria-label="Decide your SDK path">
      Decide Your SDK Path

<div>
    <h2>Start building</h2>

<span>
          <span>Workflows Overview</span>
          <span>Learn more about comparing SDKs and how to choose your integration path.</span>
        </span>
      </a>

<span>
          <span>Web SDK - Create Session</span>
          <span>Build your first ambient session, stream audio, and retrieve the note in minutes.</span>
        </span>
      </a>

<span>
          <span>Mobile SDK - Create Session</span>
          <span>Build your first ambient session, stream audio, and retrieve the note in minutes.</span>
        </span>
      </a>

<span>
          <span>Headless Web SDK - Create Session</span>
          <span>Build your first ambient session, stream audio, and retrieve the note in minutes.</span>
        </span>
      </a>

<span>
          <span>Dictation SDK - Configuration</span>
          <span>Configure the Dictation SDK with your partner credentials and settings.</span>
        </span>
      </a>

<span>
          <span>Web SDK Quickstart</span>
          <span>Build your first headed Web SDK flow in minutes.</span>
        </span>
      </a>

<span>
          <span>Headless Web SDK Quickstart</span>
          <span>Build your first headless ambient flow in minutes.</span>
        </span>
      </a>

<span>
          <span>Partner Onboarding</span>
          <span>Learn more about partner onboarding to start using Suki SDKs.</span>
        </span>
      </a>
    </div>
  </div>

<div>
    <h2>Stay updated</h2>

<p>
      Learn about the latest updates for the Web SDK, Mobile SDK, Headless Web SDK, and Dictation SDK.
    </p>

<div>
      <CardGroup>
        <Card title="Web SDK Changelog" icon="bell-ring" href="/web-sdk/product-updates/changelog">
          Releases and migration notes for the headed Web SDK packages.
        </Card>

<Card title="Mobile SDK Changelog" icon="bell-ring" href="/mobile-sdk/product-updates/changelog">
          iOS SDK updates, deprecations, and behavior changes.
        </Card>

<Card title="Headless Web SDK Changelog" icon="bell-ring" href="/headless-web-sdk/changelog">
          Platform React package updates for ambient hooks and clients.
        </Card>

<Card title="Dictation SDK Changelog" icon="bell-ring" href="/dictation-sdk/changelog">
          Dictation iframe and package updates for JavaScript and React tracks.
        </Card>
      </CardGroup>
    </div>
  </div>
</div>

# Suki SDKs Quickstart
Source: https://developer.suki.ai/sdk-overview/quickstart

Quickstarts for the Suki SDKs

Get started with the Suki SDKs by following the quickstarts below for your workflow of choice.

<CardGroup>
  <Card title="Web SDK Quickstart" icon="rocket" href="/web-sdk/quickstart">
    Build your first ambient session, stream audio, and retrieve the note in minutes.
  </Card>

<Card title="Mobile SDK Quickstart" icon="rocket" href="/mobile-sdk/overview">
    Build your first ambient session, stream audio, and retrieve the note in minutes.
  </Card>

<Card title="Headless Web SDK Quickstart" icon="rocket" href="/headless-web-sdk/quickstart">
    Build your first ambient session, stream audio, and retrieve the note in minutes.
  </Card>

<Card title="Dictation SDK Quickstart" icon="rocket" href="/dictation-sdk/quickstart">
    Build your first ambient session, stream audio, and retrieve the note in minutes.
  </Card>
</CardGroup>

# Announcements For Partners
Source: https://developer.suki.ai/updates/announcements

Important announcements and updates about the Suki Developer Documentation site

Stay informed about important announcements, maintenance windows, new features, and other updates related to the Suki Developer Documentation.

## Current announcements

<div>
      <h3>Documentation v4.6.0 is live</h3>
      <p>May 2026</p>
      <a href="/updates/release-notes">Explore what's new →</a>
    </div>
  </div>
</div>

## Maintenance & system updates

### Scheduled maintenance

Currently, no scheduled maintenance is planned. Any future maintenance windows will be announced here at least 48 hours in advance.

### System status

* **Documentation Site**: Operational
* **API Playground**: Operational
* **Search Service**: Operational
* **CDN & Assets**: Operational

For real-time system status, visit our [Status page](https://status-platform.suki.ai/).

## How to stay informed

<CardGroup>
  <Card title="Site Banners" icon="megaphone">
    Critical announcements appear as dismissible banners at the top of all pages
  </Card>

<Card title="This Page" icon="bookmark">
    Bookmark this announcements page and check back regularly for updates
  </Card>

<Card title="Email Updates" icon="envelope">
    Subscribe to receive monthly updates by email across products and workflows
  </Card>
</CardGroup>

# April 2025
Source: https://developer.suki.ai/updates/apr2025-release-notes

April 2025 release notes for Suki APIs and SDKs

This release adds the Web SDK v2.0.0 major release with automated user registration, LOINC code integration, and expanded theme customization.

## What's changed

<Update label="April 2025 - Changed" description="Web SDK v2.0.0 major release">
  ### Major changes

<Badge icon="cube">Web SDK v2.0.0</Badge> | <Badge icon="exclamation-triangle">Breaking changes</Badge>

**Major release**: We've added automated user registration, LOINC code integration for note sections, and expanded theme customization.

**Why it matters**: Automated registration simplifies onboarding. LOINC integration supports structured note sections. Theme customization helps match your app's branding.

Learn more in the [Migration guide](/web-sdk/product-updates/migration-to-v2) and [Theming guide](/web-sdk/examples/theming-and-customization).
</Update>

# April 2026
Source: https://developer.suki.ai/updates/apr2026-release-notes

April 2026 release notes for Suki APIs and SDKs

This release adds the **Dictation SDK (beta)** for clinical dictation in the browser with a hosted iframe, **in-field** and **scratchpad** modes,
and JavaScript or React callbacks for transcripts. For the **Web SDK**, we've shipped **SukiAuthManager** and **@suki-sdk/core** for authentication, plus
optional visit and provider fields in `ambientOptions` so sessions carry more context, notes read better in the UI, and the patient note list can show **visit type** as the title instead of **Note** on every row.
For the **Mobile SDK**, we've added optional **orders info**
for medications and **EMR info** for ambient sessions. For the **API**, new **info** endpoints return supported
values for medication coding systems, dosage units, encounter relations, frequencies, medication timings, origins, and statuses.

## What's new

<Update label="April 2026 - New">
  ### New features

<Badge icon="microphone">Dictation SDK v0.1.0</Badge>

**Dictation SDK (beta)**: First release of the Suki Dictation SDK. Embed clinical dictation in your web app with a hosted iframe, **in-field** mode tied to a text field or **scratchpad** mode for a floating surface, and JavaScript or React integration. You control how users start dictation; the SDK returns transcript text through callbacks.

**Why it matters**: Ship browser-based clinical dictation without building the full dictation UI yourself, while keeping your own chrome and workflows.

Learn more in the [Dictation SDK introduction](/dictation-sdk/introduction) documentation and [Changelog](/dictation-sdk/changelog).

**New info endpoints**: Added new endpoints to get the list of supported medication coding systems, dosage units, encounter relations, frequencies, medication timings, origins, and statuses.

**Endpoints**:

* <Badge>GET</Badge> [/api/v1/info/orders/coding-systems](/api-reference/info/orders-coding-systems) to get the list of supported medication coding systems.
  * <Badge>GET</Badge> [/api/v1/info/orders/dosage-units](/api-reference/info/orders-dosage-units) to get the list of supported medication dosage units.
  * <Badge>GET</Badge> [/api/v1/info/orders/encounter-relations](/api-reference/info/orders-encounter-relations) to get the list of supported encounter relations.
  * <Badge>GET</Badge> [/api/v1/info/orders/frequencies](/api-reference/info/orders-frequencies) to get the list of supported medication frequencies.
  * <Badge>GET</Badge> [/api/v1/info/orders/medication-timings](/api-reference/info/orders-medication-timings) to get the list of supported medication timings.
  * <Badge>GET</Badge> [/api/v1/info/orders/origins](/api-reference/info/orders-origins) to get the list of supported medication origins.
  * <Badge>GET</Badge> [/api/v1/info/orders/statuses](/api-reference/info/orders-statuses) to get the list of supported medication statuses.

**Why it matters**: This allows you to get the list of supported medication coding systems, dosage units, encounter relations, frequencies, medication timings, origins, and statuses.

Learn more in the [Info endpoints](/api-reference/info/orders) reference.
</Update>

## What's enhanced

<Update label="April 2026 - Enhanced">
  ### Enhancements

<Badge icon="cube">Web SDK v3.0.0</Badge> | <Badge icon="exclamation-triangle">Breaking changes</Badge>

**Web SDK new authentication flow**: Sign-in now goes through **SukiAuthManager** from **@suki-sdk/core**, the same model as our other SDKs. Add that core package next to **@suki-sdk/js** or **@suki-sdk/react**, configure partner credentials, staging or production, and provider details on the manager, and pass the manager when you start the Web SDK in JavaScript or React. You no longer rely on putting those fields only on the init call. Pick stage versus production with the manager's environment setting instead of test mode on init options.

**Why it matters**: One auth surface across SDKs, clearer separation between sign-in and UI setup, and explicit environment choice before the hosted experience loads.

Learn more in the [Migrating to Web SDK v3](../web-sdk/product-updates/migration-to-v3) guide.

**Optional session-level metadata**: Pass **visit context** (`visitType`, `encounterType`, `reasonForVisit`, `chiefComplaint`) and **providerRole** in `ambientOptions` to improve note generation. Pass these at session init (e.g. in `mount` or when calling `setAmbientOptions`).

**Why it matters**: Improve note generation accuracy by passing session-level metadata alongside your LOINC sections.

Learn more in the [Ambient implementation](/web-sdk/guides/ambient-implementation) guide and [AmbientOptions](/web-sdk/api-reference/types/ambient-options#properties) reference.

**Custom note titles**: We've updated the Web SDK so the patient note list can show a real title instead of **Note** for every entry.

Set **`visitType`** in **`ambientOptions`** when you start the session (same place you pass the other visit fields). The list uses that value as the note title. If you skip it, behavior stays the same as before.

***

***

**Why it matters**: When more than one note is created on the same day, clinicians can see labels like **`ESTABLISHED_PATIENT`** or **`WELLNESS`** instead of several rows that all say **Note**.

Learn more in the [Note management](/web-sdk/guides/note-management#note-titles-in-the-web-sdk-ui) guide.

<Badge icon="mobile">Mobile SDK v2.6.0</Badge>

**Medication orders in session context**: We have added **optional orders info** for Suki iOS SDK ambient sessions. You can now include medications tied to a visit, such as those from your EHR, while keeping your session creation flow the same.

**Implementation steps:**

To include medication orders, follow these requirements:

* **Method call**: After you create the session, call `setSessionContext(with:)` using the `SukiAmbientConstant.kOrdersInfo` constant.
  * **Data structure**: Place each order within the `MedicationOrderKeys.kMedicationOrders` key.

**Why it matters**: Note generation can use medications tied to the visit (for example from your EMR) while your session creation flow stays the same.

Learn more in the [Medication orders](/mobile-sdk/ambient-guides/provide-clinical-context#orders-info) section of the provide clinical context guide.

<Badge icon="mobile">Mobile SDK v2.6.0</Badge>

**EMR info in session context**: We have added **optional EMR info** for Suki iOS SDK ambient sessions. You can now include information about the EMR system that applies to the session, such as the vendor code or environment-specific label.

**Implementation steps:**

To include EMR info, follow these requirements:

* **Method call**: After you create the session, call `setSessionContext(with:)` using the `SukiAmbientConstant.kEmrInfo` constant.
  * **Data structure**: Place the EMR info within the `SukiAmbientConstant.kEmrInfo` key.
  * **Required fields**: The `SukiAmbientConstant.kTargetEmr` key is required with a string identifier for the target EMR.

**Why it matters**: Note generation can use the EMR info to generate notes that are specific to the EMR system.

Learn more in the [EMR info](/mobile-sdk/ambient-guides/provide-clinical-context#emr-info) section of the provide clinical context guide.

**Medication order support**: Medication orders are now supported in the API. You can now send and retrieve medication orders for an ambient session and encounter using the following endpoints:

* <Badge>GET</Badge> [/api/v1/ambient/session//structured-data](/api-reference/ambient-content/structured-data)
  * <Badge>GET</Badge> [/api/v1/ambient/session//encounter-structured-data](/api-reference/ambient-content/encounter-structured-data)
  * <Badge>POST</Badge> [/api/v1/ambient/session//context](/api-reference/ambient-sessions/update-context)
  * <Badge>GET</Badge> [/api/v1/ambient/session//content](/api-reference/ambient-content/content)
  * <Badge>GET</Badge> [/api/v1/ambient/session//encounter-content](/api-reference/ambient-content/encounter-content)

**Why it matters**: This allows you to send and retrieve medication orders for an ambient session to be used in the note generation process.

Learn more in the [Medication orders](/documentation/medication-orders) documentation and [Changelog](/api-reference/product-updates/changelog).
</Update>

# December 2024
Source: https://developer.suki.ai/updates/dec2024-release-notes

December 2024 release notes for Suki APIs and SDKs

This release adds the Web SDK v1.0.0 stable release and includes stability improvements for subsequent patch versions.

## What's new

<Update label="December 2024 - New" description="Web SDK v1.0.0 stable release">
  ### New features

**Initial stable release**: We've released the first stable version of the Web SDK with enhanced user experience, faster note generation, and improved stability.

**Why it matters**: Production-ready Web SDK for clinical note creation with improved UX and performance.
</Update>

## What's fixed

<Update label="December 2024 - Fixed" description="Stability improvements">
  ### Resolved issues

**Stability**: Various bug fixes and stability improvements.

**Stability**: Various bug fixes and stability improvements.

**Why it matters**: Improves reliability for production use.
</Update>

# December 2025
Source: https://developer.suki.ai/updates/dec2025-release-notes

December 2025 release notes for Suki APIs and SDKs

This release adds the Audio Transcription API, visit context parameters for the iOS SDK, and the initial beta of the Headless Web SDK.

## What's new

<Update label="December 2025 - New" description="Audio transcription API">
  ### New features

**Audio transcription API**: We've added support for real-time audio transcription.

Create transcription sessions, stream transcription data, and end sessions to get final transcripts for dictation, captioning, and transcript generation.

* <Badge>POST</Badge> [/api/v1/transcription/session/create](/api-reference/audio-transcription/create-session)
  * <Badge>POST</Badge> [/api/v1/transcription/session//end](/api-reference/audio-transcription/end-session)
  * <Badge>GET</Badge> [/ws/transcribe](/api-reference/audio-transcription/stream-transcription)

**Why it matters**: Supports dictation, live captioning, and transcript generation without ambient note creation.
</Update>

**Visit context parameters**: We've added support for visit-related metadata in `setSessionContext`: visit type, encounter type, provider role, reason for visit, and chief complaint to improve note accuracy.

<Badge icon="react">Headless Web SDK v0.1.1</Badge>

**Initial beta release**: We've released the first beta of the Headless Web SDK for building custom ambient integrations with full UI control.

**Why it matters**: Visit context improves note quality. The Headless Web SDK lets you build custom ambient UIs with full control over layout and behavior.

Learn more in the [Headless Web SDK changelog](/headless-web-sdk/changelog).
</Update>

# February 2025
Source: https://developer.suki.ai/updates/feb2025-release-notes

February 2025 release notes for Suki APIs and SDKs

This release includes stability improvements for the Web SDK.

## What's fixed

<Update label="February 2025 - Fixed" description="Stability improvements">
  ### Resolved issues

**Stability**: Various bug fixes and stability improvements.

**Why it matters**: Improves reliability and reduces unexpected behavior in production.
</Update>

# February 2026
Source: https://developer.suki.ai/updates/feb2026-release-notes

February 2026 release notes for Suki APIs and SDKs

This release deprecates the multilingual parameter in the Create Ambient Session endpoint. Multilingual support is now enabled by default.

## What's changed

<Update label="February 2026 - Changed">
  ### Deprecated

**Multilingual parameter**: We've deprecated the `multilingual` parameter in the Create Ambient Session endpoint. Multilingual support is now enabled by default when you call the API.

**Why it matters**: Simplifies API calls. You no longer need to pass `multilingual`; multilingual support is always on. Update your integration to remove this parameter.

Learn more in the [Create ambient session](/api-reference/ambient-sessions/create) API reference.
</Update>

# January 2026
Source: https://developer.suki.ai/updates/jan2026-release-notes

January 2026 release notes for Suki APIs and SDKs

This release adds session type detection to the Headless Web SDK, enables multilingual by default in the Web SDK, makes optional patient fields optional, and removes the prefill.noteTypeIds property from AmbientOptions.

## What's new

<Update label="January 2026 - New">
  ### New features

<Badge icon="react">Headless Web SDK v0.2.2</Badge>

**Session type detection**: We've added a `sessionType` property to the `useAmbientSession` hook.

It indicates whether a session was submitted while online or offline, so you can display appropriate UI indicators and handle offline sessions differently.

**Why it matters**: Lets you show the correct UI state (online vs offline) and handle offline sessions with different logic or messaging.

Learn more in the [Headless Web SDK changelog](/headless-web-sdk/changelog).
</Update>

## What's enhanced

<Update label="January 2026 - Enhanced">
  ### Enhancements

**Multilingual capability** is now enabled by default in the Web SDK. Patients and providers can speak in their preferred language; the SDK generates the clinical note in English. No configuration is required, and you do not need to contact Technical Support to enable this feature.

**Optional patient fields**: We've made the `birthDate` and `gender` properties **optional** on the `Patient` type.

Omit these fields when creating patient objects if the information is not available.

**Why it matters**: Multilingual works out of the box. Optional patient fields make it easier to integrate when birth date or gender is not available in your system.
</Update>

## What's removed

<Update label="January 2026 - Removed">
  ### Removed

**AmbientOptions**: We've removed the `prefill.noteTypeIds` property from the `AmbientOptions` type.

You must use the `sections` property instead.

**Why it matters**: If you use `prefill.noteTypeIds`, update your code to use the `sections` property before upgrading.
</Update>

# July 2024
Source: https://developer.suki.ai/updates/jul2024-release-notes

July 2024 release notes for Suki APIs and SDKs

This release adds the initial Web SDK for clinical note creation.

## What's new

<Update label="July 2024 - New" description="Web SDK v0.5.0 initial release">
  ### New features

**Initial release**: We've released the first version of the Web SDK for clinical note creation by listening to provider–patient conversations.

**Why it matters**: Enables web-based ambient clinical documentation from provider–patient conversations.

Learn more in the [Web SDK changelog](/web-sdk/product-updates/changelog).
</Update>

# July 2025
Source: https://developer.suki.ai/updates/jul2025-release-notes

July 2025 release notes for Suki APIs and SDKs

This release adds personalization preferences and diagnosis context to the iOS SDK.

## What's new

<Update label="July 2025 - New" description="Personalization and diagnosis context">
  ### New features

**Personalization preferences**: We've added `setPersonalizationPreferences(_:completionHandler:)` to configure verbosity levels and note section styles (narrative or bulleted) for supported LOINC sections.

**Diagnosis context and structured data**: We've added `SukiAmbientConstant.kDiagnosisInfo` to `setSessionContext` for diagnosis context and `getStructuredData(for:onCompletion:)` for structured output and diagnoses (ICD10, IMO, SNOMED).

**Why it matters**: Personalization lets you match note style to provider preferences. Diagnosis context and structured data support billing and downstream systems.
</Update>

# June 2025
Source: https://developer.suki.ai/updates/jun2025-release-notes

June 2025 release notes for Suki APIs and SDKs

This release adds Bearer token authentication, session context method, and resolves ambient event and ID state issues. It also removes the insert script option from section editing.

## What's new

<Update label="June 2025 - New" description="Bearer token and session context">
  ### New features

**Bearer token authentication**: We've added support for Bearer token authentication by allowing you to pass `providerId` during SDK initialization.

**Session context method**: We've introduced `setSessionContext(with:onCompletion:)` for setting patient, provider context, and LOINC codes after session creation, with improved session workflow and LOINC integration.

**Why it matters**: Bearer token auth fits common auth flows. Session context lets you set patient and provider data after session creation for more flexible workflows.
</Update>

## What's fixed

<Update label="June 2025 - Fixed" description="Ambient event and ID state">
  ### Resolved issues

**Ambient event and ID state**: We've fixed incorrect `isAmbientInProgress` and `isAmbientPaused` flags in `ambient:update` events and fixed `activeAmbientId` not resetting in the `useSuki` hook after a session is submitted or cancelled.

**Why it matters**: Ensures your UI reflects the correct ambient state and avoids stale session IDs.
</Update>

## What's removed

<Update label="June 2025 - Removed" description="Section editing">
  ### Removed

**Section editing**: We've removed the insert script option from section editing in the note page.

**Why it matters**: If you rely on the insert script option, you will need an alternative approach.
</Update>

# June 2026
Source: https://developer.suki.ai/updates/jun2026-release-notes

June 2026 release notes for Suki APIs and SDKs

This release adds **Medication orders** to the headed **Web SDK**. During ambient sessions, clinicians can review recommended medications in the built-in note UI, and your application receives structured order data on note submit. For the **Ambient API**, **Dictation API**, and **Form Filling API**, you now have the option to authenticate providers with a **Single Auth Token** shared across all clinicians. When you choose this option, you must send `sdp_provider_id` on every REST and WebSocket request so Suki can route each call to the correct provider.

## What's enhanced

<Update label="June 2026 - Enhanced">
  ### Enhancements

**Medication orders**: The Suki Web SDK now supports **Medication orders generation during ambient sessions**. During a visit, the SDK identifies recommended medications from the clinician's conversation and displays them in the built-in **Medication orders** section for review. When the provider submits the note, the SDK returns structured order data in the note submission payload.

To enable this capability, pass the LOINC code `52471-0` in the `ambientOptions.sections` array when you mount the Web SDK or set ambient options.

* Medication orders are supported on **v2** and **v3** versions of the Web SDK.
  * Combine `52471-0` with your other note sections and a PBC section when you need to link orders to problems in the same session.
  * On note submit, parse `orders.medication_orders` from the payload and send validated orders to your EHR.

***

***

**Implementation**

**Why it matters**: Clinicians can review and complete medication orders inside the headed Web SDK without leaving the ambient workflow. Your application receives structured JSON on note submission so you can validate and persist orders to the EHR the same way you handle note `contents`.

Learn more in the [Medication orders overview](/web-sdk/medication-orders/overview), [Medication orders payload structure](/web-sdk/medication-orders/payload-structure), and [Web SDK changelog](/web-sdk/product-updates/changelog).

<Badge icon="code">API v1.4.0</Badge> | <Badge icon="code">Form Filling API v1.1.0</Badge>

**Single Auth Token authentication**: You now have the option to authenticate providers in your application using a single authentication token for all clinicians. When you choose this option, your backend uses one shared `partner_token` instead of a per-user token. The shared token proves your organization is authorized, but it does not identify who is signed in. You **must** send `sdp_provider_id` on every REST API and WebSocket API call so Suki can route each request to the correct clinician.

This applies to **Ambient, Dictation, and Form Filling API** requests. Send `sdp_provider_id` on Register and Login, and include it on every subsequent request along with `sdp_suki_token`.

**Why it matters**: You can support multiple clinicians with one organization token without a separate IdP token per user, while Suki still knows which provider each request is for.

Learn more in the [Provider authentication](/api-reference/provider-authentication#authentication-with-a-single-auth-token) guide.
</Update>

# March 2026
Source: https://developer.suki.ai/updates/mar2026-release-notes

March 2026 release notes for Suki APIs and SDKs

This release adds **Audio streaming & download** so you can stream or download original ambient session audio for playback, verification, and compliance. For the Web SDK **(v2.1.2)**, we've added **notification webhooks** for session completion and failure (no polling) and **existing patient diagnoses** in `ambientOptions` so PBC notes merge EMR problems with what's discussed in the visit.

## What's new

<Update label="March 2026 - New">
  ### New features

**Audio streaming and download**: We've added a new endpoint to stream or download the original audio recording from an ambient session. Get a presigned URL for any completed session and use it for playback, note verification, or compliance storage.

**Why it matters**: Enables playback in your app, verification of AI notes against the conversation, and compliance use cases that require retaining the original audio.

Learn more in the [Audio streaming and download](/documentation/audio-streaming-download) guide. For the full API reference, refer to [Get session recording](/api-reference/ambient-content/recording).
</Update>

## What's enhanced

<Update label="March 2026 - Enhanced">
  ### Enhancements

**Webhook support**: We've added notification webhook support for the Web SDK. When a session completes or fails, Suki sends a POST to your callback URL, same as when using the direct API. Configure one webhook URL per partner during onboarding.

**Why it matters**: Receive session completion and failure notifications when using the Web SDK without polling.

Learn more in the [Notification webhook](/documentation/webhook/overview) guide.

**Existing patient diagnoses for Problem-Based Charting**: Pass the patient's existing diagnoses (e.g. from the EMR) into an ambient session using the `diagnoses` block in `ambientOptions`. The session merges them with what's discussed during the visit so you avoid duplicate problems in the note. Use this when you have at least one PBC section (`isPBNSection: true`); each diagnosis needs one **ICD10** code.

**Why it matters**: Seed the problem list from the EMR and get one merged note without duplicates when the provider or patient discusses those problems.

Learn more in the [Existing patient diagnoses](/web-sdk/guides/ambient-problem-based-charting#existing-patient-diagnoses) guide.
</Update>

# May 2025
Source: https://developer.suki.ai/updates/may2025-release-notes

May 2025 release notes for Suki APIs and SDKs

This release adds problem-based charting, audio buffering, multilingual support, and resolves offline upload and session recovery issues.

## What's new

<Update label="May 2025 - New" description="Problem-based charting and audio buffering">
  ### New features

**Problem-based charting**: We've added support for problem-based charting (PBN) with LOINC via the `isPBNSection` property in `ambientOptions`.

Learn more in the [Ambient guide](/web-sdk/guides/ambient-problem-based-charting).

**Audio buffering and multilingual**: We've implemented audio buffering to reduce offline sessions caused by brief internet interruptions and added `SukiAmbientConstant.kMultilingual` for multilingual processing support.

**Why it matters**: PBN supports problem-oriented documentation. Audio buffering reduces lost sessions from brief network drops. Multilingual supports diverse patient populations.
</Update>

## What's enhanced

<Update label="May 2025 - Enhanced" description="Default UI and background recording">
  ### Enhancements

**Default UI options**: We've updated default values for `uiOptions` to match the latest UI configuration: close button, start ambient button, dictation, copy, and insert script are enabled by default; create empty note is disabled by default.

**Background recording handling**: We've added proper error handling when attempting to start recording while the app is backgrounded, providing clearer error messages and preventing unexpected behavior.

**Why it matters**: Default UI aligns with recommended configuration. Background recording errors are clearer and easier to handle.
</Update>

## What's fixed

<Update label="May 2025 - Fixed" description="Offline upload and session recovery">
  ### Resolved issues

**Offline upload and session recovery**: We've fixed the "No record exist for offline upload" failure category identified through the note failure tracing dashboard. We've also improved session recovery reliability during network transitions.

**Why it matters**: Reduces offline upload failures and improves reliability when the network drops and recovers.
</Update>

# May 2026
Source: https://developer.suki.ai/updates/may2026-release-notes

May 2026 release notes for Suki APIs and SDKs

This release introduces the **Form Filling API (beta)** so you can create and manage form-filling sessions, retrieve structured data, submit feedback,
and query medical form templates for nursing workflows and data collection during in-person or virtual encounters. For the **Web SDK**, we've shipped **Minimized layout**:
the headed UI shrinks to a compact, viewport-aligned widget during ambient sessions so clinicians keep the
EHR or patient chart in focus while capture continues in the background, and developers can reclaim screen space for your own UI.

## What's new

<Update label="May 2026 - New">
  ### New features

<Badge icon="code">Form Filling API v1.0.0</Badge>

**Form Filling API**: The initial release of the Suki Form Filling API. This API allows you to create and manage form-filling sessions, retrieve structured data, submit feedback, and get information about medical form templates for nursing workflows and data collection during in-person visits or virtual encounters.

**Available endpoints**:

* <Badge>POST</Badge> [/api/v1/form-filling/session/create](/form-filling-api-reference/form-filling-sessions/create) - Create a new form-filling session
  * <Badge>POST</Badge> [/api/v1/form-filling/session//context](/form-filling-api-reference/form-filling-sessions/context) - Get the context for a form-filling session
  * <Badge>PATCH</Badge> [/api/v1/form-filling/session//context](/form-filling-api-reference/form-filling-sessions/update-context) - Update the context for a form-filling session
  * <Badge>POST</Badge> [/api/v1/form-filling/session//end](/form-filling-api-reference/form-filling-sessions/end) - End a form-filling session
  * <Badge>GET</Badge> [/api/v1/form-filling/session//status](/form-filling-api-reference/form-filling-sessions/status) - Get the status of a form-filling session
  * <Badge>GET</Badge> [/api/v1/form-filling/session//structured-data](/form-filling-api-reference/form-filling-sessions/structured-data) - Get the structured data for a form-filling session
  * <Badge>POST</Badge> [/api/v1/form-filling/session///feedback](/form-filling-api-reference/form-filling-sessions/feedback) - Submit feedback for a form-filling session
  * <Badge>GET</Badge> [/api/v1/info/suki-medical-form-templates](/form-filling-api-reference/info/suki-medical-form-templates) - Get information about medical form templates

**Why it matters**: Build voice-driven form workflows with Suki-defined templates. Create a session, stream visit audio, and retrieve generated form instances that your application can review, edit, and save to the EHR or another downstream system.

Learn more in the [Form Filling API overview](/form-filling-api-reference/overview).
</Update>

## What's enhanced

<Update label="May 2026 - Enhanced">
  ### Enhancements

**Minimized layout**: The Suki Web SDK now supports a minimized layout for ambient sessions in the headed iframe. When minimize capability is enabled, the UI can move from the full headed panel into a compact, viewport-aligned widget while recording, pause, cancel, and generate actions continue in the same session.

* The SDK sends layout values such as `expanded`, `minimized`, and `minimized-paused` so your host app can collapse the mount wrapper and let the chart or other primary content reclaim the space.

**Why it matters**: Clinicians can keep documentation capture running while reading the EHR, reviewing orders, or working in a dense chart layout. Developers get the SDK-managed minimized widget, but still control the surrounding layout by:

* Collapsing the mount wrapper
  * Keeping overflow visible
  * Restoring the full headed panel when the SDK returns to `expanded`

Learn more in the [Minimized layout overview](/web-sdk/minimized-layout/overview) and [Minimized layout implementation](/web-sdk/minimized-layout/implementation) guides.
</Update>

## What's fixed

<Update label="May 2026 - Fixed">
  ### Resolved issues

<Badge icon="cube">Headless Web SDK v0.2.3</Badge>

**Bug fixes**: Various bug fixes and stability improvements.

**Why it matters**: Improves reliability and reduces unexpected behavior in production.
</Update>

# November 2025
Source: https://developer.suki.ai/updates/nov2025-release-notes

November 2025 release notes for Suki APIs and SDKs

This release adds telehealth audio capture to the Web SDK and code examples for all Ambient APIs.

## What's new

<Update label="November 2025 - New" description="Telehealth audio capture">
  ### New features

**Telehealth audio capture**: We've added the ability to capture audio from separate tabs in the same browser window (e.g. Zoom, Teams) for accurate ambient documentation during virtual visits.

This feature is opt-in and disabled by default.

**Why it matters**: Enables accurate ambient documentation during virtual visits when the patient is in a separate video call tab.

Learn more in the [Telehealth guide](/web-sdk/guides/telehealth).
</Update>

## What's enhanced

<Update label="November 2025 - Enhanced" description="Code examples">
  ### Enhancements

**Code examples**: We've added code examples in Python and TypeScript for all Ambient APIs.

**Why it matters**: Speeds up integration by providing ready-to-use examples in common languages.
</Update>

# October 2025
Source: https://developer.suki.ai/updates/oct2025-release-notes

October 2025 release notes for Suki APIs and SDKs

This release introduces info endpoints, enhanced ambient session context, iOS SDK improvements, and documentation updates. It also removes SNOMED and paused state support.

## What's new

<Update label="October 2025 - New" description="Info endpoints and context">
  ### New features

**Info endpoints and context**: We've introduced three info endpoints for supported enum values (encounter types, visit types, provider roles) and updated ambient session context to support `VisitContext` (e.g. chief complaint, visit type) and enhanced provider context (e.g. provider\_role).

Learn more in [Info endpoints](/api-reference/info/encounter-types) and [Ambient session context](/api-reference/ambient-sessions/context).

**User feedback and audio buffer**: We've added `submitFeedback(_:for:onCompletion:)` for feedback on AI-generated content and the `audioBufferFilled(withPercentage:)` delegate for connection status in the UI.

**Why it matters**: Info endpoints let you validate and display supported values. Visit and provider context improve note accuracy. User feedback and audio buffer improve UX and connection visibility.
</Update>

## What's enhanced

<Update label="October 2025 - Enhanced" description="Documentation and offline handling">
  ### Enhancements

**Documentation**: We've added [API reference guidelines](/api-reference/api-guidelines), restructured and enhanced API documentation, rewritten the Problem-Based Charting guide, and added detailed authentication guidance for the Audio streaming API.

Learn more in the [API changelog](/api-reference/product-updates/changelog).

**Offline handling**: We've added a 15-second buffer before transitioning to offline mode to handle temporary connection problems and allow connection status notifications in the UI.

**Getting started guide**: We've improved the getting started guide with a workflow diagram to help you understand the process of using the Suki Mobile SDK.

**Why it matters**: Better documentation speeds up integration. The offline buffer reduces false offline transitions during brief network hiccups.
</Update>

## What's removed

<Update label="October 2025 - Removed" description="SNOMED and paused state">
  ### Removed

**SNOMED and paused state**: We've removed support for SNOMED codes in the diagnosis context.

We've also removed support for the paused state for ambient sessions.

**Why it matters**: If you use SNOMED in diagnosis context or the paused state, update your integration before upgrading.

Learn more in the [Ambient session context](/api-reference/ambient-sessions/context) API reference.
</Update>

# Release & Versioning Policy
Source: https://developer.suki.ai/updates/release-and-versioning

Learn how Suki versions APIs and SDKs, where release information is published, and how to plan upgrades and migrations for your integration

Suki provides the clinical intelligence infrastructure used by leading healthcare software providers and
vendors to build applications on top of Suki capabilities. As a trusted partner, we are committed to providing a stable and reliable platform that you can build on with confidence.

This page explains:

* How Suki versions APIs and SDKs
* How changes are labeled and published
* Where to find release information
* How to plan upgrades and migrations
* Why we publish updates this way

## Why we publish updates this way

Many integrations use more than one Suki product, such as ambient workflows, form filling, dictation, and SDKs. To support that model, Suki publishes updates through two channels:

<CardGroup>
  <Card title="Monthly release notes" icon="calendar">
    Cross-product visibility each month: what shipped across ambient, form filling, dictation, and SDKs, with paths into deeper docs.
  </Card>

<Card title="Product changelogs" icon="list">
    Version-level history per product: labels, tags, breaking-change callouts, snippets, and migration pointers. Open each changelog from the Release notes hub.
  </Card>
</CardGroup>

Together, these channels help you understand:

* What changed
* Whether your integration is affected
* Where to find implementation details

<Note>
  Release notes provide a **workflow-level summary**. Changelogs provide **product-specific technical detail**.
</Note>

## Versioning

Suki uses **semantic versioning** (SemVer) for SDKs and documented release trains:

For example:

<Callout>
  **MAJOR.MINOR.PATCH**

Example: `3.1.0`
</Callout>

| Version segment | Meaning                                                                                  |
| --------------- | ---------------------------------------------------------------------------------------- |
| **Major**       | Breaking or incompatible changes that might require migration work or regression testing |
| **Minor**       | Backward-compatible features or capabilities                                             |
| **Patch**       | Backward-compatible fixes and documentation updates                                      |

### Product versioning

<Tabs>
  <Tab title="SDKs">
    SDKs, including the Web SDK, Mobile SDK, Headless Web SDK, and Dictation SDK, are released as **versioned npm packages**.

A **major** version increase usually indicates that code or configuration changes are required. When applicable, changelog entries include **migration guidance**.
  </Tab>

<Tab title="APIs">
    REST APIs include a version segment in the URL when applicable, such as **`v1`**. That pattern applies across Ambient, Dictation, Form Filling, and our other REST surfaces.

Current Suki REST APIs are released under **`v1`**.
    Changelog release labels, such as `v1.0.0` or `v1.3.0`, represent incremental product releases. They are separate from the API path version. Those releases can include:

* New endpoints
    * Optional fields
    * Behavior updates
    * Bug fixes

Always review the changelog entry for release-specific details. Changelogs are organized by product line:

* [Ambient and Dictation APIs changelog](/api-reference/product-updates/changelog)
    * [Form Filling API changelog](/form-filling-api-reference/changelog)
  </Tab>
</Tabs>

### Breaking and non-breaking changes

Use the following guidance when reviewing API changes.

<CardGroup>
  <Card title="Usually Non-Breaking Changes" icon="check-circle">
    These changes are typically backward compatible:

* New optional request or response fields
    * New endpoints
    * Performance improvements
    * Documentation clarifications
  </Card>

<Card title="Potentially Breaking Changes" icon="exclamation-triangle">
    Review these changes carefully before upgrading:

* New required fields
    * Renamed fields
    * Removed endpoints or fields
    * Stricter validation
    * Changed default behavior
    * Any update marked as <Badge icon="exclamation-triangle">Breaking changes</Badge>

If a changelog entry identifies a <Badge icon="exclamation-triangle">Breaking changes</Badge>, update clients or configuration **before** adopting the new behavior.
  </Card>
</CardGroup>

## Where changes are published

| Channel                                 | Purpose                                                                         |
| --------------------------------------- | ------------------------------------------------------------------------------- |
| [Release notes](/updates/release-notes) | Monthly summaries across workflows such as ambient, form filling, and dictation |
| [Announcements](/updates/announcements) | Site-wide notices and operational updates                                       |
| Product changelogs                      | Product-specific version history, release details, and migration guidance       |

### Product changelogs

We maintain dedicated changelogs for each of our product lines. This helps you understand the specific changes and updates for each product.

For regular updates, we highly recommend subscribing to the [Release notes](/updates/release-notes) hub to receive monthly updates across products.

**How to subscribe:**

| Option                                 | What to do                                                                                                                  |
| -------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- |
| <Icon icon="rss" /> **RSS**            | Open the [Release notes](/updates/release-notes) hub and use the **RSS** button to subscribe to the monthly feed.           |
| <Icon icon="envelope" /> **Subscribe** | Open the [Release notes](/updates/release-notes) hub and use **Subscribe** to get monthly updates by email across products. |

## How to read monthly release notes

Monthly release notes are organized by **calendar month** and **workflow area**, not by a single platform-wide version number.

To review a monthly release:

1. Open the month from the [Release notes](/updates/release-notes) hub.
2. Review the available section headings for that month.
3. Use **product badges** to identify the products relevant to your integration.
4. Read the **Why it matters** section when available.
5. Follow links to changelogs, guides, or API reference documentation before updating production integrations.

### Monthly release note sections

| Section             | Description                                                                                 |
| ------------------- | ------------------------------------------------------------------------------------------- |
| **What's new**      | New capabilities, workflows, SDKs, or API families                                          |
| **What's enhanced** | Improvements to existing functionality, including additive features and reliability updates |
| **What's changed**  | Behavioral updates, terminology changes, operational notes, or partner-facing adjustments   |
| **What's removed**  | Deprecations and removals, including migration recommendations when available               |

<Note>
  **Important**:

* Not every release includes every section.
  * Monthly release notes **supplement** changelogs. They do not replace detailed version history.
</Note>

## Changelog policy

Each product changelog is the **authoritative source** for that product line.

Changelog entries include:

* A release label such as `v3.1.0`
* Tags that summarize the update
* Clear identification of breaking changes
* Integration examples and code snippets when applicable

The [Ambient and Dictation APIs changelog](/api-reference/product-updates/changelog) also supports **scope filters** for narrowing results by API category.

<Tip>
  If the same update appears in both release notes and a changelog, use the **changelog** for exact version boundaries and migration guidance.
</Tip>

## Release notes and changelogs

Use **release notes** to understand:

<Callout>
  What changed this month across the workflows my organization uses?
</Callout>

Use **changelogs** to understand:

<Callout>
  What changed in this specific SDK or API release, and what updates are required in my integration?
</Callout>

**Recommended workflow:**

## Recommended best practices

Suki recommends that partners:

<Tip>
  * **Pin** SDK and dependency versions in production.
  * **Review changelogs** before upgrading.
  * Treat **major** releases and **breaking** changes as planned upgrade work.
  * **Test** integrations before production rollout.
  * Treat **optional fields** and **new endpoints** as additive functionality.
  * **Subscribe** to release notifications through RSS or email.
</Tip>

If you have questions about your integration, contact your Suki representative or email [support@suki.ai](mailto:support@suki.ai).

# Release Notes
Source: https://developer.suki.ai/updates/release-notes

Release notes by workflow (ambient clinical intelligence, form filling, dictation) and integration surface, with links to product changelogs.

<div>
  <div>
    <div>
      <div>
        <h1>Suki For Partners Release</h1>

<span>Subscribe to updates</span>
            </button>
          </span>

<div>
          <div>
            <div>
              <h2>
                Subscribe to email updates
              </h2>

<p>
              Sign up below to get notified when new partner releases are published, or use the RSS feed instead.
            </p>

<label>
                    Name
                    <span> (required)</span>
                  </label>
                </div>

<label>
                    Email address
                    <span> (required)</span>
                  </label>
                </div>

<button type="submit">
                  Subscribe
                </button>

<p>
                  By clicking "Subscribe" you agree that your personal data will be processed in accordance with our

<a href="https://www.suki.ai/privacy-policy/">
                    Privacy Policy
                  </a>

.
                </p>
              </form>

<span>Submitting…</span>
                </div>

<div>
              <p>
                Email signup is not wired for this site yet. Set <code>releaseNotesSubscribeSubmitUrl</code> (Apps Script Web app <code>/exec</code> URL for duplicate-safe signup) and/or
                <code>releaseNotesSubscribeEmbedUrl</code> in <code>docs.json</code>, then redeploy.
              </p>

<p>
                <a href="/updates/release-notes-rss-feed/rss.xml">
                  Subscribe with RSS instead
                </a>
              </p>
            </div>
          </div>
        </div>
      </div>

<p>
        Get the latest updates and changes in Suki for Partners developer platform. Subscribe to the release notes to receive monthly updates across products.
      </p>

<span>Ambient</span>
          </button>

<span>Form filling</span>
          </button>

<span>Dictation</span>
          </button>
        </div>

<a href="/api-reference/product-updates/changelog" aria-label="Ambient API changelog">
                  <div>
                    <div>
                      <h3>Ambient API Changelog</h3>
                      <p>Ambient API product updates and announcements</p>
                    </div>

<div>
                <span>Latest v1.4.0</span>
              </div>
            </div>

<a href="/web-sdk/product-updates/changelog" aria-label="Web SDK changelog">
                  <div>
                    <div>
                      <h3>Web SDK Changelog</h3>
                      <p>Web SDK product updates and announcements</p>
                    </div>

<div>
                <span>Latest v3.1.0</span>
              </div>
            </div>

<a href="/mobile-sdk/product-updates/changelog" aria-label="Mobile SDK changelog">
                  <div>
                    <div>
                      <h3>Mobile SDK Changelog</h3>
                      <p>Mobile SDK product updates and announcements</p>
                    </div>

<div>
                <span>Latest v2.6.0</span>
              </div>
            </div>

<a href="/headless-web-sdk/changelog" aria-label="Headless Web SDK changelog">
                  <div>
                    <div>
                      <h3>Headless SDK Changelog</h3>
                      <p>Headless Web SDK product updates and announcements</p>
                    </div>

<div>
                <span>Latest v0.2.3</span>
              </div>
            </div>

<a href="/dictation-sdk/changelog" aria-label="Dictation SDK changelog">
                  <div>
                    <div>
                      <h3>Dictation SDK Changelog</h3>
                      <p>Dictation SDK product updates and announcements</p>
                    </div>

<div>
                <span>Latest v0.1.0</span>
              </div>
            </div>

<a href="/form-filling-api-reference/changelog" aria-label="Form filling APIs changelog">
                  <div>
                    <div>
                      <h3>Form Filling API Changelog</h3>
                      <p>Form filling API product updates and announcements</p>
                    </div>

<div>
                <span>Latest v1.1.0</span>
              </div>
            </div>
          </div>
        </div>

<Note>
          For how we version APIs and SDKs, how release notes relate to product changelogs, and how to plan upgrades and migrations, refer to the [Release and versioning policy](/updates/release-and-versioning) guide.
        </Note>

<div>
          <div>
            <div>
              <div>
                <label>
                  Category
                </label>

<li>
                      <button type="button">
                        Mobile-SDK
                      </button>
                    </li>

<li>
                      <button type="button">
                        Headless-Web-SDK
                      </button>
                    </li>

<li>
                      <button type="button">
                        Dictation-SDK
                      </button>
                    </li>

<li>
                      <button type="button">
                        Form filling APIs
                      </button>
                    </li>
                  </ul>
                </div>
              </div>

<div>
                <label>
                  Attention
                </label>

<div>
                  <button type="button">
                    <span>All attention levels</span>

<ul>
                    <li>
                      <button type="button">
                        All attention levels
                      </button>
                    </li>

<li>
                      <button type="button">
                        Noteworthy
                      </button>
                    </li>

<li>
                      <button type="button">
                        Breaking changes
                      </button>
                    </li>

<li>
                      <button type="button">
                        Deprecated
                      </button>
                    </li>

<li>
                      <button type="button">
                        Action required
                      </button>
                    </li>

<li>
                      <button type="button">
                        Removed
                      </button>
                    </li>
                  </ul>
                </div>
              </div>
            </div>

<p>
            No timeline entries match this combination of workflow, category, and attention for the expanded months above. Try All on the filters, or open the changelog cards for granular updates.
          </p>

<div>
                  <div>
                    <div>
                      <a href="/updates/jun2026-release-notes">View full release notes →</a>
                    </div>

<div>
                      <div>
                        <Badge icon="cube">Web SDK</Badge> |
                        <Badge icon="lightbulb">Noteworthy</Badge> |
                        <Badge icon="sparkles">New</Badge>
                        <h3>Medication orders</h3>

<p>
                          The Headed Web SDK now supports Medication orders generation during ambient sessions. Pass LOINC code <code>52471-0</code> in <code>ambientOptions.sections</code> to enable review in the note UI and structured JSON on note submit.
                        </p>

<p>
                          <a href="/web-sdk/medication-orders/overview">Learn more: Medication orders overview</a>
                          <span> · </span>
                          <a href="/web-sdk/medication-orders/payload-structure">Medication orders payload structure</a>
                        </p>
                      </div>

<div>
                        <Badge icon="code">API v1.4.0</Badge> |
                        <Badge icon="code">Form Filling API v1.1.0</Badge> |
                        <Badge icon="lightbulb">Noteworthy</Badge>
                        <h3>Single Auth Token authentication</h3>

<p>
                          You now have the option to authenticate providers using a single authentication token for all clinicians. When you choose this option, you must send <code>sdp\_provider\_id</code> as a header on every API call so Suki can route each request to the correct clinician. This applies to Ambient, Dictation, and Form Filling API requests.
                        </p>

<p>
                          <a href="/api-reference/provider-authentication#authentication-with-a-single-auth-token">Learn more: Provider authentication</a>
                        </p>
                      </div>
                    </div>
                  </div>
                </div>
              </li>

<div>
                  <div>
                    <div>
                      <a href="/updates/may2026-release-notes">View full release notes →</a>
                    </div>

<div>
                      <div>
                        <Badge icon="cube">Web SDK v3.1.0</Badge> |
                        <Badge icon="sparkles">New</Badge>
                        <h3>Minimized layout</h3>

<p>
                          The headed Web SDK can shrink to a compact, viewport-aligned widget during ambient sessions so clinicians keep focus on the EHR or chart while capture continues in the background.
                        </p>

<p>
                          <a href="/web-sdk/minimized-layout/overview">Learn more: Minimized layout overview</a>
                          <span> · </span>
                          <a href="/web-sdk/minimized-layout/implementation">Minimized layout implementation</a>
                        </p>
                      </div>

<div>
                        <Badge icon="code">Form Filling API v1.0.0</Badge> |
                        <Badge icon="sparkles">New</Badge>
                        <h3>Form Filling API</h3>

<p>
                          Our new Suki Form Filling API allows you to create and manage form-filling sessions, retrieve structured data, submit feedback, and get info about medical form templates for nursing use cases and data collection during
                          in-person visits or virtual patient encounters.
                        </p>

<p>
                          <a href="/form-filling-api-reference/overview">Learn more: Form Filling API overview</a>
                          <span> · </span>
                          <a href="/form-filling-api-reference/changelog">Form Filling API changelog</a>
                        </p>
                      </div>

<div>
                        <Badge icon="cube">Headless Web SDK v0.2.3</Badge> |
                        <Badge icon="bug">Bug fixes</Badge>
                        <h3>Bug fixes and stability improvements</h3>

<p>
                          Minor bug fixes and stability improvements for the Headless Web SDK.
                        </p>
                      </div>
                    </div>
                  </div>
                </div>
              </li>

<li>
                <div>
                  <span>April</span>
                  <span>2026</span>
                </div>

<div>
                  <div>
                    <div>
                      <a href="/updates/apr2026-release-notes">View full release notes →</a>
                    </div>

<div>
                      <div>
                        <Badge icon="microphone">Dictation SDK v0.1.0</Badge> |
                        <Badge icon="sparkles">New</Badge>
                        <h3>Dictation SDK (beta)</h3>

<p>
                          Initial <strong>beta</strong> release of the Suki Dictation SDK so you can embed clinical dictation in the browser with a hosted iframe, <strong>in-field</strong> or <strong>scratchpad</strong> modes, and callbacks for transcript text from JavaScript or React.
                        </p>

<p>
                          <a href="/dictation-sdk/introduction">Learn more: Dictation SDK overview</a>
                          <span> · </span>
                          <a href="/dictation-sdk/changelog">Dictation SDK changelog</a>
                        </p>
                      </div>

<div>
                        <Badge icon="cube">Web SDK v3.0.0</Badge> |
                        <Badge icon="exclamation-triangle">Breaking changes</Badge> |
                        <Badge icon="bolt">Action required</Badge>
                        <h3>New authentication flow</h3>

<p>
                          Sign-in now goes through <strong>SukiAuthManager</strong> from <code>@suki-sdk/core</code>, the same model as our other SDKs. Configure the manager with partner credentials, environment, and provider details, then pass it when you start the Web SDK.
                        </p>

<p>
                          <a href="/web-sdk/product-updates/migration-to-v3">Learn more: Migrating to Web SDK v3</a>
                          <span> · </span>
                          <a href="/web-sdk/quickstart">Web SDK quickstart</a>
                        </p>
                      </div>

<div>
                        <Badge icon="cube">Web SDK v2.2.0</Badge> |
                        <Badge icon="lightbulb">Noteworthy</Badge>
                        <h3>Optional session-level metadata</h3>

<p>
                          Pass optional visit and provider fields in <code>ambientOptions</code> when you start a session (for example <code>visitType</code>, <code>encounterType</code>, <code>reasonForVisit</code>, <code>chiefComplaint</code>, and <code>providerRole</code>) so note generation has better context.
                        </p>

<p>
                          <a href="/web-sdk/guides/ambient-implementation">Learn more: Ambient implementation</a>
                          <span> · </span>
                          <a href="/web-sdk/api-reference/types/ambient-options#properties">AmbientOptions properties</a>
                        </p>
                      </div>

<div>
                        <Badge icon="cube">Web SDK v2.2.0</Badge> |
                        <Badge icon="lightbulb">Noteworthy</Badge>
                        <h3>Note list titles from visit type</h3>

<p>
                          When <code>visitType</code> is set in <code>ambientOptions</code>, the Web SDK uses it as the note title for each generated note in the patient note list instead of the generic <strong>Note</strong> label, so multiple notes from the same day are easier to distinguish.
                        </p>

<a href="/web-sdk/guides/note-management#note-titles-in-the-web-sdk-ui">Learn more: Note titles</a>
                      </div>

<div>
                        <Badge icon="mobile">Mobile SDK v2.6.0</Badge> |
                        <Badge icon="sparkles">New</Badge>
                        <Badge icon="bolt">Action required</Badge>
                        <h3>Medication orders in session context</h3>

<p>
                          Provide optional medication orders via <code>SukiAmbientConstant.kOrdersInfo</code> and <code>MedicationOrderKeys.kMedicationOrders</code> after session creation in the iOS SDK to include medications tied to a visit, such as those from your EHR.
                        </p>

<p>
                          <a href="/mobile-sdk/ambient-guides/provide-clinical-context#orders-info">Learn more: Orders info</a>
                        </p>
                      </div>

<div>
                        <Badge icon="mobile">Mobile SDK v2.6.0</Badge> |
                        <Badge icon="lightbulb">Noteworthy</Badge>
                        <h3>EMR info in session context</h3>

<p>
                          Provide optional EMR info via <code>SukiAmbientConstant.kEmrInfo</code> after session creation in the iOS SDK, to include information about the EMR system that applies to the session, such as the vendor code or environment-specific label.
                        </p>

<p>
                          <a href="/mobile-sdk/ambient-guides/provide-clinical-context#emr-info">Learn more: EMR info</a>
                        </p>
                      </div>

<div>
                        <Badge icon="code">API v1.3.0</Badge> |
                        <Badge icon="sparkles">New</Badge>
                        <h3>New info endpoints</h3>

<p>
                          Added new endpoints to get the list of supported medication coding systems, dosage units, encounter relations, frequencies, medication timings, origins, and statuses.
                        </p>

<p>
                          <a href="/api-reference/info/orders">Learn more: Info endpoints</a>
                        </p>
                      </div>

<div>
                        <Badge icon="code">API v1.3.0</Badge> |
                        <Badge icon="sparkles">New</Badge>
                        <h3>Medication order support</h3>

<p>
                          Medication orders are now supported in the API. You can now send and retrieve medication orders for an ambient session to be used in the note generation process.
                        </p>

<p>
                          <a href="/documentation/medication-orders">Learn more: Medication orders</a>
                          <span> · </span>
                          <a href="/api-reference/product-updates/changelog#enhancements">Learn more: Changelog</a>
                        </p>
                      </div>
                    </div>
                  </div>
                </div>
              </li>

<li>
                <div>
                  <span>March</span>
                  <span>2026</span>
                </div>

<div>
                  <div>
                    <div>
                      <a href="/updates/mar2026-release-notes">View full release notes →</a>
                    </div>

<div>
                      <div>
                        <Badge icon="code">API v1.2.1</Badge> |
                        <Badge icon="sparkles">New</Badge>
                        <h3>Audio streaming and download</h3>

<p>
                          New endpoint to stream or download the original audio from an ambient session using a presigned URL. Use it for playback, note verification, or compliance storage.
                        </p>

<p>
                          <a href="/documentation/audio-streaming-download">Learn more: Audio streaming and download</a>
                          <span> · </span>
                          <a href="/api-reference/ambient-content/recording">Get session recording API</a>
                        </p>
                      </div>

<div>
                        <Badge icon="cube">Web SDK v2.1.2</Badge> |
                        <Badge icon="sparkles">New</Badge>
                        <h3>Webhook support</h3>

<p>
                          When a session completes or fails, Suki sends a POST to your callback URL, same as when using the direct API. Configure one webhook URL per partner during onboarding.
                        </p>

<a href="/documentation/webhook/overview">Learn more: Notification webhook</a>
                      </div>

<div>
                        <Badge icon="cube">Web SDK v2.1.2</Badge> |
                        <Badge icon="lightbulb">Noteworthy</Badge>
                        <h3>Existing patient diagnoses for Problem-Based Charting</h3>

<p>
                          Pass existing diagnoses from the EMR in <code>ambientOptions.diagnoses</code> so the session merges them with what's discussed during the visit and avoids duplicate problems in the note.
                        </p>

<a href="/web-sdk/guides/ambient-problem-based-charting#existing-patient-diagnoses">Learn more: Existing patient diagnoses</a>
                      </div>
                    </div>
                  </div>
                </div>
              </li>

<li>
                <div>
                  <span>February</span>
                  <span>2026</span>
                </div>

<div>
                  <div>
                    <div>
                      <a href="/updates/feb2026-release-notes">View full release notes →</a>
                    </div>

<div>
                      <div>
                        <Badge icon="code">API v1.1.1</Badge> |
                        <Badge icon="bolt">Action required</Badge>
                        <h3>Multilingual parameter deprecated</h3>

<p>
                          Removed <code>multilingual</code> from Create Ambient Session calls. Multilingual support is always on, which simplifies integration.
                        </p>

<a href="/api-reference/ambient-sessions/create">Learn more: Create ambient session</a>
                      </div>
                    </div>
                  </div>
                </div>
              </li>

<li>
                <div>
                  <span>January</span>
                  <span>2026</span>
                </div>

<div>
                  <div>
                    <div>
                      <a href="/updates/jan2026-release-notes">View full release notes →</a>
                    </div>

<div>
                      <div>
                        <Badge icon="react">Headless Web SDK v0.2.2</Badge> |
                        <Badge icon="lightbulb">Noteworthy</Badge>
                        <h3>Session type detection</h3>

<p>
                          <code>useAmbientSession</code> exposes <code>sessionType</code> so you can tell whether a session was submitted online or offline and adjust UI or handling.
                        </p>

<a href="/headless-web-sdk/changelog">Learn more: Headless Web SDK changelog</a>
                      </div>

<div>
                        <Badge icon="cube">Web SDK v2.1.1</Badge> |
                        <Badge icon="lightbulb">Noteworthy</Badge>
                        <h3>Multilingual and optional patient fields</h3>

<p>
                          Multilingual is on by default in the Web SDK. <code>birthDate</code> and <code>gender</code> on <code>Patient</code> are optional when that data is unavailable.
                        </p>
                      </div>

<div>
                        <Badge icon="cube">Web SDK v2.1.1</Badge> |
                        <Badge icon="bolt">Action required</Badge>
                        <h3>AmbientOptions: prefill.noteTypeIds removed</h3>

<p>
                          Use the <code>sections</code> property instead of <code>prefill.noteTypeIds</code> before upgrading.
                        </p>
                      </div>
                    </div>
                  </div>
                </div>
              </li>
            </ul>

<ul aria-label="2025 release notes by month">
              <li>
                <div>
                  <span>December</span>
                  <span>2025</span>
                </div>

<li>
                <div>
                  <span>November</span>
                  <span>2025</span>
                </div>

<li>
                <div>
                  <span>October</span>
                  <span>2025</span>
                </div>

<li>
                <div>
                  <span>September</span>
                  <span>2025</span>
                </div>

<li>
                <div>
                  <span>April</span>
                  <span>2025</span>
                </div>

<li>
                <div>
                  <span>February</span>
                  <span>2025</span>
                </div>

<ul aria-label="2024 release notes by month">
              <li>
                <div>
                  <span>December</span>
                  <span>2024</span>
                </div>

# Release Notes
Source: https://developer.suki.ai/updates/release-notes-rss-feed

Stay updated with the latest releases and improvements for Suki for Partners.

<Update label="June 2026" description="Partner updates">
  [View June 2026 release notes](https://developer.suki.ai/updates/jun2026-release-notes)
</Update>

<Update label="May 2026" description="Partner updates">
  [View May 2026 release notes](https://developer.suki.ai/updates/may2026-release-notes)
</Update>

<Update label="April 2026" description="Monthly release notes">
  [View April 2026 release notes](https://developer.suki.ai/updates/apr2026-release-notes)
</Update>

<Update label="March 2026" description="Monthly release notes">
  [View March 2026 release notes](https://developer.suki.ai/updates/mar2026-release-notes)
</Update>

<Update label="February 2026" description="Monthly release notes">
  [View February 2026 release notes](https://developer.suki.ai/updates/feb2026-release-notes)
</Update>

<Update label="January 2026" description="Monthly release notes">
  [View January 2026 release notes](https://developer.suki.ai/updates/jan2026-release-notes)
</Update>

<Update label="December 2025" description="Monthly release notes">
  [View December 2025 release notes](https://developer.suki.ai/updates/dec2025-release-notes)
</Update>

<Update label="November 2025" description="Monthly release notes">
  [View November 2025 release notes](https://developer.suki.ai/updates/nov2025-release-notes)
</Update>

<Update label="October 2025" description="Monthly release notes">
  [View October 2025 release notes](https://developer.suki.ai/updates/oct2025-release-notes)
</Update>

<Update label="September 2025" description="Monthly release notes">
  [View September 2025 release notes](https://developer.suki.ai/updates/sep2025-release-notes)
</Update>

<Update label="July 2025" description="Monthly release notes">
  [View July 2025 release notes](https://developer.suki.ai/updates/jul2025-release-notes)
</Update>

<Update label="June 2025" description="Monthly release notes">
  [View June 2025 release notes](https://developer.suki.ai/updates/jun2025-release-notes)
</Update>

<Update label="May 2025" description="Monthly release notes">
  [View May 2025 release notes](https://developer.suki.ai/updates/may2025-release-notes)
</Update>

<Update label="April 2025" description="Monthly release notes">
  [View April 2025 release notes](https://developer.suki.ai/updates/apr2025-release-notes)
</Update>

<Update label="February 2025" description="Monthly release notes">
  [View February 2025 release notes](https://developer.suki.ai/updates/feb2025-release-notes)
</Update>

<Update label="December 2024" description="Monthly release notes">
  [View December 2024 release notes](https://developer.suki.ai/updates/dec2024-release-notes)
</Update>

<Update label="July 2024" description="Monthly release notes">
  [View July 2024 release notes](https://developer.suki.ai/updates/jul2024-release-notes)
</Update>

# September 2025
Source: https://developer.suki.ai/updates/sep2025-release-notes

September 2025 release notes for Suki APIs and SDKs

This release adds event monitoring, offline handling improvements, and user feedback collection to the Web SDK.

## What's enhanced

<Update label="September 2025 - Enhanced" description="Event monitoring and offline handling">
  ### Enhancements

**Event monitoring**: We've added six new authentication events and five new ambient session lifecycle events to the `EmitterEvents` type for login, registration, token refresh, and session state changes.

Learn more in [EmitterEvents](/web-sdk/api-reference/types/emitter-events).

**Offline handling**: We've added a 15-second buffer before transitioning to offline mode to handle temporary connection problems.

**User feedback**: We've added the ability to collect user feedback on AI-generated content directly through the SDK.

**Why it matters**: More events let you build richer UI and analytics. The offline buffer reduces false offline transitions. User feedback supports model improvement and quality monitoring.
</Update>

# Classes Reference
Source: https://developer.suki.ai/web-sdk/api-reference/classes

Web SDK class definitions, constructors, and methods reference

This section provides a detailed reference for all classes available in the Suki Web SDK.

## SDKClient instance

The `SDKClientInstance` is the primary interface for interacting with the Suki Web SDK, providing comprehensive methods for managing encounters, ambient sessions, and event subscriptions.

The code snippet below shows how to use the `SDKClientInstance` class to interact with the Suki Web SDK.

```js JavaScript theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
interface SDKClientInstance {
  activeAmbientId: string | null;
  attemptLogin(): Promise<true | void>;
  setPartnerToken(partnerToken: string): void;
  cancelAmbient(): void;
  cleanup(): void;
  destroy(): void;
  mount(options: MountOptions): Promise<void>;
  on<T extends keyof EmitterEvents>(
    type: T,
    handler: (data: EmitterEvents[T]) => void | Promise<void>,
  ): () => void;
  pauseAmbient(): void;
  resumeAmbient(): void;
  setAmbientOptions(options: AmbientOptions): void;
  setEncounter(encounter: Encounter): Promise<void>;
  startAmbient(): void;
  submitAmbient(): void;
}
```

### Properties

<ResponseField name="activeAmbientId" type="string | null">
  The ID of the currently active ambient session, or `null` if no session is active.
</ResponseField>

### Available methods

<Expandable title="available methods">
  <ResponseField name="attemptLogin" type="Promise<true | void>">
    Re-authenticates the user with the SDK. This method does not take any parameters.
  </ResponseField>

<ResponseField name="cancelAmbient" type="void">
    Cancels the current ambient session. This method does not take any parameters.
  </ResponseField>

<ResponseField name="cleanup" type="void">
    Cleans up the SDK and removes all event listeners. This method does not take any parameters.
  </ResponseField>

<ResponseField name="destroy" type="void">
    Destroys the SDK instance and stops the token refresh mechanism. This method does not take any parameters. For more information, see the [Token refresh](/web-sdk/guides/token-refresh) guide.
  </ResponseField>

<ResponseField name="mount" type="Promise<void>">
    Mounts the SDK to a specified DOM element with the provided configuration options.

<Expandable title="parameters">
      <ResponseField name="options" type="MountOptions" href="/web-sdk/api-reference/types#mountoptions">
        The configuration options for mounting the SDK.
      </ResponseField>
    </Expandable>
  </ResponseField>

<ResponseField name="on" type="() => void">
    Subscribes to SDK events. This method returns an unsubscribe function.

<Expandable title="parameters">
      <ResponseField name="type" type="T">
        The type of event to subscribe to (e.g., `'ready'`, `'ambient:update'`).
      </ResponseField>

<ResponseField name="handler" type="(data: EmitterEvents[T]) => void | Promise<void>">
        The callback function to be executed when the event is emitted.
      </ResponseField>
    </Expandable>
  </ResponseField>

<ResponseField name="pauseAmbient" type="void">
    Pauses the current ambient session. This method does not take any parameters.
  </ResponseField>

<ResponseField name="resumeAmbient" type="void">
    Resumes a paused ambient session. This method does not take any parameters.
  </ResponseField>

<ResponseField name="setAmbientOptions" type="void">
    Updates the ambient session configuration dynamically.

<Expandable title="parameters">
      <ResponseField name="options" type="AmbientOptions" href="/web-sdk/api-reference/types#ambientoptions">
        The new ambient session configuration options.
      </ResponseField>
    </Expandable>
  </ResponseField>

<ResponseField name="setEncounter" type="Promise<void>">
    Sets the encounter context for the ambient session.

<Expandable title="parameters">
      <ResponseField name="encounter" type="Encounter" href="/web-sdk/api-reference/types#encounter">
        Full [`Encounter`](/web-sdk/api-reference/types/encounter) payload. **`patient.identifier`** is required. **`encounter.identifier`** is optional. Each value must be **at most 36 characters** (<Tooltip href="/Glossary/v#varchar-36">varchar(36)</Tooltip>) when present.
      </ResponseField>
    </Expandable>
  </ResponseField>

<ResponseField name="setPartnerToken" type="void">
    Updates the partner token for authentication after a token refresh.

<Expandable title="parameters">
      <ResponseField name="partnerToken" type="string">
        The new partner token string.
      </ResponseField>
    </Expandable>
  </ResponseField>

<ResponseField name="startAmbient" type="void">
    Starts a new ambient session. This method does not take any parameters.
  </ResponseField>

<ResponseField name="submitAmbient" type="void">
    Submits the current ambient session for processing. This method does not take any parameters.
  </ResponseField>
</Expandable>

## Next steps

<Icon icon="file-lines" /> Refer to the [Functions](/web-sdk/api-reference/functions) to learn more about the available functions in the Suki Web SDK.

# Components Reference
Source: https://developer.suki.ai/web-sdk/api-reference/components

Web SDK React components, props, and usage examples

This section provides a detailed reference for all React components available in the Suki Web SDK.

## SukiAssistant component

The `SukiAssistant` is the main UI component that renders the Suki Assistant interface within your React application. It manages the **display** and **interaction** for ambient sessions.

The code snippet below shows how to use the `SukiAssistant` component to render the Suki Assistant interface within your React application.

```jsx React theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
import { SukiAssistant, SukiProvider } from '@suki-sdk/react';

function App() {
  return (
    <SukiProvider>
      <SukiAssistant
        // props
      />
    </SukiProvider>
  );
}
```

### Available props

<Expandable title="available props">
  <ResponseField name="ambientOptions" type="AmbientOptions">
    Configuration options for ambient session functionality, including note sections and problem-based charting settings. Refer to the [AmbientOptions](/web-sdk/api-reference/types/ambient-options) page for more information.
  </ResponseField>

<ResponseField name="encounter" type="Encounter">
    Full [`Encounter`](/web-sdk/api-reference/types/encounter) payload. **`patient.identifier`** is required. **`encounter.identifier`** is optional. Each value must be **at most 36 characters** (<Tooltip href="/Glossary/v#varchar-36">varchar(36)</Tooltip>) when present.
  </ResponseField>

<ResponseField name="onClose" type="() => void">
    Callback function invoked when the SDK's close button is clicked. This prop is only available and functional when `uiOptions.showCloseButton` is not explicitly set to `false`. Refer to the [UIOptions](/web-sdk/api-reference/types/ui-options) page for more information.
  </ResponseField>

<ResponseField name="uiOptions" type="UIOptions">
    UI configuration options for the SDK, controlling the visibility and functionality of various interface elements like buttons and editing features. Refer to the [UIOptions](/web-sdk/api-reference/types/ui-options) page for more information.
  </ResponseField>

<ResponseField name="onNoteSubmit" type="(data: NoteSubmitData) => void">
    Callback function when a note is submitted. Refer to [emitter events](/web-sdk/api-reference/types/emitter-events#param-note-submission-success) page for more information.
  </ResponseField>
</Expandable>

### Type safety for onClose prop

The `SukiAssistant` component employs conditional typing to ensure type safety for the `onClose` prop, which is dynamically determined by the `uiOptions.showCloseButton` configuration:

<Expandable title="type safety for onClose prop">
  <ResponseField name="When uiOptions.showCloseButton is false" type="Info">
    The `onClose` prop is not available for use.
  </ResponseField>

<ResponseField name="When uiOptions.showCloseButton is true or undefined" type="Info">
    The `onClose` prop is optional and can be provided.
  </ResponseField>
</Expandable>

## Next steps

<Icon icon="file-lines" /> Refer to the [Examples section](/web-sdk/examples/basic-usage) to learn more about how to use the Web SDK in your application.

# Functions Reference
Source: https://developer.suki.ai/web-sdk/api-reference/functions

Web SDK utility functions, initialization methods, and helper functions

This section provides a detailed reference for all functions available in the Suki Web SDK.

## Initialize function

The `initialize` function is used to initialize the SDK with the provided options and returns a configured client instance.

The code snippet below shows how to use the `initialize` function to initialize the SDK with the provided options and returns a configured client instance.

```js JavaScript theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
import { initialize } from "@suki-sdk/js";

initialize(options: InitOptions): SDKClientInstance
```

Initializes the SDK with the provided options and returns a configured client instance.

Web SDK v3 expects an `authManager` instance from `@suki-sdk/core` on the options object instead of partner fields alone on `initialize()`. See [Migrating to Web SDK v3](/web-sdk/product-updates/migration-to-v3).

### Parameters

<ResponseField name="options" type="InitOptions" href="/web-sdk/api-reference/types#initoptions">
  The configuration options required to initialize the SDK.
</ResponseField>

### Returns

It returns a [`SDKClientInstance`](/web-sdk/api-reference/classes#sdkclient-instance) - The initialized SDK client instance is ready for use.

## Next steps

<Icon icon="file-lines" /> Refer to [Hooks](/web-sdk/api-reference/hooks) for more information on the available hooks.

# Hooks Reference
Source: https://developer.suki.ai/web-sdk/api-reference/hooks

Learn about Web SDK React hooks for state management and SDK integration

The **`useSuki`** hook provides a React-friendly way to use the Suki Web SDK from components. It exposes session state, lets you handle SDK events, and exposes ambient methods without passing a JavaScript client instance through props.

### Prerequisites

**`useSuki`** must be used within a component tree wrapped by [`SukiProvider`](/web-sdk/api-reference/providers).

### Common use cases

* **Initialization:** Call **`init`** with your configuration options. Use **`isInitialized`** to avoid redundant initialization and to gate UI logic.
* **Token management:** Call **`setPartnerToken`** when the host application supplies a new **`partnerToken`**.
* **Ambient session control:** Manage the lifecycle with **`startAmbient`**, **`pauseAmbient`**, **`resumeAmbient`**, **`cancelAmbient`**, and **`submitAmbient`**.
* **State monitoring:** Read **`activeAmbientId`**, **`isAmbientInProgress`**, **`isAmbientPaused`**, and **`error`** to drive UI updates or logging.
* **Event handling:** Use **`on`** to subscribe to SDK events (for example **`ambient:update`** or **`error`**; refer to [Emitter events](/web-sdk/api-reference/types/emitter-events)). Like the JavaScript client, this returns an unsubscribe function same pattern as **`SDKClientInstance.on`** in [Classes](/web-sdk/api-reference/classes).
* **Authentication and encounter data:** Use **`setEncounter`** to push encounter context updates, and **`attemptLogin`** to trigger re-authentication same role as **`SDKClientInstance.attemptLogin`** in [Classes](/web-sdk/api-reference/classes).

<Tip>
  **Web SDK v3 migration:** **`init`** expects an **`authManager`** object from **`@suki-sdk/core`** on the options object for authentication credentials. See [Migrating to Web SDK v3](/web-sdk/product-updates/migration-to-v3).
</Tip>

## useSuki hook

### Usage

Call **`useSuki()`** with no arguments from a descendant of **`SukiProvider`**.

```typescript Typescript theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
const client: UseSukiReturn = useSuki();
```

### Returns

The hook returns a [`UseSukiReturn`](/web-sdk/api-reference/hooks#usesukireturn-type) object. Its properties and methods mirror those on [`SDKClientInstance`](/web-sdk/api-reference/classes) from the JavaScript `initialize()` path. The following sections document each field and method.

## UseSukiReturn type

Return type of the `useSuki` hook containing SDK state and methods.

```js JavaScript theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
type UseSukiReturn = {
  activeAmbientId: string | null;
  attemptLogin: () => void;
  cancelAmbient: () => void;
  error: SukiError | null;
  init: (options: ReactInitOptions) => void;
  isAmbientInProgress: boolean;
  isAmbientPaused: boolean;
  isInitialized: boolean;
  on: <T extends keyof EmitterEvents>(
    type: T,
    handler: (args: EmitterEvents[T]) => void | Promise<void>,
  ) => () => void;
  pauseAmbient: () => void;
  resumeAmbient: () => void;
  setEncounter: (encounter: Encounter) => Promise<void>;
  setPartnerToken: (partnerToken: string) => void;
  startAmbient: () => void;
  submitAmbient: () => void;
};
```

### Available properties

<Expandable title="properties">
  <ResponseField name="activeAmbientId" type="string | null">
    The ID of the currently active ambient session, or `null` if no session is active.
  </ResponseField>

<ResponseField name="error" type="SukiError | null" href="/web-sdk/api-reference/types#sukierror">
    Current error state of the SDK, or `null` if no errors.
  </ResponseField>

<ResponseField name="isAmbientInProgress" type="boolean">
    Whether an ambient session is currently in progress.
  </ResponseField>

<ResponseField name="isAmbientPaused" type="boolean">
    Whether the current ambient session is paused.
  </ResponseField>

<ResponseField name="isInitialized" type="boolean">
    Whether the SDK has been successfully initialized.
  </ResponseField>
</Expandable>

### Available methods

<Expandable title="available methods">
  <ResponseField name="attemptLogin" type="void">
    Attempts to authenticate when SDK is not authenticated after initialization. This method does not take any parameters.
  </ResponseField>

<ResponseField name="cancelAmbient" type="void">
    Cancels the current ambient session. This method does not take any parameters.
  </ResponseField>

<ResponseField name="init" type="void">
    Initializes the SDK with the provided options. Web SDK v3 passes `authManager` from `@suki-sdk/core` on `options` instead of partner fields alone. See [Migrating to Web SDK v3](/web-sdk/product-updates/migration-to-v3).

<Expandable title="parameters">
      <ResponseField name="options" type="ReactInitOptions" href="/web-sdk/api-reference/types#initoptions">
        The configuration options required to initialize the SDK.
      </ResponseField>
    </Expandable>
  </ResponseField>

<ResponseField name="on" type="() => void">
    Subscribes to SDK events. This method returns an unsubscribe function.

<Expandable title="parameters">
      <ResponseField name="type" type="T">
        The type of event to subscribe to (e.g., `'ready'`, `'ambient:update'`).
      </ResponseField>

<ResponseField name="handler" type="(args: EmitterEvents[T]) => void | Promise<void>">
        The callback function to be executed when the event is emitted.
      </ResponseField>
    </Expandable>
  </ResponseField>

<ResponseField name="pauseAmbient" type="void">
    Pauses the current ambient session. This method does not take any parameters.
  </ResponseField>

<ResponseField name="resumeAmbient" type="void">
    Resumes a paused ambient session. This method does not take any parameters.
  </ResponseField>

<ResponseField name="setEncounter" type="Promise<void>">
    Updates the current encounter data.

<ResponseField name="setPartnerToken" type="void">
    Updates the partner token after token refresh.

<Expandable title="parameters">
      <ResponseField name="partnerToken" type="string">
        The new partner token string.
      </ResponseField>
    </Expandable>
  </ResponseField>

<ResponseField name="startAmbient" type="void">
    Starts a new ambient session. This method does not take any parameters.
  </ResponseField>

<ResponseField name="submitAmbient" type="void">
    Submits the current ambient session. This method does not take any parameters.
  </ResponseField>
</Expandable>

## Next steps

<Icon icon="file-lines" /> Refer to the [Provider types](/web-sdk/api-reference/providers) to learn more about the provider types.

# Providers Reference
Source: https://developer.suki.ai/web-sdk/api-reference/providers

Web SDK React providers and context configuration

## SukiProvider

The main provider component for the Suki SDK, which wraps your application and provides context for the SDK state and methods.

```jsx React theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
import { SukiProvider } from '@suki-sdk/react';

function App() {
  return (
    <SukiProvider>
      {/* Your application components */}
    </SukiProvider>
  );
}
```

## Available properties

<ResponseField name="children" type="ReactNode">
  The child components that will have access to the Suki SDK context
</ResponseField>

## Next steps

<Icon icon="file-lines" /> Refer to [Components section](/web-sdk/api-reference/components) for more information on the available components.

# Web SDK Types Reference
Source: https://developer.suki.ai/web-sdk/api-reference/types

Web SDK TypeScript type definitions, interfaces, and enums

In TypeScript, types and interfaces describe the shape of objects you pass into the SDK (for example initialization, mounting, and encounter data). They document which fields exist, which are required, and how values are typed so your editor can validate usage against this reference.

This page groups the Web SDK type topics below: core encounter and initialization types, UI and theme configuration, ambient session types, clinical data, and utility types. Each linked page includes an overview, a type snippet, and property details. Use the cards to jump to the full definition for the type you are implementing.

## Core types

Use these types for the following purposes:

* **Encounter**: Represents a clinical encounter that includes patient-related information.
* **Patient**: Contains patient demographics and identifying details.
* **InitOptions**: Defines configuration settings used to initialize the SDK.
* **PartnerDetails**: Includes partner authentication and provider information required during initialization, as described on the Partner details page.

<Note>
  For ambient flows, **`patient.identifier`** and **`encounter.identifier`** (when set) must each be strings **at most 36 characters** (<Tooltip href="/Glossary/v#varchar-36">varchar(36)</Tooltip>). See [Patient](/web-sdk/api-reference/types/patient) and [Encounter](/web-sdk/api-reference/types/encounter).
</Note>

<CardGroup>
  <Card title="Encounter" icon="calendar" href="/web-sdk/api-reference/types/encounter">
    Clinical encounter; identifiers up to 36 characters
  </Card>

<Card title="Patient" icon="user" href="/web-sdk/api-reference/types/patient">
    Demographics; patient ID up to 36 characters
  </Card>

<Card title="InitOptions" icon="gear" href="/web-sdk/api-reference/types/init-options">
    Configuration options for initializing the SDK
  </Card>

<Card title="PartnerDetails" icon="key" href="/web-sdk/api-reference/types/partner-details">
    Partner authentication and provider information
  </Card>
</CardGroup>

## UI & theme configuration

Use these types for the following purposes:

* **ThemeOptions**: Customize the SDK's appearance.
* **MountOptions**: Mount the SDK to a DOM element and pass related options.
* **UIOptions**: Configure user interface behavior and settings.
* **SectionEditingOptions**: Configure section editing features within the SDK.

<CardGroup>
  <Card title="ThemeOptions" icon="palette" href="/web-sdk/api-reference/types/theme-options">
    Configuration for customizing SDK appearance
  </Card>

<Card title="MountOptions" icon="window" href="/web-sdk/api-reference/types/mount-options">
    Configuration for mounting SDK to DOM element
  </Card>

<Card title="UIOptions" icon="eye" href="/web-sdk/api-reference/types/ui-options">
    User interface configuration options
  </Card>

<Card title="SectionEditingOptions" icon="pen" href="/web-sdk/api-reference/types/section-editing-options">
    Configuration for section editing features
  </Card>
</CardGroup>

## Ambient session types

Use these types for the following purposes:

* **AmbientOptions**: Configure ambient session functionality.
* **Section**: Define a clinical note section using LOINC codes for ambient sessions.
* **EmitterEvents**: Handle events emitted by the Web SDK to monitor session state and process responses. See the Emitter events page for details on tracking authentication and ambient session lifecycle events.
* **NoteContent**: Define the structure of clinical note content, including optional diagnosis and LOINC code.

<CardGroup>
  <Card title="AmbientOptions" icon="microphone" href="/web-sdk/api-reference/types/ambient-options">
    Configuration for ambient session functionality
  </Card>

<Card title="Section" icon="file-lines" href="/web-sdk/api-reference/types/section">
    Clinical note section using LOINC codes
  </Card>

<Card title="EmitterEvents" icon="bell" href="/web-sdk/api-reference/types/emitter-events">
    Events emitted by the SDK for monitoring
  </Card>

<Card title="NoteContent" icon="note" href="/web-sdk/api-reference/types/note-content">
    Content structure for clinical notes
  </Card>
</CardGroup>

## Clinical data types

Use these types for the following purposes:

* **Diagnosis**: Define the structure of clinical diagnosis information, including ICD codes.

<CardGroup>
  <Card title="Diagnosis" icon="stethoscope" href="/web-sdk/api-reference/types/diagnosis">
    Clinical diagnosis information with ICD codes
  </Card>
</CardGroup>

## Utility types

Use these types for the following purposes:

* **LogLevel**: Control debug output verbosity.
* **SukiError**: Define the structure of SDK errors, including `code` and `details`. See the Suki error page for details.

<CardGroup>
  <Card title="LogLevel" icon="terminal" href="/web-sdk/api-reference/types/log-level">
    Log levels for controlling debug output
  </Card>

<Card title="SukiError" icon="triangle-exclamation" href="/web-sdk/api-reference/types/suki-error">
    Error structure with codes and details
  </Card>
</CardGroup>

## Next steps

<Icon icon="file-lines" /> Explore each type in detail by clicking on the cards above, or refer to the [Classes](/web-sdk/api-reference/classes) section for information on available SDK classes.

# AmbientOptions Type
Source: https://developer.suki.ai/web-sdk/api-reference/types/ambient-options

AmbientOptions type represents the configuration options for ambient session functionality

<Callout title="Updates" icon="bell">
  **Updated**

`v2.2.0+` Added additional optional session-level metadata: Pass **visit context** (`visitType`, `encounterType`, `reasonForVisit`, `chiefComplaint`) and **providerRole** in `ambientOptions` to improve note generation. Pass these at session init (e.g. in `mount` or when calling `setAmbientOptions`).
</Callout>

AmbientOptions type represents the configuration options for ambient session functionality. The code snippet below shows how to use the `AmbientOptions` type to create an ambient options object.

```js JavaScript theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
type AmbientOptions = { 
  sections?: Section[];
  diagnoses?: { // [!code ++:6] New in v2.1.2
    values: Array<{
      codes: Array<{ code?: string; description?: string; type: "ICD10" }>;
      diagnosis_note?: string;
    }>;
  };
  // Optional session context // [!code ++:6] New in v2.2.0
  visitType?: string;       // Enum: use values from Visit Types API
  encounterType?: string;   // Enum: use values from Encounter Types API
  providerRole?: string;   // Enum: use values from Provider Roles API
  reasonForVisit?: string;  // Max 255 characters
  chiefComplaint?: string;   // Max 255 characters
};
```

## Properties

<ResponseField name="sections" type="Section[]" href="/web-sdk/api-reference/types/section">
  Array of clinical note LOINC sections to generate suggestions for
</ResponseField>

<ResponseField name="diagnoses" type="object">
  **Optional** - Pass the patient's existing diagnoses (e.g. from the EMR) when PBC is enabled so the session merges them with what's discussed and avoids duplicate problems. Each diagnosis needs one ICD10 code. See [Existing patient diagnoses](/web-sdk/guides/ambient-problem-based-charting#existing-patient-diagnoses) for details.
</ResponseField>

<ResponseField name="visitType" type="string">
  **Optional** - Type of visit (e.g. `NEW_PATIENT`, `ESTABLISHED_PATIENT`, `WELLNESS`, `ED`). Also refer to [Visit types](/api-reference/info/visit-types) for available enum values.

<Tip>
    Pass with LOINC codes at session init to improve note accuracy.
  </Tip>

<Note>
    In the Web SDK UI, this value is used to set the **title** for the generated note in the patient note list when present, so clinicians see a meaningful label (for example, **`NEW_PATIENT`** or **`ESTABLISHED_PATIENT`**) instead of the generic **Note** label across multiple notes from the same day.
  </Note>
</ResponseField>

<ResponseField name="encounterType" type="string">
  **Optional** - Setting of the encounter (e.g. `AMBULATORY`, `INPATIENT`, `ED`).
</ResponseField>

<ResponseField name="providerRole" type="string">
  **Optional** - Provider's role in the encounter (e.g. `PRIMARY/ATTENDING`, `CONSULTING`). Also refer to [Provider roles](/web-sdk/api-reference/providers) for available enum values.
</ResponseField>

<ResponseField name="reasonForVisit" type="string">
  **Optional** - Free-text reason for the visit. Maximum **255 characters**. Helps focus the note on the primary reason for the visit.
</ResponseField>

<ResponseField name="chiefComplaint" type="string">
  **Optional** - Patient's primary complaint or concern. Maximum **255 characters**. Helps structure the chief complaint section of the note.
</ResponseField>

# Diagnosis Type
Source: https://developer.suki.ai/web-sdk/api-reference/types/diagnosis

Diagnosis type represents the structure for clinical diagnosis information

Diagnosis type represents the structure for clinical diagnosis information, including ICD codes. The code snippet below shows how to use the `Diagnosis` type to create a diagnosis object.

```js JavaScript theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
type Diagnosis = {
  icdCode: string;
  icdDescription: string;
  snomedCode: string;
  snomedDescription: string;
  hccCode: string;
  panelRanking: number;
  billable: boolean;
  problemLabel: string;
  suggestionType: "DEFAULT" | "ED" | "PL";
};
```

## Properties

<Expandable title="properties">
  <ResponseField name="icdCode" type="string">
    The ICD code for the diagnosis
  </ResponseField>

<ResponseField name="icdDescription" type="string">
    The description of the ICD code
  </ResponseField>

<ResponseField name="snomedCode" type="string">
    The SNOMED code for the diagnosis
  </ResponseField>

<ResponseField name="snomedDescription" type="string">
    The description of the SNOMED code
  </ResponseField>

<ResponseField name="hccCode" type="string">
    The HCC code for the diagnosis
  </ResponseField>

<ResponseField name="panelRanking" type="number">
    The ranking of the diagnosis in the panel
  </ResponseField>

<ResponseField name="billable" type="boolean">
    Whether the diagnosis is billable
  </ResponseField>

<ResponseField name="problemLabel" type="string">
    The label for the problem associated with the diagnosis
  </ResponseField>

<ResponseField name="suggestionType" type="DEFAULT | ED | PL">
    The type of suggestion
  </ResponseField>
</Expandable>

# EmitterEvents Type
Source: https://developer.suki.ai/web-sdk/api-reference/types/emitter-events

EmitterEvents type represents the events that can be emitted by the web SDK

EmitterEvents type represents the events the Web SDK emits to monitor session state and handle responses. The code snippet below shows how to use the `EmitterEvents` type to create an emitter events object.

Version `2.0.4` of the Suki Web SDK updates the `EmitterEvents` type. Use these events to track granular details for authentication processes and ambient session lifecycles.

## Authentication events

The web SDK supports **six new auth events** that allow you to monitor registration and token refreshes:

<Expandable title="authentication events">
  <ResponseField name="login:success" type="never">
    Emitted when a user is successfully authenticated
  </ResponseField>

<ResponseField name="login:fail" type="SukiError">
    Emitted when a user authentication fails
  </ResponseField>

<ResponseField name="register:success" type="never">
    Emitted when a user is successfully registered
  </ResponseField>

<ResponseField name="register:fail" type="SukiError">
    Emitted when a user registration fails
  </ResponseField>

<ResponseField name="token-refresh:success" type="never">
    Emitted when a user token is successfully refreshed
  </ResponseField>

<ResponseField name="token-refresh:fail" type="SukiError">
    Emitted when a user token refresh fails
  </ResponseField>
</Expandable>

## Ambient events

<Expandable title="ambient events">
  The web SDK supports **five new ambient events** that allow you to monitor the ambient session lifecycle:

<ResponseField name="ambient:start" type="object">
    Emitted when a new ambient session is started
  </ResponseField>

<ResponseField name="ambient:pause" type="object">
    Emitted when the ambient session is paused
  </ResponseField>

<ResponseField name="ambient:resume" type="object">
    Emitted when the ambient session is resumed
  </ResponseField>

<ResponseField name="ambient:cancel" type="object">
    Emitted when the ambient session is cancelled
  </ResponseField>

<ResponseField name="ambient:submit" type="object">
    Emitted when the ambient session is submitted
  </ResponseField>
</Expandable>

These additional events will help you monitor the state of the ambient session and handle responses accordingly.

```js JavaScript expandable theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
type EmitterEvents = {
  ready: never;
  "init:change": boolean;
  close: never;
  // login events supported by the Web SDK
  "login:success": never; // [!code ++:6] New in v2.0.4
  "login:fail": SukiError;
  "register:success": never; 
  "register:fail": SukiError;
  "token-refresh:success": never;
  "token-refresh:fail": SukiError;
  "ambient:update": {
    ambientId: string;
    isAmbientInProgress: boolean;
    isAmbientPaused: boolean;
  };
  // lifecycle events supported by the Web SDK
  "ambient:start": { // [!code ++:15] New in v2.0.4
    ambientId: string;
  },
  "ambient:pause": {
    ambientId: string;
  },
  "ambient:resume": {
    ambientId: string;
  },
  "ambient:cancel": {
    ambientId: string;
  },
  "ambient:submit": {
    ambientId: string;
  },
  "note-submission:success": {
    noteId: string;
    encounterId: string;
    contents: Array<{ title: string; content: NoteContent }>;
  };
  error: SukiError;
};
```

<Tip>
  To identify the `SukiError` from above events, refer to the [error codes](/web-sdk/api-reference/types/suki-error#errorcode-identifier) section for more information.
</Tip>

## Properties

<Expandable title="properties">
  <ResponseField name="ambient:update" type="object">
    Emitted when ambient session state changes
  </ResponseField>

<ResponseField name="close">
    Emitted when the SDK is closed
  </ResponseField>

<ResponseField name="error" type="SukiError">
    Emitted when an error occurs. Refer to the [SukiError](/web-sdk/api-reference/types/suki-error) page for more information.
  </ResponseField>

<ResponseField name="init:change" type="boolean">
    Emitted when initialization state changes
  </ResponseField>

<ResponseField name="note-submission:success" type="object">
    Emitted when a note is successfully submitted
  </ResponseField>

<ResponseField name="ready">
    Emitted when the SDK is ready for use
  </ResponseField>
</Expandable>

# Encounter Type
Source: https://developer.suki.ai/web-sdk/api-reference/types/encounter

Encounter type represents a clinical encounter with patient information

Encounter type represents a clinical encounter with patient information. The code snippet below shows how to use the `Encounter` type to create an encounter object.

```js JavaScript theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
type Encounter = {
  identifier?: string; // optional; max 36 characters
  patient: Patient;
};
```

## Properties

<Expandable title="properties">
  <ResponseField name="identifier" type="string">
    **Optional** - Unique identifier for the encounter. Must be a string **at most 36 characters** (<Tooltip href="/Glossary/v#varchar-36">varchar(36)</Tooltip>) when you set it.
  </ResponseField>

<ResponseField name="patient" type="Patient" href="/web-sdk/api-reference/types/patient">
    Patient information for the encounter
  </ResponseField>
</Expandable>

# InitOptions Type
Source: https://developer.suki.ai/web-sdk/api-reference/types/init-options

InitOptions type represents the configuration options for initializing the SDK

<Callout title="Updates" icon="bell">
  **Web SDK `v3.X.X+`:** Pass a `SukiAuthManager` instance from `@suki-sdk/core` using the `authManager` field on `initialize` or `init` instead of supplying partner fields only on those calls.

Refer to [Migrating to Web SDK v3](/web-sdk/product-updates/migration-to-v3) for more details.
</Callout>

InitOptions type represents the configuration options for initializing the SDK. The code snippet below shows how to use the `InitOptions` type to create an init options object.

```js JavaScript theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
type InitOptions = PartnerDetails & {
  enableDebug?: boolean;
  logLevel?: LogLevel;
  isTestMode?: boolean;
  theme?: ThemeOptions;
};
```

## Properties

The following properties are available on the `InitOptions` type:

<Expandable title="properties">
  <ResponseField name="enableDebug" type="boolean">
    Whether to enable debug mode. This will log additional information to the console
  </ResponseField>

<ResponseField name="logLevel" type="LogLevel" href="/web-sdk/api-reference/types/log-level">
    The log level to use when debug mode is enabled. Controls which messages are output to the console
  </ResponseField>

<ResponseField name="isTestMode" type="boolean">
    Whether to connect to stage environment. This will use stage endpoints. From **Web SDK v3.0.0+:** do not use this field to choose staging vs production; use `environment` on `SukiAuthManager` instead. Refer to [Migrating to Web SDK v3](/web-sdk/product-updates/migration-to-v3) for more details.
  </ResponseField>

<ResponseField name="theme" type="ThemeOptions" href="/web-sdk/api-reference/types/theme-options">
    The theme configuration for the SDK
  </ResponseField>
</Expandable>

**Extends**: [`PartnerDetails`](/web-sdk/api-reference/types/partner-details)

# LogLevel Type
Source: https://developer.suki.ai/web-sdk/api-reference/types/log-level

LogLevel type represents the available log levels for controlling debug output verbosity

LogLevel type represents the available log levels for controlling debug output verbosity. The code snippet below shows how to use the `LogLevel` type to create a log level object.

```js JavaScript theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
type LogLevel = "debug" | "info" | "warn" | "error" | "log";
```

## Properties

<Expandable title="properties">
  <ResponseField name="debug" type="debug">
    Log all messages including detailed debug information
  </ResponseField>

<ResponseField name="warn" type="warn">
    Log warnings and above (warn, error, log)
  </ResponseField>

<ResponseField name="info" type="info">
    Log informational messages and above (info, warn, error, log)
  </ResponseField>

<ResponseField name="error" type="error">
    Log errors and above (error, log)
  </ResponseField>

<ResponseField name="log" type="log">
    Log only explicit log messages
  </ResponseField>
</Expandable>

<Note>
  The logger respects both the `enableDebug` flag and `logLevel` setting.
  Messages are only output when debug mode is enabled AND the message level
  meets or exceeds the configured log level.
</Note>

# MountOptions Type
Source: https://developer.suki.ai/web-sdk/api-reference/types/mount-options

MountOptions type represents the configuration options for mounting the SDK to a DOM element

MountOptions type represents the configuration options for mounting the SDK to a DOM element. The code snippet below shows how to use the `MountOptions` type to create a mount options object.

```js JavaScript theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
type MountOptions = {
  rootElement: HTMLElement;
  encounter: Encounter;
  uiOptions?: UIOptions;
  ambientOptions?: AmbientOptions;
};
```

## Properties

<Expandable title="properties">
  <ResponseField name="rootElement" type="HTMLElement">
    The DOM element to mount the SDK into. Should be an empty container element
  </ResponseField>

<ResponseField name="encounter" type="Encounter" href="/web-sdk/api-reference/types/encounter">
    Full [`Encounter`](/web-sdk/api-reference/types/encounter) payload. **`patient.identifier`** is required. **`encounter.identifier`** is optional. Each value must be **at most 36 characters** (<Tooltip href="/Glossary/v#varchar-36">varchar(36)</Tooltip>) when present.
  </ResponseField>

<ResponseField name="uiOptions" type="UIOptions" href="/web-sdk/api-reference/types/ui-options">
    UI configuration options
  </ResponseField>

<ResponseField name="ambientOptions" type="AmbientOptions" href="/web-sdk/api-reference/types/ambient-options">
    Ambient session configuration options
  </ResponseField>
</Expandable>

# NoteContent Type
Source: https://developer.suki.ai/web-sdk/api-reference/types/note-content

NoteContent type represents the content structure for clinical notes

NoteContent type represents the content structure for clinical notes, including optional diagnosis and LOINC code. The code snippet below shows how to use the `NoteContent` type to create a note content object.

```js JavaScript theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
type NoteContent = {
  title: string;
  content: string;
  diagnosis?: Diagnosis;
  loinc_code?: string;
};
```

## Properties

<Expandable title="properties">
  <ResponseField name="title" type="string">
    The title of the section
  </ResponseField>

<ResponseField name="content" type="string">
    Content of the section in plain text
  </ResponseField>

<ResponseField name="diagnosis" type="Diagnosis">
    Array of clinical note sections to generate suggestions. Refer to the [Diagnosis](/web-sdk/api-reference/types/diagnosis) page for more information.
  </ResponseField>

<ResponseField name="loinc_code" type="string">
    LOINC code of the section
  </ResponseField>
</Expandable>

# PartnerDetails Type
Source: https://developer.suki.ai/web-sdk/api-reference/types/partner-details

PartnerDetails type represents the partner authentication and provider information

PartnerDetails type represents the partner authentication and provider information required for SDK initialization. The code snippet below shows how to use the `PartnerDetails` type to create a partner details object.

```js JavaScript theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
type PartnerDetails = {
  partnerId: string;
  partnerToken: string;
  providerName: string;
  providerOrgId: string;
  providerSpecialty?: string;
  providerId?: string;
};
```

## Properties

<Expandable title="properties">
  <ResponseField name="partnerId" type="string">
    The unique identifier of the partner to use when authenticating with the Suki Platform
  </ResponseField>

<ResponseField name="partnerToken" type="string">
    The idToken of the user/provider to use when authenticating with the Suki Platform
  </ResponseField>

<ResponseField name="providerName" type="string">
    The full name of the user/provider. First name, middle name, and last name separated by a space
  </ResponseField>

<ResponseField name="providerOrgId" type="string">
    The unique identifier of the organization in the partner system to which the provider belongs
  </ResponseField>

<ResponseField name="providerSpecialty" type="string">
    The specialty of the provider, if applicable. Defaults to `FAMILY_MEDICINE`
  </ResponseField>

<ResponseField name="providerId" type="string">
    The unique identifier of the provider in the partner system
  </ResponseField>
</Expandable>

# Patient Type
Source: https://developer.suki.ai/web-sdk/api-reference/types/patient

Patient type represents demographic and identification information

Patient type represents demographic and identification information. The code snippet below shows how to use the `Patient` type to create a patient object.

```js JavaScript theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
type Patient = {
  identifier: string; // max 36 characters
  kind?: string;
  name: {
    use: string;
    family: string;
    given: string[];
    suffix: string[];
  };
  birthDate: string;
  gender: "MALE" | "FEMALE" | "UNKNOWN";
};
```

## Properties

<Expandable title="properties">
  <ResponseField name="birthDate" type="string">
    **Optional** - Date of birth in YYYY-MM-DD format
  </ResponseField>

<ResponseField name="gender" type="MALE | FEMALE | UNKNOWN">
    **Optional** - Patient's gender. Use "UNKNOWN" if gender information is not available
  </ResponseField>

<ResponseField name="identifier" type="string">
    Unique identifier for the patient. Must be a string **at most 36 characters** (<Tooltip href="/Glossary/v#varchar-36">varchar(36)</Tooltip>), for example an EMR patient key.
  </ResponseField>

<ResponseField name="kind" type="string">
    Kind of patient (e.g., "human", "animal")
  </ResponseField>

<ResponseField name="name" type="object">
    Patient name information
  </ResponseField>

<ResponseField name="name.family" type="string">
    Family name (last name)
  </ResponseField>

<ResponseField name="name.given" type="string[]">
    Given names (first names)
  </ResponseField>

<ResponseField name="name.suffix" type="string[]">
    Name suffixes
  </ResponseField>

<ResponseField name="name.use" type="string">
    Use of the name (e.g., "usual", "official", "nickname")
  </ResponseField>
</Expandable>

# Section Type
Source: https://developer.suki.ai/web-sdk/api-reference/types/section

Section type represents a clinical note section using LOINC codes for ambient sessions

Section type represents a clinical note section using LOINC codes for ambient sessions. The code snippet below shows how to use the `Section` type to create a section object.

```js JavaScript theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
type Section = {
  loinc: string;
  isPBNSection?: boolean;
};
```

## Properties

<Expandable title="properties">
  <ResponseField name="loinc" type="string">
    Standard LOINC code identifying the section type
  </ResponseField>

<ResponseField name="isPBNSection" type="boolean">
    Marks this section as the single PBN (Problem-Based Note) section. Only one section may be marked as PBN. If omitted on all sections, Assessment & Plan (LOINC `51847-2`) will be used as default
  </ResponseField>
</Expandable>

# SectionEditingOptions Type
Source: https://developer.suki.ai/web-sdk/api-reference/types/section-editing-options

SectionEditingOptions type represents the configuration options for section editing features

SectionEditingOptions type represents the configuration options for section editing features within the SDK. The code snippet below shows how to use the `SectionEditingOptions` type to create a section editing options object.

```js JavaScript theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
type SectionEditingOptions = {
  enableDictation?: boolean;
  enableCopy?: boolean;
};
```

## Properties

<Expandable title="properties">
  <ResponseField name="enableDictation" type="boolean">
    Whether to enable dictation feature for the sections
  </ResponseField>

<ResponseField name="enableCopy" type="boolean">
    Whether to enable copying the section contents
  </ResponseField>
</Expandable>

# Suki Error Reference
Source: https://developer.suki.ai/web-sdk/api-reference/types/suki-error

SukiError type represents the structure for SDK errors

SukiError type represents the structure for SDK errors. The code snippet below shows how to use the `SukiError` type to create a suki error object.

```js JavaScript theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
type SukiError = {
  code: ErrorCode;
  details: ErrorDetail;
};
```

## Properties

<Expandable title="properties">
  <ResponseField name="code" type="ErrorCode" href="/web-sdk/api-reference/types/suki-error#errorcode-identifier">
    Unique error code identifier
  </ResponseField>

<ResponseField name="details" type="ErrorDetail" href="/web-sdk/api-reference/types/suki-error#errordetail">
    Detailed error information including name, message, and reason
  </ResponseField>
</Expandable>

## ErrorCode identifier

ErrorCode represents the unique identifiers for different types of SDK errors. The following table lists the available error code identifiers and their descriptions.

| Code       | Name                      | Category       | Description                                          |
| ---------- | ------------------------- | -------------- | ---------------------------------------------------- |
| `SUKI0001` | init:sdk-init-failed      | Initialization | SDK initialization failed                            |
| `SUKI0002` | init:auth-failed          | Authentication | User authentication failed                           |
| `SUKI0003` | init:mount-failed         | Initialization | SDK mounting to DOM failed                           |
| `SUKI0004` | init:messenger-failed     | Initialization | Internal messaging system failed                     |
| `SUKI0005` | init:invalid-options      | Initialization | Invalid initialization options provided              |
| `SUKI0006` | navigate:failed           | Navigation     | Navigation within SDK failed                         |
| `SUKI0007` | create-appointment:failed | Encounter      | Failed to create appointment/encounter               |
| `SUKI0008` | get-appointment:failed    | Encounter      | Failed to retrieve appointment/encounter             |
| `SUKI0009` | create-patient:failed     | Patient        | Failed to create patient record                      |
| `SUKI0010` | update-patient:failed     | Patient        | Failed to update patient information                 |
| `SUKI0011` | get-patient:failed        | Patient        | Failed to retrieve patient information               |
| `SUKI0012` | note-submission:failed    | Notes          | Failed to submit clinical note                       |
| `SUKI0013` | ambient-fail              | Ambient        | Ambient session operation failed                     |
| `SUKI0014` | encounter-fail            | Encounter      | General encounter operation failed                   |
| `SUKI0015` | token-update-fail         | Authentication | Failed to update partner token                       |
| `SUKI0016` | unsupported-loinc-codes   | Configuration  | Provided LOINC codes are not supported               |
| `SUKI0017` | no-supported-loinc-codes  | Configuration  | No supported LOINC codes found in configuration      |
| `SUKI0018` | multiple-pbn-sections     | Configuration  | Multiple sections marked as PBN (Problem-Based Note) |

## ErrorDetail

ErrorDetail represents the detailed information about a specific error. The code snippet below shows how to use the `ErrorDetail` type to create an error detail object.

```js JavaScript theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
type ErrorDetail = {
  name: `init:sdk-init-failed` | `init:auth-failed` ...;
  message: string;
  reason?: ErrorReasons;
}
```

### ErrorDetail properties

<Expandable title="properties">
  <ResponseField name="name" type="string">
    Unique name for the error (corresponds to error code)
  </ResponseField>

<ResponseField name="message" type="string">
    Human-readable description of the error
  </ResponseField>

<ResponseField name="reason" type="ErrorReasons" href="/web-sdk/api-reference/types/suki-error#errorreasons">
    Additional context about why the error occurred
  </ResponseField>
</Expandable>

## ErrorReasons

ErrorReasons represents the specific reasons that provide additional context for why an error occurred.

```js JavaScript theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
type ErrorReasons =
  | "lib-error"
  | "no-init"
  | "no-partner-token"
  | "missing-partner-details"
  | "no-init-or-auth"
  | "service-error"
  | "already-started"
  | "no-ambient"
  | "ambient-in-progress"
  | "invalid-encounter"
  | "unsupported-loinc-codes"
  | "no-supported-loinc-codes"
  | "multiple-pbn-sections";
```

The below table lists the available error reasons and their descriptions.

| Reason                       | Category       | Description                                                                                                                                                    |
| ---------------------------- | -------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **already-started**          | State          | Operation attempted when already in progress                                                                                                                   |
| **ambient-in-progress**      | Ambient        | Cannot perform action while ambient session is active                                                                                                          |
| **invalid-encounter**        | Data           | Encounter data is invalid or malformed (for example **`patient.identifier`** or **`encounter.identifier`** longer than **36 characters** or otherwise invalid) |
| **lib-error**                | System         | Internal library or system error                                                                                                                               |
| **missing-partner-details**  | Configuration  | Required partner authentication details are missing                                                                                                            |
| **multiple-pbn-sections**    | Configuration  | Multiple sections marked as PBN when only one is allowed                                                                                                       |
| **no-ambient**               | State          | No ambient session available for operation                                                                                                                     |
| **no-init**                  | State          | SDK not initialized before operation attempted                                                                                                                 |
| **no-init-or-auth**          | Authentication | SDK not initialized or user not authenticated                                                                                                                  |
| **no-partner-token**         | Authentication | Partner token is missing or invalid                                                                                                                            |
| **no-supported-loinc-codes** | Configuration  | No supported LOINC codes found                                                                                                                                 |
| **service-error**            | Network        | External service or API error                                                                                                                                  |
| **unsupported-loinc-codes**  | Configuration  | Provided LOINC codes are not supported                                                                                                                         |

## Example

```js JavaScript theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
const error = {
  code: "SUKI0001",
  details: {
    name: "init:sdk-init-failed",
    message: "SDK initialization failed",
    reason: "lib-error"
  }
};
```

# ThemeOptions Type
Source: https://developer.suki.ai/web-sdk/api-reference/types/theme-options

ThemeOptions type represents the configuration options for customizing the SDK appearance

ThemeOptions type represents the configuration options for customizing the Web SDK appearance. The code snippet below shows how to use the `ThemeOptions` type to create a theme options object.

```js JavaScript theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
type ThemeOptions = {
  primary?: string;
  background?: string;
  secondaryBackground?: string;
  foreground?: string;
  warning?: string;
};
```

## Properties

<Expandable title="properties">
  <ResponseField name="primary" type="string">
    The primary color of the theme in rgb
  </ResponseField>

<ResponseField name="background" type="string">
    The primary background color of the theme in rgb
  </ResponseField>

<ResponseField name="secondaryBackground" type="string">
    The secondary background color of the theme in rgb
  </ResponseField>

<ResponseField name="foreground" type="string">
    The foreground/text color of the theme in rgb
  </ResponseField>

<ResponseField name="warning" type="string">
    The warning color used for alerts and notifications in rgb
  </ResponseField>
</Expandable>

<Note>
  The `ThemeOptions` type is optional and will default to the Suki brand colors if not provided.
</Note>

# UIOptions Type
Source: https://developer.suki.ai/web-sdk/api-reference/types/ui-options

UIOptions type represents the user interface configuration options for the SDK

UIOptions type represents the user interface configuration options for the SDK. The code snippet below shows how to use the `UIOptions` type to create a ui options object.

```js JavaScript theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
type UIOptions = {
  showCloseButton?: boolean;
  showCreateEmptyNoteButton?: boolean;
  sectionEditing?: SectionEditingOptions;
  showStartAmbientButton?: boolean;
};
```

## Properties

<Expandable title="properties">
  <ResponseField name="showCloseButton" type="boolean">
    Whether to show the close button in the SDK header
  </ResponseField>

<ResponseField name="showCreateEmptyNoteButton" type="boolean">
    Whether to show the create empty note button in the patient profile
  </ResponseField>

<ResponseField name="sectionEditing" type="SectionEditingOptions" href="/web-sdk/api-reference/types/section-editing-options">
    Configuration for section editing features. Defaults to all enabled.
  </ResponseField>

<ResponseField name="showStartAmbientButton" type="boolean">
    Whether to show the start ambient button in the patient profile
  </ResponseField>
</Expandable>

# Web SDK For Audio Dictation
Source: https://developer.suki.ai/web-sdk/dictation-overview

Overview of audio dictation in the Suki Web SDK for JavaScript and React applications

<span>Quick summary</span>
  </div>

<div>
    This section walks you through the process of integrating audio dictation using the Suki Web SDK in a browser-based JavaScript or React application. You will use the packages provided by Suki Web SDK to complete the integration.
  </div>

<span>Last updated:</span>
    <span>April 2026</span>
  </div>
</div>

This section walks you through the process of integrating audio dictation using the Suki Web SDK in a browser-based JavaScript or React application. You will use the packages provided by Suki to complete the integration.

To implement dictation, you must create a `SukiAuthManager` and a `DictationClient`.

In a **React application**, you wrap your component tree with the `DictationProvider`. You then render the `Dictation` component when you want the user to dictate. In a **JavaScript application**, you call `await dictationClient.show({ ... })` when the user is ready to begin dictation.

## Prerequisites

Before you begin, meet the necessary requirements in [Web SDK prerequisites](/web-sdk/prerequisites) and obtain `partnerId` and `partnerToken` after [Partner onboarding](/documentation/partner-onboarding).

## Integration guides

Choose the integration guide for your stack:

<CardGroup>
  <Card title="JavaScript" icon="js" href="/web-sdk/guides/dictation-javascript">
    Use the JavaScript package provided by Suki Web SDK to integrate audio dictation in a JavaScript application (browser-based).
  </Card>

<Card title="React" icon="react" href="/web-sdk/guides/dictation-react">
    Use the React package provided by Suki Web SDK to integrate audio dictation in a React application (browser-based).
  </Card>
</CardGroup>

For options such as **`mode`**, **`fieldId`**, and callbacks, refer to [Configuration](/dictation-sdk/guides/configuration) guide in the Dictation SDK section.

# Advanced Configuration
Source: https://developer.suki.ai/web-sdk/examples/advanced-configuration

Learn to use the advanced JavaScript and React Web SDK configuration options and customization features

Customize the Suki Assistant Web SDK to fit your application's specific needs. This example covers the complete setup, including the **root provider**, **dynamic props**, **UI customization**, and **event handling**, as shown in the comprehensive example.

## Configurations

### Wrapping your application

Wrapping your application with the `SukiProvider` component is the first step in configuring the Suki Assistant Web SDK. This is necessary for the SDK and its hooks to function correctly.

<CodeGroup>
  ```jsx JavaScript theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
  import { SukiProvider } from "@suki-sdk/react";

// This is the root of your application
  function Root() { 
    return (
      <SukiProvider>
        <App />
      </SukiProvider>
    );
  }
  ```
</CodeGroup>

### Initializing the SDK

Before you can use advanced features, you must **initialize the SDK** inside the `SukiProvider` context.

Use `SukiAuthManager` from `@suki-sdk/core` for partner token and provider fields, then call `init` from `useSuki` **once** when your application loads (typically inside a `useEffect`), passing `authManager` on the options object. See [Migrating to Web SDK v3](/web-sdk/product-updates/migration-to-v3).

<CodeGroup>
  ```jsx JavaScript expandable theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}

import { useEffect, useMemo } from "react";
  import { SukiAuthManager } from "@suki-sdk/core";
  import { SukiProvider, useSuki } from "@suki-sdk/react";

function App() {
    const authManager = useMemo(
      () =>
        new SukiAuthManager({
          partnerId: "f80c8db8-a4d0-4b75-8d63-56c82b5413f0", // Replace with your partner ID
          partnerToken: "YOUR_JWT_HERE", // Replace with your partner token
          providerName: "John Doe", // Replace with your provider's name
          providerOrgId: "1234", // Replace with your provider's organization ID
          providerId: "1234567890", // Replace with the provider's ID
          providerSpecialty: "FAMILY_MEDICINE", // Replace with the provider's specialty
          environment: "production",
          loginOnInitialize: true,
        }),
      [],
    );

const { init, isInitialized } = useSuki();

useEffect(() => {
      if (!isInitialized) {
        init({
          authManager,
          theme: {
            primary: "#0066cc", // Replace with your primary color
            background: "#ffffff", // Replace with your background color
          },
        });
      }
    }, [init, isInitialized, authManager]);

// ... rest of the application
  }
  ```
</CodeGroup>

### Configure the SukiAssistant component

The `<SukiAssistant />` component is the main UI for the SDK. Configure its behavior and appearance by passing it the following props.

#### Handling dynamic encounters

The `encounter` prop is the most important piece of contextual information.

The example below demonstrates how to dynamically change this prop to load different patient encounters into the SDK.

<CodeGroup>
  ```jsx JavaScript expandable theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
  import { useState } from "react";

// In your main App component...
  const [encounter, setEncounter] = useState(encounters[0]); // encounters is your array of data

return (
    <>
      {/* Buttons to demonstrate switching the encounter context */}
      <button onClick={() => setEncounter(encounters[0])}>
        Load Encounter 1
      </button>
      <button onClick={() => setEncounter(encounters[1])}>
        Load Encounter 2
      </button>

{/* Pass the currently selected encounter to the component */}
      <SukiAssistant encounter={encounter} {...otherProps} />
    </>
  );
  ```
</CodeGroup>

#### Ambient and UI options

The `ambientOptions` and `uiOptions` props are used to configure the ambient session and the user interface of the SDK.

<Accordion title="Ambient Prop" icon="microphone">
  `ambientOptions`: Configures the note-generation session.

<ResponseField name="sections" type="Array">
    An array of objects that defines the clinical sections for note generation, identified by [LOINC codes](/documentation/note-sections).

<Expandable title="properties">
      <ResponseField name="loinc" type="string">
        The LOINC code for the clinical section.
      </ResponseField>

<ResponseField name="isPBNSection" type="boolean">
        A boolean that indicates if the section should be treated as a Problem-Based Noting section.
      </ResponseField>
    </Expandable>
  </ResponseField>

<ResponseField name="diagnoses" type="object">
    **Optional.** Use this when you have Problem-Based Charting (PBC) enabled. Pass the patient's existing diagnoses (e.g. from the EMR) so the session can merge them with what's discussed during the visit and avoid duplicate problems in the note.

Each item in <code>values</code> is one diagnosis: give it a single <code>code</code> (ICD10 only for now) and optionally a <code>description</code> or <code>diagnosis\_note</code>. Refer to the [Existing patient diagnoses](/web-sdk/guides/ambient-problem-based-charting#existing-patient-diagnoses) guide for more details.
  </ResponseField>

<CodeGroup>
    ```jsx JavaScript theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
    const ambientOptions = {
      sections: [
        {
          loinc: "51847-2", // Assessment and Plan
          isPBNSection: true,
        },
        {
          loinc: "10164-2", // History of Present Illness
        },
        {
          loinc: "10187-3", // Review of Systems
        },
      ],
      diagnoses: { // [!code ++:14] New in v2.1.2
        values: [
          {
            codes: [
              {
                code: "I10",
                description: "Essential hypertension",
                type: "ICD10",
              },
            ],
            diagnosisNote: "Hypertension",
          },
        ],
      },
    };
    ```
  </CodeGroup>
</Accordion>

<Accordion title="UI Prop" icon="eye">
  `uiOptions`: Controls the visibility and functionality of UI elements like the **close button** or editing features within note sections.

<ResponseField name="showCloseButton" type="boolean">
    Controls visibility of the close button in the header.
  </ResponseField>

<ResponseField name="showCreateEmptyNoteButton" type="boolean">
    Controls visibility of the create empty note button in the patient profile.
  </ResponseField>

<ResponseField name="showStartAmbientButton" type="boolean">
    Controls visibility of the start ambient button in the patient profile.
  </ResponseField>

<ResponseField name="sectionEditing" type="object">
    Controls the visibility and functionality of editing features within note sections.

<Expandable title="properties">
      <ResponseField name="enableDictation" type="boolean">
        **(Default: true)** Enables or disables the dictation (microphone) icon for editing text.
      </ResponseField>

<ResponseField name="enableCopy" type="boolean">
        **(Default: false)** Enables or disables the copy-to-clipboard icon for section content.
      </ResponseField>
    </Expandable>
  </ResponseField>

<CodeGroup>
    ```jsx JavaScript theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
    const uiOptions = {
      showCloseButton: true,
      showStartAmbientButton: true,
      showCreateEmptyNoteButton: false,
      sectionEditing: {
        enableDictation: true,
        enableCopy: false,
      },
    };
    ```
  </CodeGroup>
</Accordion>

#### Event handlers

Listen for key events from the SDK by providing `callback` functions as props. This allows your application to react when a user takes an action.

* `onNoteSubmit`: This function is called when a note is successfully generated and submitted. It receives an object containing the `noteId` and the `contents` of the note.

* `onClose`: This function is called when the user clicks the close button in the UI.

## Complete example

This example ties all the concepts together, showing the `SukiProvider`, `SukiAssistant`, `useSuki` hook, dynamic encounters, and all configuration props in a single, working component structure.

<CodeGroup>
  ```jsx JavaScript expandable theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
  import React, { useEffect, useMemo, useState } from "react";
  import { SukiAuthManager } from "@suki-sdk/core";
  import { SukiAssistant, SukiProvider, useSuki } from "@suki-sdk/react";

// Mock data for demonstration
  const encounters = [
    {
      identifier: "6ec3920f-b0b1-499d-a4e9-889bf788e5ab",
      patient: {
        identifier: "905c2521-25eb-4324-9978-724636df3436",
        name: { family: "Smith", given: ["John"] },
        birthDate: "1980-01-15",
        gender: "male",
      },
    },
    {
      identifier: "qsc2393g-b0b1-499d-a4e9-983cq125g5op",
      patient: {
        identifier: "25eb905-1232-082132-aw12320do4r",
        name: { family: "Johnson", given: ["Sarah"] },
        birthDate: "1985-03-20",
        gender: "female",
      },
    },
  ];

// 1. SukiProvider must wrap the root of your application
  function Root() {
    return (
      <SukiProvider>
        <App />
      </SukiProvider>
    );
  }

// 2. The main application component handles initialization and state
  function App() {
    const authManager = useMemo(
      () =>
        new SukiAuthManager({
          partnerId: "f80c8db8-a4d0-4b75-8d63-56c82b5413f0", // Replace with your actual partner ID
          partnerToken: "YOUR_JWT_HERE", // Replace with your actual partner token
          providerName: "John doe",
          providerOrgId: "1234",
          providerId: "1234567890", // Replace with the provider's ID
          providerSpecialty: "FAMILY_MEDICINE", // Replace with the provider's specialty
          environment: "production",
          loginOnInitialize: true,
        }),
      [],
    );

const { init, isInitialized } = useSuki();
    const [encounter, setEncounter] = useState(encounters[0]);

useEffect(() => {
      if (!isInitialized) {
        init({
          authManager,
          theme: {
            primary: "#0066cc",
            background: "#ffffff",
          },
        });
      }
    }, [init, isInitialized, authManager]);

// Define ambient options for note generation
    const ambientOptions = {
      sections: [
        { loinc: "51847-2", isPBNSection: true }, // Assessment and Plan
        { loinc: "10164-2" }, // History of Present Illness
        { loinc: "10187-3" }, // Review of Systems
      ],
      diagnoses: { // [!code ++:14] New in v2.1.2
        values: [
          {
            codes: [
              {
                code: "I10",
                description: "Essential hypertension",
                type: "ICD10",
              },
            ],
            diagnosisNote: "Hypertension",
          },
        ],
      },
    };

return (
      <>
        <h3>Select an Encounter:</h3>
        <button onClick={() => setEncounter(encounters[0])}>
          Load John Smith
        </button>
        <button onClick={() => setEncounter(encounters[1])}>
          Load Sarah Johnson
        </button>
        <hr />
        <AdvancedSDKComponent
          encounter={encounter}
          ambientOptions={ambientOptions}
        />
      </>
    );
  }

// 3. This component renders and manages the SukiAssistant UI
  function AdvancedSDKComponent({ encounter, ambientOptions }) {
    const [isVisible, setIsVisible] = useState(true);

// Define UI options to customize the interface
    const uiOptions = {
      showCloseButton: true,
      showStartAmbientButton: true,
      showCreateEmptyNoteButton: false,
      sectionEditing: {
        enableDictation: true,
        enableCopy: false,
      },
    };

// Define event handlers to react to SDK events
    const handleNoteSubmit = (data) => {
      console.log("Note submitted successfully:", data.noteId);
      data.contents.forEach((section) => {
        console.log(`- ${section.title}: ${section.content}`);
      });
    };

const handleClose = () => {
      setIsVisible(false);
      console.log("SDK closed by user");
    };

if (!isVisible) {
      return <div>SDK has been closed.</div>;
    }

return (
      <SukiAssistant
        encounter={encounter}
        uiOptions={uiOptions}
        ambientOptions={ambientOptions}
        onNoteSubmit={handleNoteSubmit}
        onClose={handleClose}
      />
    );
  }

```
</CodeGroup>

## Next steps

<Icon icon="file-lines" /> Read the [Theming and customization](/web-sdk/examples/theming-and-customization) example to learn how to customize the UI of the SDK.

# Ambient Events
Source: https://developer.suki.ai/web-sdk/examples/ambient-events

Learn how to use ambient events in the Suki React Web SDK to track and manage ambient interactions

The Web SDK emits events when the ambient session state changes. Listen for these events to track the state of the ambient session and handle responses accordingly.

For more information, refer to the [Emitter-events-type](/web-sdk/api-reference/types/emitter-events) section.

## Code example

The example below demonstrates how to listen for ambient events in the web SDK.

```jsx React expandable theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
import { SukiAssistant, SukiProvider, useSuki } from "@suki-sdk/react";

function MyComponent() {
  const { on, activeAmbientId } = useSuki();

useEffect(() => {
    const handleAmbientUpdate = (event) => {
      console.log("Ambient event received:", event);
    };

// Subscribe to ambient update events
    const unsubscribe = on("ambient-update", handleAmbientUpdate);

// Cleanup subscription on unmount
    return () => {
      unsubscribe();
    };
  }, [on]);

return (
    <>
      Active Ambient ID: {activeAmbientId}
      <SukiAssistant
      // props
      />
    </>
  );
}
```

## Next steps

<Icon icon="file-lines" /> Refer to the [Test mode](/web-sdk/examples/test-mode) example to learn how to use the test mode in the web SDK.

# Basic Usage
Source: https://developer.suki.ai/web-sdk/examples/basic-usage

Learn how to integrate the Suki React Web SDK into your application

This guide walks you through the basic usage of the Suki React Web SDK in your application.

## Code example for React Web SDK

This example below covers the complete setup, including the **root provider**, **dynamic props**, **UI customization**, and **event handling**.

```jsx React expandable theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
import { useEffect, useMemo } from "react";
import { SukiAuthManager } from "@suki-sdk/core";
import { SukiAssistant, SukiProvider, useSuki } from "@suki-sdk/react";

function Root() {
  return (
    <SukiProvider>
      <App />
    </SukiProvider>
  );
}

function App() {
  const authManager = useMemo(
    () =>
      new SukiAuthManager({
        partnerId: "f80c8db8-a4d0-4b75-8d63-56c82b5413f0", // Replace with your actual partner ID
        partnerToken:
          "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiYWRtaW4iOnRydWUsImlhdCI6MTUxNjIzOTAyMn0.KMUFsIDTnFmyG3nMiGM6H9FNFUROf3wh7SmqJp-QV30", // Replace with your actual partner token
        providerName: "John doe", // Replace with the full name of the provider
        providerOrgId: "1234", // Replace with the provider's organization ID
        environment: "production",
        loginOnInitialize: true,
        providerId: "1234567890", // Replace with the provider's ID
        providerName: "John doe", // Replace with the full name of the provider
        providerOrgId: "1234", // Replace with the provider's organization ID
        providerSpecialty: "FAMILY_MEDICINE", // Replace with the provider's specialty
      }),
    [],
  );

const { init, isInitialized } = useSuki();

useEffect(() => {
    if (!isInitialized) {
      init({ authManager });
    }
  }, [init, isInitialized, authManager]);

const encounter = {
    identifier: "6ec3920f-b0b1-499d-a4e9-889bf788e5ab",
    patient: {
      identifier: "905c2521-25eb-4324-9978-724636df3436",
      name: {
        use: "usual",
        family: "Smith",
        given: ["John"],
        suffix: [],
      },
      birthDate: "1980-01-15",
      gender: "male",
    },
  };

return <MySDKComponent encounter={encounter} />;
}

const ambientOptions = {
    sections: [
      {
        loinc: "51847-2", // Assessment and Plan
        isPBNSection: true,
      },
      {
        loinc: "10164-2", // History of Present Illness
      },
      {
        loinc: "10187-3", // Review of Systems
      },
    ],
    diagnoses: { // [!code ++:14] New in v2.1.2
      values: [
        {
          codes: [
            {
              code: "I10",
              description: "Essential hypertension",
              type: "ICD10",
            },
          ],
          diagnosisNote: "Hypertension",
        },
      ],
    },
    visitType: "ESTABLISHED_PATIENT", // [!code ++:6] New in v2.2.0
    encounterType: "AMBULATORY",
    providerRole: "PRIMARY/ATTENDING",
    reasonForVisit: "Follow-up for hypertension",
    chiefComplaint: "Headache",
  };

return (
    <SukiAssistant
      encounter={encounter}
      onNoteSubmit={handleNoteSubmit}
      ambientOptions={ambientOptions}
    />
  );
}
```

## Next steps

<Icon icon="file-lines" /> Read the [Control visibility](/web-sdk/examples/control-visibility) example to learn how to control the visibility of the SDK.

# Control Visibility
Source: https://developer.suki.ai/web-sdk/examples/control-visibility

Learn how to control visibility of the Suki React Web SDK using the embedded close button.

This guide walks you through the process of controlling the visibility of the Suki React Web SDK using the embedded close button.

Control the visibility of the Suki React Web SDK using the embedded close button. Use this when you want to show or hide the SDK from your application.

## Code example for React Web SDK

The following examples demonstrate how to control the visibility of the SDK using the `showCloseButton` prop.

<Tabs>
  <Tab title="With Close Button">
    This example shows how to control the visibility of the web SDK using the `showCloseButton` prop. When the `showCloseButton` is set to `true`, the close button is visible and the `onClose` prop is available.

```jsx React expandable theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
    import { useEffect, useMemo, useState } from "react";
    import { SukiAuthManager } from "@suki-sdk/core";
    import { SukiAssistant, SukiProvider, useSuki } from "@suki-sdk/react";

function ComponentWithCloseButton() {
    const authManager = useMemo(
    () =>
      new SukiAuthManager({
        partnerId: "f80c8db8-a4d0-4b75-8d63-56c82b5413f0", // Replace with your actual partner ID
        partnerToken:
          "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiYWRtaW4iOnRydWUsImlhdCI6MTUxNjIzOTAyMn0.KMUFsIDTnFmyG3nMiGM6H9FNFUROf3wh7SmqJp-QV30", // Replace with your actual partner token
        providerName: "John doe", // Replace with the full name of the provider
        providerOrgId: "1234", // Replace with the provider's organization ID
        environment: "production",
        loginOnInitialize: true,
        providerId: "1234567890", // Replace with the provider's ID
        providerName: "John doe", // Replace with the full name of the provider
        providerOrgId: "1234", // Replace with the provider's organization ID
        providerSpecialty: "FAMILY_MEDICINE", // Replace with the provider's specialty
      }),
    [],
    );

const { init, isInitialized } = useSuki();
    const [isVisible, setIsVisible] = useState(true);

useEffect(() => {
    if (!isInitialized) {
      init({ authManager });
    }
    }, [init, isInitialized, authManager]);

const encounter = {
    identifier: "encounter-789",
    patient: {
      identifier: "patient-101",
      name: {
        use: "usual",
        family: "Johnson",
        given: ["Sarah", "Marie"],
        suffix: ["MD"],
      },
      birthDate: "1985-03-20",
      gender: "female",
    },
    };

const uiOptions = { showCloseButton: true };

const handleClose = () => {
    setIsVisible(false);
    console.log("SDK closed by user");
    };

if (!isVisible) {
    return <div>SDK has been closed</div>;
    }

return (
    <SukiAssistant
      encounter={encounter}
      uiOptions={uiOptions}
      ambientOptions={ambientOptions}
      onClose={handleClose}
      onNoteSubmit={(data) => {
        console.log(data);
      }}
    />
    );
    }
    ```
  </Tab>

<Tab title="Without Close Button">
    This example shows how to control the visibility of the web SDK using the `onClose` prop. When the `showCloseButton` is set to `false`, the `onClose` prop is not available.

```jsx React theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
    // When showCloseButton is false, onClose is not available
    function ComponentWithoutCloseButton() {
    const uiOptions = {
    showCloseButton: false,
    };

return (
    <SukiAssistant
      encounter={encounter}
      uiOptions={uiOptions}
      onNoteSubmit={(data) => {
        console.log(data);
      }}
      // onClose={handleClose} // TypeScript error: Property 'onClose' does not exist
      // rest of the props
    />
    );
    }
    ```
  </Tab>
</Tabs>

## Next steps

<Icon icon="file-lines" /> Read the [Dynamic encounter](/web-sdk/examples/dynamic-encounter) example to learn how to dynamically update the encounter data in the web SDK.

# Dynamic Encounter
Source: https://developer.suki.ai/web-sdk/examples/dynamic-encounter

Learn how to dynamically set the encounter data in the Suki React Web SDK

Encounter data contains patient and provider information. You pass it to the `SukiAssistant` component to pre-populate the React Web SDK.

**Identifiers:**

* **`patient.identifier`** is required and must be **at most 36 characters** (<Tooltip href="/Glossary/v#varchar-36">varchar(36)</Tooltip>).
* **`encounter.identifier`** is optional; if you set it, use the same **36-character** limit (<Tooltip href="/Glossary/v#varchar-36">varchar(36)</Tooltip>).

**Dynamic encounter:**

You can update the **`encounter`** prop after the component loads. When you pass new encounter data, the Web SDK updates it automatically for note generation.

## Code example for React Web SDK

The example below demonstrates how to change encounter data using React state:

<CodeGroup>
  ```jsx React expandable theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
  import { SukiAssistant, SukiProvider, useSuki } from "@suki-sdk/react";

function DynamicEncounterComponent() {
    const [currentEncounter, setCurrentEncounter] = useState(initialEncounter); // Replace with your initial encounter data

const switchToNewPatient = () => {
      const newEncounter = {
        identifier: "6ec3920f-b0b1-499d-a4e9-889bf788e5ab", // max 36 characters
        patient: {
          identifier: "905c2521-25eb-4324-9978-724636df3436", // max 36 characters
          name: {
            use: "usual",
            family: "Wilson",
            given: ["Emma"],
            suffix: [],
          },
          birthDate: "1992-07-10",
          gender: "female",
        },
      };

setCurrentEncounter(newEncounter);
    };

return (
      <SukiProvider>
        <div>
          <button onClick={switchToNewPatient}>Switch to New Patient</button>

## Next steps

<Icon icon="file-lines" /> Refer to [Ambient events](/web-sdk/guides/ambient) to learn more about how to track and manage ambient interactions in the web SDK.

# Test Mode
Source: https://developer.suki.ai/web-sdk/examples/test-mode

Learn how to use Suki React Web SDK in test mode for development and testing purposes before going live

For development and testing against Suki staging infrastructure, Web SDK v3 uses `environment: "staging"` on `SukiAuthManager` (not `isTestMode` on `init`). This page shows a React example; the same `SukiAuthManager` settings work with `initialize()` in JavaScript.

## Code example

The example below points the SDK at staging and turns on debug logging.

```jsx React expandable theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
import { useEffect, useMemo } from "react";
import { SukiAuthManager } from "@suki-sdk/core";
import { SukiAssistant, SukiProvider, useSuki } from "@suki-sdk/react";

function Root() {
  return (
    <SukiProvider>
      <App />
    </SukiProvider>
  );
}

function App() {
  const authManager = useMemo(
    () =>
      new SukiAuthManager({
        partnerId: "f80c8db8-a4d0-4b75-8d63-56c82b5413f0", // Replace with your actual partner ID
        partnerToken:
          "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiYWRtaW4iOnRydWUsImlhdCI6MTUxNjIzOTAyMn0.KMUFsIDTnFmyG3nMiGM6H9FNFUROf3wh7SmqJp-QV30", // Replace with your actual partner token
        providerName: "John doe", // Replace with the full name of the provider
        providerOrgId: "1234", // Replace with the provider's organization ID
        environment: "staging",
        loginOnInitialize: true,
        providerId: "1234567890", // Replace with the provider's ID
        providerName: "John doe", // Replace with the full name of the provider
        providerOrgId: "1234", // Replace with the provider's organization ID
        providerSpecialty: "FAMILY_MEDICINE", // Replace with the provider's specialty
      }),
    [],
  );

const { init, isInitialized } = useSuki();

useEffect(() => {
    if (!isInitialized) {
      init({
        authManager,
        enableDebug: true,
        logLevel: "debug",
      });
    }
  }, [init, isInitialized, authManager]);

return <MySDKComponent encounter={encounter} />;
}

function MySDKComponent({ encounter }) {
  const handleNoteSubmit = (data) => {
    console.log("Note submitted:", data);
  };

return (
    <SukiAssistant
      encounter={encounter}
      onNoteSubmit={handleNoteSubmit}
      // rest of the props as needed
    />
  );
}
```

<Note>
  **Web SDK v2** used `isTestMode: true` on `init` options for the same idea. **Web SDK v3** uses `environment` on `SukiAuthManager` instead. See [Migrating to Web SDK v3](/web-sdk/product-updates/migration-to-v3) and [InitOptions](/web-sdk/api-reference/types/init-options).
</Note>

## Next steps

<Icon icon="file-lines" /> Refer to the [SDK inside an iframe](/web-sdk/examples/using-inside-iframe) example to learn how to use the web SDK inside an iframe.

# Theming and Customization
Source: https://developer.suki.ai/web-sdk/examples/theming-and-customization

Learn how to theme the Suki React SDK to match your application's design.

Customize the Suki Web SDK to match your application's design. This gives you full control over the look and feel of the SDK, including the colors, fonts, and overall design.

## Code example

This example below covers the complete setup, including the **root provider**, **dynamic props**, **UI customization**, and **event handling**.

<Note>
  Theme colors are optional and will default to the Suki brand colors if not provided.
</Note>

```jsx JavaScript expandable theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
import { useEffect, useMemo } from "react";
import { SukiAuthManager } from "@suki-sdk/core";
import { SukiAssistant, SukiProvider, useSuki } from "@suki-sdk/react";

function Root() {
  return (
    <SukiProvider>
      <App />
    </SukiProvider>
  );
}

function App() {
  const authManager = useMemo(
    () =>
      new SukiAuthManager({
        partnerId: "f80c8db8-a4d0-4b75-8d63-56c82b5413f0", // Replace with your actual partner ID
        partnerToken:
          "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiYWRtaW4iOnRydWUsImlhdCI6MTUxNjIzOTAyMn0.KMUFsIDTnFmyG3nMiGM6H9FNFUROf3wh7SmqJp-QV30", // Replace with your actual partner token
        providerName: "John doe", // Replace with the full name of the provider
        providerOrgId: "1234", // Replace with the provider's organization ID
        providerId: "1234567890", // Replace with the provider's ID
        providerSpecialty: "FAMILY_MEDICINE", // Replace with the provider's specialty
        environment: "production",
        loginOnInitialize: true,
      }),
    [],
  );

const { init, isInitialized } = useSuki();

useEffect(() => {
    if (!isInitialized) {
      init({
        authManager,
        theme: {
          primary: rgb(28, 28, 28), // just an example, replace with your primary color
          background: rgb(255, 255, 255), // Replace with your background color
          secondaryBackground: rgb(233, 233, 240), // Replace with your secondary background color
          foreground: rgb(0, 0, 0), // Replace with your foreground color
          warning: rgb(255, 184, 0), // Replace with your warning color
        },
      });
    }
  }, [init, isInitialized, authManager]);

return <MySDKComponent  />;
}

function MySDKComponent() {
  const handleNoteSubmit = (data) => {
    console.log("Note submitted:", data);
  };

const uiOptions = {
    showCloseButton: false,
    showCreateEmptyNoteButton: false,
    showStartAmbientButton: true,
    sectionEditing: {
      enableDictation: false,
      enableCopy: true,
    }
  }

return (
    <SukiAssistant
      encounter={encounter}
      onNoteSubmit={handleNoteSubmit}
      uiOptions={uiOptions}
      // rest of the props as needed
    />
  );
}
```

# Use Suki SDK Inside an Iframe
Source: https://developer.suki.ai/web-sdk/examples/using-inside-iframe

Learn how to use the Suki Web SDK inside an iframe.

Embed the Suki Web SDK in your web application by using an iframe. For the SDK to function correctly, grant the iframe specific permissions to access the microphone and clipboard.

### Granting required permissions

* **Microphone access** is required for ambient note capture and dictation.

* **Clipboard access** is required for the copy-to-clipboard functionality in note sections.

To enable these features, add the `allow` attribute to your `<iframe>` element with the necessary permission values.

<Note>
  Modern browsers restrict access to sensitive APIs like the microphone from within an iframe for security reasons. If you do not explicitly grant permission, core SDK features will fail.
</Note>

<CodeGroup>
  ```html HTML theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
  <iframe
    src="https://your-app-url.com"
    allow="microphone; clipboard-write; clipboard-read"
  >
    
  </iframe>
  ```
</CodeGroup>

## Next steps

<Icon icon="file-lines" /> Read the [Advanced configuration](/web-sdk/examples/advanced-configuration) example to learn how to configure the Suki SDK.

# Automatic User Onboarding
Source: https://developer.suki.ai/web-sdk/faqs/auto-onboarding

Questions about automatic user registration and onboarding with Web SDK

Starting from version 2.0.0, the Suki SDK includes an **auto onboarding** feature to simplify the initial setup for new users. The SDK automatically creates a provider account the first time a new user interacts with it, eliminating the need for manual setup.

## How auto onboarding works

When the SDK is mounted, it uses the `patient.identifier` to check if a provider already exists in the Suki system:

* If the provider **does not exist**, the SDK will automatically create one.
* If the provider **already exists**, the SDK will use the existing provider data.

This behavior also extends to **new organizations**. If the specified organization does not exist, it will be created automatically using the `providerOrgId` provided during SDK initialization.

<Note>
  To support auto onboarding of organizations, ensure that the `providerOrgId`
  is always provided during SDK initialization.
</Note>

# General
Source: https://developer.suki.ai/web-sdk/faqs/general

General questions about Web SDK features, capabilities, and browser compatibility

<Accordion title="What is the Suki SDK?">
  Suki Software Development Kit (SDK) enables developers to embed Suki's voice
  AI capabilities directly into their application. Healthcare solutions
  including electronic health records (EHRs), healthcare overlay applications
  such as ACOs, medical devices, and more can now easily incorporate AI voice
  features directly into their offerings.

The Suki SDK comes with an out-of-the-box UI component that automatically manages the user state and
  error handling, providing a seamless user experience without requiring explicit control from the developer.
</Accordion>

<Accordion title="How does Suki SDK work?">
  The clinician will use the partner application installed on their device
  (mobile/web) to initiate the ambient session. The Suki SDK records the
  clinician-patient conversation or clinician monologue in real-time,
  streaming it to the server.

In cases of network instability, the recording (audio)
  occurs offline on the client device. The SDK's UI enables users to start,
  stop, and pause voice recordings, handling microphone access, audio capture,
  encryption, encoding, and data transmission.

It also manages system-level interruptions like incoming calls or messages, delegating them to the
  partner application.

**Note generation and editing:** Upon completing the voice
  recording, the clinician can generate the note. The Suki SDK transcribes the
  recording using Suki's automatic speech recognizer (ASR) to create a
  transcript, which is then combined with other relevant patient
  information to produce a new patient note.

This note is processed by Suki's fine-tuned Language Models (LLMs) to generate ambient note suggestions. By
  default, a basic `SOAP` note template is used unless otherwise specified. The
  SDK also enables clinicians to edit the generated note through voice
  dictation or typing.

Finally, the Suki SDK allows the parent app to retrieve
  the final note in LOINC coded JSON format or write back the generated notes
  and sections using provided APIs.
</Accordion>

<Accordion title="What platforms does the Suki SDK support?">
  Currently, the Suki SDK supports web interfaces that use ReactJS and
  JavaScript.
</Accordion>

<Accordion title="What are the main benefits of the Suki SDK?">
  **Ease of integration:** Developers can integrate the Suki SDK in their
  application with minimal effort, requiring only a few lines of code,
  ensuring a quick and smooth integration process.

**Flexibility and customizability:** The Suki SDK offers developers the
  flexibility to customize the user interface elements to align with their
  branding guidelines and style of their applications.

**User experience:** Suki's
  AI capabilities are available directly within partner applications, which
  eliminates the need for users to switch contexts. This streamlined workflow
  enhances efficiency and gives clinicians a more intuitive user experience.
</Accordion>

# Implementation
Source: https://developer.suki.ai/web-sdk/faqs/implementation

Implementation questions and best practices for Web SDK integration

<Accordion title="Are there any best practices for implementing the Suki SDK?">
  Yes, to ensure a successful implementation of the Suki SDK, start by clearly
  defining your project requirements and reviewing the SDK documentation
  thoroughly.

Set up your development environment with the necessary tools and
  adopt a modular approach, integrating one feature at a time to simplify
  troubleshooting. Adhere to coding standards, implement robust error handling
  and logging, and secure your API keys and data transmissions.
</Accordion>

<Accordion title="Can the Suki SDK be customized to fit our organization's specific needs?">
  Yes, there are a set of elements within the SDK UI related to its look and
  feel that can be changed such as color, width/height and presence of buttons.
</Accordion>

# Technical
Source: https://developer.suki.ai/web-sdk/faqs/technical

Technical questions about Web SDK architecture, performance, and troubleshooting

<Accordion title="Are there any prerequisites for using the Suki SDK?">
  You should use ReactJS 18 or higher, or alternatively, pure JavaScript to
  utilize our SDK. If you're using a different framework, please reach out to
  us for assistance.
</Accordion>

<Accordion title="How do we integrate the Suki SDK into our existing systems?">
  To integrate the Suki SDK into your existing systems, follow the
  instructions provided for ReactJS and JavaScript.
</Accordion>

<Accordion title="What format should encounter and patient identifiers use?">
  **`patient.identifier`** and **`encounter.identifier`** (when set) must each be strings **at most 36 characters** (<Tooltip href="/Glossary/v#varchar-36">varchar(36)</Tooltip>). Longer values can cause errors when the platform creates ambient composition or related resources. See [Patient](/web-sdk/api-reference/types/patient) and [Encounter](/web-sdk/api-reference/types/encounter).
</Accordion>

<Accordion title="How often is the SDK updated, and how are updates managed?">
  We update the SDK regularly to keep it compatible with the latest platform versions and to introduce new features and improvements.

We generally release updates quarterly and issue critical bug fixes and security patches as needed. We manage updates through Semantic Versioning (Major.Minor.Patch).
  We send new-release notifications through our developer mailing list and publish detailed release notes in the documentation.

To update the SDK, you can use your npm package manager:

```bash theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
  npm update {sdk-package-name}
  ```

We highly recommend keeping the SDK **updated** to benefit from the latest features and improvements.
  If you encounter any issues during the update process, our support team is available to assist you. Suki will support its then-current release of the Services and the last major release of the Services.

Keep your integration up to date by updating to the latest SDK version within six months of each release.
</Accordion>

# Ambient Session Overview
Source: https://developer.suki.ai/web-sdk/guides/ambient

Learn how to implement ambient sessions with the Web SDK

<span>Quick summary</span>
  </div>

<div>
    An ambient session captures patient-provider conversations and generates clinical notes in real-time. The SDK handles recording, note generation, and error handling automatically.

<br />

Manage sessions in two ways: uncontrolled mode where users interact only with SDK UI controls, or controlled mode where your EHR system controls when sessions start and stop through external triggers.
  </div>

<span>Last updated:</span>
    <span>May 2026</span>
  </div>
</div>

An ambient session captures patient-provider conversations and generates clinical notes in real-time. The SDK handles recording, note generation, and error handling automatically.

To generate notes, you must configure sections that organize the content. Use either predefined note types or [LOINC codes](/documentation/note-sections). The SDK creates notes from the conversation using these configured sections.

<Note>
  LOINC code support is available in **version 2.0** and above. See the [note sections documentation](/documentation/note-sections) for supported codes. For older versions, contact support to configure note types.
</Note>

## Session management in Web SDK

Manage ambient sessions in the Web SDK in two ways:

<CardGroup>
  <Card title="Uncontrolled Mode" icon="circle-play">
    Users interact only with SDK UI controls. The SDK manages the session lifecycle automatically.
  </Card>

<Card title="Controlled Mode" icon="sliders">
    Your EHR system controls the session lifecycle (start, stop, resume) through external triggers. The SDK handles recording and note generation while your app controls when sessions start and stop.
  </Card>
</CardGroup>

## Ambient guides

<CardGroup>
  <Card title="Create Session" icon="plus" href="/web-sdk/guides/ambient-implementation">
    Create an ambient session and provide session context.
  </Card>

<Card title="Session Status" icon="waveform" href="/web-sdk/guides/ambient-session-status">
    Lifecycle events and status flags for ambient sessions.
  </Card>

<Card title="Problem-Based Charting" icon="list" href="/web-sdk/guides/ambient-problem-based-charting">
    Enable PBC and pass existing patient diagnoses.
  </Card>

<Card title="Multilingual Support" icon="language" href="/web-sdk/guides/ambient-multilingual">
    Use multiple languages in ambient sessions.
  </Card>

<Card title="Offline Mode" icon="wifi" href="/web-sdk/guides/ambient-offline-mode">
    How sessions behave during network interruptions.
  </Card>

<Card title="Re-Ambient & Recovery" icon="rotate" href="/web-sdk/guides/ambient-session-recovery">
    Continue existing notes and recover abandoned sessions.
  </Card>
</CardGroup>

# Create Session
Source: https://developer.suki.ai/web-sdk/guides/ambient-implementation

Learn to create a session and implement controlled session management with the Suki Web SDK

<Callout title="Updates" icon="bell">
  **Updated**

From **`v2.2.0+`**, you can pass **optional session-level metadata** in `ambientOptions` (in `mount` or `setAmbientOptions`) to improve note generation. When you set **`visitType`**, the Web SDK also uses it as the **note title** in the patient note list (see [Note list titles](/web-sdk/guides/note-management#note-titles-in-the-web-sdk-ui)).

Learn more in the [AmbientOptions](/web-sdk/api-reference/types/ambient-options#properties) reference. **These parameters are optional**; omitting them does not break existing flows.
</Callout>

Before you can start recording audio and generating clinical notes using the Web SDK, you must create an ambient session. This guide shows you how to create a session and provide clinical context that helps Suki generate more accurate notes.

**What will you learn?**

In this guide, you will learn how to:

* Configure the SDK client with `initialize()` in JavaScript or `init()` from the `useSuki()` hook in React
* Provide session context through `mount()` or the `<SukiAssistant>` component
* Start an ambient session with `startAmbient()` and read the active session ID from `activeAmbientId`

## Controlled session management

To create an ambient session with the Suki Web SDK, follow this three-step workflow:

<Steps>
  <Step title="Configure the client">
    You must first initialize the client to establish a connection.

* **JavaScript:** Call `initialize(options)` to get back an [`SDKClientInstance`](/web-sdk/api-reference/classes#sdkclient-instance).
    * **React:** Call `init()` from the `useSuki()` hook.
  </Step>

<Step title="Provide session context">
    You provide the encounter data and `ambientOptions`, such as patient details, note sections, and visit type, to improve note quality. Detailed context helps the Suki generate more accurate clinical notes.

* **JavaScript:** Pass the context through `sdkClient.mount()`.
    * **React:** Use the props on the `<SukiAssistant>` component.

<Note>
      **`patient.identifier`** is required; **`encounter.identifier`** is optional. Each must be a string **at most 36 characters** (<Tooltip href="/Glossary/v#varchar-36">varchar(36)</Tooltip>). Longer strings can fail during composition or ambient workflows. See [Patient](/web-sdk/api-reference/types/patient) and [Encounter](/web-sdk/api-reference/types/encounter).
    </Note>
  </Step>

<Step title="Start the session">
    Once you have configured the client and context, you can start the ambient recording.

* **Start:** Call `startAmbient()` on the client in JavaScript, or from the `useSuki()` hook in React.
    * **Track:** Read the active session ID from `sdkClient.activeAmbientId`, or from the `useSuki()` hook in React, to display the status of the current session.
  </Step>
</Steps>

<Tip>
  Providing richer metadata in the `ambientOptions` ensures the Suki Web SDK has the necessary context to generate more accurate clinical notes.
</Tip>

The following example shows how to create an ambient session in JavaScript and React using the Suki Web SDK.

<View title="JavaScript" icon="js">
  ```js controlled.js expandable theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
  import { SukiAuthManager } from "@suki-sdk/core";
  import { initialize } from "@suki-sdk/js";

let isSukiReady = false;

// Replace with your actual encounter data
  const encounterDetails = {
    identifier: "6ec3920f-b0b1-499d-a4e9-889bf788e5ab",
    patient: {
      identifier: "905c2521-25eb-4324-9978-724636df3436",
      name: {
        use: "official",
        family: "Doe",
        given: ["John"],
        suffix: ["MD"],
      },
      birthDate: "1990-01-01",
      gender: "Male",
    },
  };

const authManager = new SukiAuthManager({
    partnerId: "f80c8db8-a4d0-4b75-8d63-56c82b5413f0", // Replace with your actual partner ID
    partnerToken: "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...", // Replace with your actual partner token
    providerName: "John Doe", // Replace with the full name of the provider
    providerOrgId: "1234", // Replace with the provider's organization ID
    providerSpecialty: "FAMILY_MEDICINE", // Replace with the provider's specialty
    environment: "production",
    loginOnInitialize: true, 
    providerId: "1234567890", // Replace with the provider's ID
    providerName: "John Doe", // Replace with the full name of the provider
    providerOrgId: "1234", // Replace with the provider's organization ID
    providerSpecialty: "FAMILY_MEDICINE", // Replace with the provider's specialty
  });

const sdkClient = initialize({
    authManager,
  });

const unsubscribeReady = sdkClient.on("ready", () => {
    isSukiReady = true;
  });

// Ambient session control functions
  function startAmbient() {
    if (isSukiReady) {
      sdkClient.startAmbient();
    } else {
      console.error("Suki SDK is not ready yet.");
    }
  }

function pauseAmbient() {
    if (isSukiReady) {
      sdkClient.pauseAmbient();
    } else {
      console.error("Suki SDK is not ready yet.");
    }
  }

function resumeAmbient() {
    if (isSukiReady) {
      sdkClient.resumeAmbient();
    } else {
      console.error("Suki SDK is not ready yet.");
    }
  }

function cancelAmbient() {
    if (isSukiReady) {
      sdkClient.cancelAmbient();
    } else {
      console.error("Suki SDK is not ready yet.");
    }
  }

function submitAmbient() {
    if (isSukiReady) {
      sdkClient.submitAmbient();
    } else {
      console.error("Suki SDK is not ready yet.");
    }
  }

// Attach event listeners to buttons
  document.getElementById("start-ambient").addEventListener("click", startAmbient);
  document.getElementById("pause-ambient").addEventListener("click", pauseAmbient);
  document.getElementById("resume-ambient").addEventListener("click", resumeAmbient);
  document.getElementById("cancel-ambient").addEventListener("click", cancelAmbient);
  document.getElementById("submit-ambient").addEventListener("click", submitAmbient);

// Cleanup function to destroy the SDK and event listeners
  // Call this function when you no longer need the SDK
  function destroy() {
    isSukiReady = false;
    unsubscribeInit();
    unsubscribeReady();
    sdkClient.destroy();
    
    // Remove event listeners
    document.getElementById("start-ambient").removeEventListener("click", startAmbient);
    document.getElementById("pause-ambient").removeEventListener("click", pauseAmbient);
    document.getElementById("resume-ambient").removeEventListener("click", resumeAmbient);
    document.getElementById("cancel-ambient").removeEventListener("click", cancelAmbient);
    document.getElementById("submit-ambient").removeEventListener("click", submitAmbient);
    
    // Clear the root element
    document.getElementById("suki-root").innerHTML = "";
  }
  ```
</View>

<View title="React" icon="react">
  ```jsx controlled.jsx expandable theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
  import { useState, useEffect, useMemo } from "react";
  import { SukiAuthManager } from "@suki-sdk/core";
  import { useSuki, SukiAssistant } from "@suki-sdk/react";

function Controlled() {
    const authManager = useMemo(
      () =>
        new SukiAuthManager({
          partnerId: "f80c8db8-a4d0-4b75-8d63-56c82b5413f0", // Replace with your actual partner ID
          partnerToken: "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...", // Replace with your actual partner token
          providerName: "John Doe", // Replace with the full name of the provider
          providerOrgId: "1234", // Replace with the provider's organization ID
          environment: "production",
          loginOnInitialize: true,
          providerId: "1234567890", // Replace with the provider's ID
          providerName: "John Doe", // Replace with the full name of the provider
          providerOrgId: "1234", // Replace with the provider's organization ID
          providerSpecialty: "FAMILY_MEDICINE", // Replace with the provider's specialty
        }),
      [],
    );

const {
      cancelAmbient,
      pauseAmbient,
      resumeAmbient,
      startAmbient,
      submitAmbient,
      init,
      on,
      isInitialized,
    } = useSuki();
    const [isSukiReady, setIsSukiReady] = useState(false);

// Replace with your actual encounter data
    const currentEncounter = useMemo(
      () => ({
        identifier: "6ec3920f-b0b1-499d-a4e9-889bf788e5ab",
        patient: {
          identifier: "905c2521-25eb-4324-9978-724636df3436",
          name: {
            use: "official",
            family: "Doe",
            given: ["John"],
            suffix: ["MD"],
          },
          birthDate: "1990-01-01",
          gender: "Male",
        },
      }),
      []
    );

// Initialize SDK when component mounts
    useEffect(() => {
      if (!isInitialized) {
        init({ authManager });
      }
    }, [init, isInitialized, authManager]);

// Set up event listeners for SDK initialization and readiness
    useEffect(() => {
      const unsubscribeInit = on("init:change", (isInitialized) => {
        if (!isInitialized) {
          setIsSukiReady(false); // Reset the ready state if initialization fails
        }
      });

const unsubscribeReady = on("ready", () => {
        setIsSukiReady(true);
      });

return () => {
        unsubscribeInit();
        unsubscribeReady();
      };
    }, [on]);

return (
      <>
        <SukiAssistant
          encounter={currentEncounter}
          ambientOptions={{
            sections: [
              { loinc: "51848-0" },
              { loinc: "11450-4" },
              { loinc: "29545-1" },
            ],
            diagnoses: { // [!code ++:14] New in v2.1.2
              values: [
                {
                  codes: [
                    {
                      code: "I10",
                      description: "Essential hypertension",
                      type: "ICD10",
                    },
                  ],
                  diagnosisNote: "Hypertension",
                },
              ],
            },
            visitType: "ESTABLISHED_PATIENT", // [!code ++:6] New in v2.2.0
            encounterType: "AMBULATORY",
            providerRole: "PRIMARY/ATTENDING",
            reasonForVisit: "Follow-up for hypertension",
            chiefComplaint: "Headache",
          }}
        />

{isSukiReady && (
          <div>
            <button onClick={startAmbient}>Start Ambient</button>
            <button onClick={pauseAmbient}>Pause Ambient</button>
            <button onClick={resumeAmbient}>Resume Ambient</button>
            <button onClick={cancelAmbient}>Cancel Ambient</button>
            <button onClick={submitAmbient}>Submit Ambient</button>
          </div>
        )}
        {/* Rest of your code */}
      </>
    );
  }
  ```
</View>

## Update session encounter and ambient options

You can update the session encounter and ambient options whenever a new encounter loads in your EHR. Providing current context ensures that the Suki Platform generates accurate documentation for the specific visit.

### Update the encounter

When the patient or visit details change, you must update the encounter context.

* **JavaScript:** Call `setEncounter()` on the client.
* **React:** Use the `encounter` prop on the `<SukiAssistant>` component.

### Update ambient options

You can also update the ambient options, such as required note sections or diagnoses, during an active session.

* **JavaScript:** Call `setAmbientOptions()` on the client.
* **React:** Use the `ambientOptions` prop on the `<SukiAssistant>` component.

<Tip>
  Updating the encounter and ambient options as soon as the EHR context changes ensures that the session is in sync with the latest context.
</Tip>

<View title="JavaScript" icon="js">
  ```js JavaScript theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
  // Update encounter data
  sdkClient.setEncounter({
    identifier: "qsc2393g-b0b1-499d-a4e9-983cq125g5op",
    patient: {
      identifier: "25eb905-1232-082132-aw12320do4r",
      name: {
        use: "official",
        family: "Smith",
        given: ["Jane"],
        suffix: [],
      },
      birthDate: "1985-05-15",
      gender: "Female",
    },
  });

// Update ambient options
  sdkClient.setAmbientOptions({
    sections: [
      { loinc: "48765-2" },
      { loinc: "10157-6" },
      { loinc: "10164-2" },
    ],
    diagnoses: {
      values: [
        {
          codes: [
            { code: "I10", description: "Essential hypertension", type: "ICD10" },
          ],
          diagnosisNote: "Hypertension",
        },
      ],
    },
    visitType: "ESTABLISHED_PATIENT",
    encounterType: "AMBULATORY",
    providerRole: "PRIMARY/ATTENDING",
    reasonForVisit: "Follow-up for hypertension",
    chiefComplaint: "Blood pressure check",
  });
  ```
</View>

<View title="React" icon="react">
  ```jsx React theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
  <SukiAssistant
    encounter={{
      identifier: "qsc2393g-b0b1-499d-a4e9-983cq125g5op",
      patient: {
        identifier: "25eb905-1232-082132-aw12320do4r",
        name: {
          use: "official",
          family: "Smith",
          given: ["Jane"],
          suffix: [],
        },
        birthDate: "1985-05-15",
        gender: "Female",
      },
    }}
    ambientOptions={{
      sections: [
        { loinc: "48765-2" },
        { loinc: "10157-6" },
        { loinc: "10164-2" },
      ],
      diagnoses: {
        values: [
          {
            codes: [
              { code: "I10", description: "Essential hypertension", type: "ICD10" },
            ],
            diagnosisNote: "Hypertension",
          },
        ],
      },
      visitType: "ESTABLISHED_PATIENT",
      encounterType: "AMBULATORY",
      providerRole: "PRIMARY/ATTENDING",
      reasonForVisit: "Follow-up for hypertension",
      chiefComplaint: "Blood pressure check",
    }}
  />
  ```

<Info>
    Passing new encounter data or ambient options to the `SukiAssistant` component automatically updates the encounter details or sections for note generation.
  </Info>
</View>

## Next steps

<Icon icon="file-lines" /> Track session state: [Ambient session status](/web-sdk/guides/ambient-session-status)

<Icon icon="file-lines" /> Configure problem-based notes: [PBC](/web-sdk/guides/ambient-problem-based-charting)

<Icon icon="file-lines" /> Return to [Ambient session](/web-sdk/guides/ambient) overview

# Multilingual Sessions
Source: https://developer.suki.ai/web-sdk/guides/ambient-multilingual

Use multilingual capability in ambient sessions; the SDK generates notes in English from any language

The Web SDK supports the **Multilingual** capability for all ambient sessions you create. Patients and providers can speak in their preferred language during the conversation; the SDK generates the clinical note in English.

<Note>
  The SDK enables multilingual capability automatically when you create an ambient session. You don't need to configure anything.
</Note>

Learn more about multilingual capability in the [Multilingual support](/api-reference/capabilities/multilingual) capability guide.

## Next steps

<Icon icon="file-lines" /> Problem-based charting: [PBC](/web-sdk/guides/ambient-problem-based-charting)

<Icon icon="file-lines" /> Offline behavior: [Offline mode](/web-sdk/guides/ambient-offline-mode)

<Icon icon="file-lines" /> Return to [Ambient session](/web-sdk/guides/ambient) overview

# Offline Mode
Source: https://developer.suki.ai/web-sdk/guides/ambient-offline-mode

How ambient sessions behave during network interruptions, what triggers offline mode, and recovery with the Web SDK

The Web SDK supports offline mode so ambient sessions continue during network interruptions. When the connection is lost, recording continues and audio is stored locally until connectivity is restored.

The SDK uses a **15-second buffer** before transitioning to offline mode. Use this delay to display a connection status notification (for example, **Connection unstable**) in your UI before the session goes fully offline.

## What triggers offline mode

A session enters offline mode due to:

* Network interruptions
* Backend unavailability
* High latency in audio transmission
* Socket connection drops
* Authentication failures

## Offline mode behavior

When the session enters offline mode, the SDK automatically:

<CardGroup>
  <Card title="Continues Recording" icon="microphone">
    Audio recording continues without interruption during network issues.
  </Card>

<Card title="Local Storage" icon="hard-drive">
    Audio and metadata are stored locally on the device.
  </Card>

<Card title="Automatic Upload" icon="cloud-arrow-up">
    Stored data is automatically uploaded once connection is restored.
  </Card>

<Card title="User Notification" icon="bell">
    Users are notified about offline status and reconnection attempts.
  </Card>
</CardGroup>

<Info>
  During offline mode, **session submission is temporarily paused**. The SDK will continuously attempt to reconnect and submit the note once connectivity is reestablished.
</Info>

## Next steps

<Icon icon="file-lines" /> Re-ambient and recovery: [Session recovery](/web-sdk/guides/ambient-session-recovery)

<Icon icon="file-lines" /> Multilingual: [Multilingual support](/web-sdk/guides/ambient-multilingual)

<Icon icon="file-lines" /> Return to [Ambient session](/web-sdk/guides/ambient) overview

# Problem-Based Charting In Web SDK
Source: https://developer.suki.ai/web-sdk/guides/ambient-problem-based-charting

Enable PBC, set a PBN section, and pass existing patient diagnoses so notes merge with EMR problems

<Callout title="Updates" icon="bell">
  **Updated**

The `diagnoses` block in `ambientOptions` is supported in the Web SDK `v2.1.2`. Pass the patient's existing diagnoses (e.g. from the EMR) so the session merges them with what's discussed in the visit. Refer to the [Existing patient diagnoses](/web-sdk/guides/ambient-problem-based-charting#existing-patient-diagnoses) guide for more details.
</Callout>

Problem-Based Charting (PBC) organizes clinical notes by patient problems instead of traditional note sections. To enable it in the Web SDK, mark one section as the Problem-Based Note (PBN) by setting `isPBNSection: true` on that section in `ambientOptions` (using the section's [LOINC code](/documentation/note-sections)).

## Implementation

<View title="JavaScript" icon="js">
  ```js JavaScript theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
  sdkClient.mount({
    rootElement: document.getElementById("suki-root"),
    encounter: encounterDetails,
    ambientOptions: {
      sections: [
        { loinc: "51848-0", isPBNSection: true }, // Assessment and Plan as PBN
        { loinc: "11450-4" },
        { loinc: "29545-1" },
      ],
      diagnoses: { // [!code ++:14] New in v2.1.2
        values: [
          {
            codes: [
              {
                code: "I10",
                description: "Essential hypertension",
                type: "ICD10",
              },
            ],
            diagnosisNote: "Hypertension",
          },
        ],
      },
    },
  });
  ```
</View>

<View title="React" icon="react">
  ```jsx React theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
  <SukiAssistant
    encounter={currentEncounter}
    ambientOptions={{
      sections: [
        { loinc: "51848-0", isPBNSection: true }, // Assessment and Plan as PBN
        { loinc: "11450-4" },
        { loinc: "29545-1" },
      ],
      diagnoses: { //  [!code ++:14] New in v2.1.2
        values: [
          {
            codes: [
              {
                code: "I10",
                description: "Essential hypertension",
                type: "ICD10",
              },
            ],
            diagnosisNote: "Hypertension",
          },
        ],
      },
    }}
  />
  ```
</View>

## Configuration rules

<Steps>
  <Step title="Single PBN section">
    Only one section can have `isPBNSection: true`. If multiple sections are marked as PBN, the ambient session will fail to start.
  </Step>

<Step title="Explicit flag values">
    Explicitly pass `true` or `false` for the `isPBNSection` flag. The value provided will be respected as-is.
  </Step>

<Step title="Default behavior">
    If no section includes the `isPBNSection` flag (i.e., left `undefined`) and the Assessment & Plan section (51847-2) is present, that section will automatically be treated as the PBN.
  </Step>

<Step title="Override default">
    If you explicitly set `isPBNSection: false` on the Assessment & Plan section, the automatic default behavior will not apply.
  </Step>
</Steps>

<Warning>
  For a given ambient session, **only one section** can have `isPBNSection: true`. If more than one section is marked as PBN, the ambient session will fail to start.
</Warning>

## Existing patient diagnoses

Pass the patient's current diagnoses (e.g. from the EMR) into the session using the `diagnoses` block in the `ambientOptions` object. The SDK automatically merges them with what's discussed during the visit so the note has one problem list and no duplicates.

When you switch to a new patient or encounter, pass that encounter's diagnoses in `ambientOptions`; see [Update encounter and ambient options](/web-sdk/guides/ambient-implementation#update-encounter-and-ambient-options) for more details.

<Note>
  Diagnoses can be seeded **only at the start of the first session** in an encounter.
</Note>

In re-ambient (later sessions in the same encounter), you cannot seed diagnoses; rely on the note from the previous session for any updates.

A diagnosis you pass in is included in the note only if the provider or patient talks about it during the visit. If they don't mention it, it's left out.

### Requirements for passing diagnoses

* You must have **at least one PBC section** in your `ambientOptions.sections` (set `isPBNSection: true`).
* For each diagnosis you pass in:
  * Include exactly one code in the `codes` array.
  * Set the code `type` to `"ICD10"`.
  * Provide at least one of `code` or `description` (you can provide both).
  * `diagnosis_note` is optional.

<Note>
  **Things to keep in mind**

* **Input:** Only **ICD10** is supported for the diagnoses you pass in. Output can include ICD10, IMO, and SNOMED.

* **AutoCoding:** Off by default so your seeded data is used as is.
</Note>

<Note>
  **Response**

The response is **unchanged** when you pass diagnoses. You receive the same object (`noteId`, `encounterId`, `contents`) via `onNoteSubmit` or `note-submission:success`.

For the full response structure, refer to [Note management - Response structure](/web-sdk/guides/note-management#response-structure).
</Note>

## Next steps

<Icon icon="file-lines" /> Track session state: [Ambient session status](/web-sdk/guides/ambient-session-status)

<Icon icon="file-lines" /> Multilingual sessions: [Multilingual support](/web-sdk/guides/ambient-multilingual)

<Icon icon="file-lines" /> Return to [Ambient session](/web-sdk/guides/ambient) overview

# Re-Ambient & Session Recovery
Source: https://developer.suki.ai/web-sdk/guides/ambient-session-recovery

Continue an existing note with re-ambient and recover abandoned ambient sessions with the Web SDK

## Re-ambient sessions

Each ambient session creates a new note, even if the patient and encounter identifiers are the same. To continue working on an existing note:

<Steps>
  <Step title="Open existing note">
    Open the existing note in the SDK UI.
  </Step>

<Step title="Initiate re-ambient">
    Start a re-ambient session from the note interface.
  </Step>

<Step title="Intelligent merge">
    The SDK intelligently merges the new session content with existing note content, allowing seamless continuation.
  </Step>
</Steps>

## Session recovery

If the app crashes or a session is abandoned (not cancelled or submitted), the Web SDK automatically recovers the last ambient session when the app loads again.

### What gets recovered

<Accordion title="Restore Audio Recording" icon="waveform">
  The last recorded audio is restored and made available for processing.
</Accordion>

<Accordion title="Reattach Session Metadata" icon="database">
  Session metadata (encounter details, timestamps, configuration) is reattached to maintain continuity.
</Accordion>

<Accordion title="User Prompt" icon="circle-question">
  The user is prompted to either generate the note or discard the session. If the user chooses to generate the note, the SDK proceeds with note generation in the background.
</Accordion>

### Best practices

<Note>
  Always submit or cancel the active ambient session when users navigate away from the encounter. This prevents unintended session recoveries.

**Recommendation:** Show a confirmation dialog before navigation so users can decide whether to continue or discard the session.
</Note>

## Next steps

<Icon icon="file-lines" /> Offline behavior: [Offline mode](/web-sdk/guides/ambient-offline-mode)

<Icon icon="file-lines" /> Note submission: [Note management](/web-sdk/guides/note-management)

<Icon icon="file-lines" /> Return to [Ambient session](/web-sdk/guides/ambient) overview

# Session Status & Events
Source: https://developer.suki.ai/web-sdk/guides/ambient-session-status

Track ambient session status and lifecycle events (start, pause, resume, cancel, submit) with the Web SDK

The Web SDK sends real-time events so you can see ambient session status. The `ambient:update` event includes an `ambientSessionId`. That is the unique ID for that recording session.

Use it to follow the session lifecycle and when you report issues to support. You can also read the current session ID from `activeAmbientId` on [`SDKClientInstance`](/web-sdk/api-reference/classes) or from [`useSuki()`](/web-sdk/api-reference/hooks) after you call `startAmbient()`. Refer to [Create session](/web-sdk/guides/ambient-implementation) for more detail.

## Quick reference: IDs

The diagram below shows the order of IDs generated in the different stages of the ambient session lifecycle while using the Web SDK.

You start with the encounter ID, which is the encounter you supplied at setup. Next is the note ID, which identifies the note generated after the session is submitted. Then comes the ambient session ID, which is created when you call `startAmbient()`. Finally, the active ambient ID identifies the session that is currently active.

| Field                  | Where you read it                                                                                                                                                                                    | What it is                                                                                                                                                                                                |
| :--------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **`encounterId`**      | `onNoteSubmit` (React) and `note-submission:success` when the note completes successfully                                                                                                            | Unique identifier for the encounter associated with the note. Refer to [Note management](/web-sdk/guides/note-management).                                                                                |
| **`noteId`**           | `onNoteSubmit` (React) and `note-submission:success` when the note completes successfully                                                                                                            | Unique identifier for the generated note. Refer to [Note management](/web-sdk/guides/note-management).                                                                                                    |
| **`ambientSessionId`** | `ambient:update` (along with `isAmbientInProgress` and `isAmbientPaused`), and in payloads for the `ambient:start`, `ambient:pause`, `ambient:resume`, `ambient:cancel`, and `ambient:submit` events | Unique ID for a recording session. This is the same session identifier emitted across ambient events. Refer to [Emitter events](/web-sdk/api-reference/types/emitter-events) for the exact payload types. |
| **`activeAmbientId`**  | [`SDKClientInstance`](/web-sdk/api-reference/classes), [`useSuki()`](/web-sdk/api-reference/hooks)                                                                                                   | The ID of the currently active ambient session. Returns `null` if no session is active ([Classes](/web-sdk/api-reference/classes), [Hooks](/web-sdk/api-reference/hooks)).                                |

Refer to [Emitter events](/web-sdk/api-reference/types/emitter-events) for the full event list and types.

<Note>
  **Important:** `encounterId` is not the same as `ambientSessionId` or `activeAmbientId`. It comes back after the note completes (refer to [Note management](/web-sdk/guides/note-management)). It is the encounter you supplied at setup.
</Note>

## Lifecycle events

The Web SDK emits these events when the session state changes:

* `ambient:start` - Emitted when a new ambient session is started.
* `ambient:pause` - Emitted when the ambient session is paused.
* `ambient:resume` - Emitted when the ambient session is resumed.
* `ambient:cancel` - Emitted when the ambient session is cancelled.
* `ambient:submit` - Emitted when the ambient session is submitted.

<View title="JavaScript" icon="js">
  ```js JavaScript theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
  sdkClient.on("ambient:update", (flags) => {
    console.log("Ambient in progress:", flags.isAmbientInProgress);
    console.log("Ambient paused:", flags.isAmbientPaused);
  });
  // lifecycle events supported by the Web SDK
  sdkClient.on("ambient:start", ({ ambientSessionId }) => {
    // New in v2.0.4. Payload is { ambientSessionId }; refer to Emitter events.
    console.log("Ambient started:", ambientSessionId);
  });
  ```
</View>

<View title="React" icon="react">
  ```jsx React theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
  import { useSuki } from "@suki-sdk/react";
  import { useEffect } from "react";

const MyComponent = () => {
    const { on } = useSuki();

useEffect(() => {
      const unsubscribe = on("ambient:update", (flags) => {
        console.log("Ambient in progress:", flags.isAmbientInProgress);
        console.log("Ambient paused:", flags.isAmbientPaused);
      });

return () => unsubscribe();
    }, [on]);

return <div>App Content</div>;
  };
  ```
</View>

## Status flags

<ResponseField name="isAmbientInProgress" type="boolean">
  Returns `true` if an ambient session is currently active (started and not cancelled or submitted).
</ResponseField>

<ResponseField name="isAmbientPaused" type="boolean">
  Returns `true` if the ambient session is currently in a paused state.
</ResponseField>

## Next steps

<Icon icon="file-lines" /> Implement controlled sessions: [Ambient implementation](/web-sdk/guides/ambient-implementation)

<Icon icon="file-lines" /> Configure problem-based notes: [PBC](/web-sdk/guides/ambient-problem-based-charting)

<Icon icon="file-lines" /> Return to [Ambient session](/web-sdk/guides/ambient) overview

# Branding & Layout
Source: https://developer.suki.ai/web-sdk/guides/branding

Customize Web SDK UI appearance with branding guidelines and layout options

<span>Quick summary</span>
  </div>

<div>
    The Suki SDK comes with an out-of-the-box UI component that automatically manages user states, recording flows, and error handling. The default recommended dimensions for optimal display are 360 pixels in width and 912 pixels in height.

<br />

Widths exceeding 360 pixels are acceptable, and the height can be adjusted to match the enclosing window's dimensions.
  </div>

<span>Last updated:</span>
    <span>April 2026</span>
  </div>
</div>

Customize the Suki SDK UI appearance with branding guidelines and layout options.

## Spacing and layout guidelines

The Suki SDK comes with an out-of-the-box UI component that will automatically manage user states, recording flows and error handling, allowing you to provide your users with a seamless experience.

Below are a set of recommended guidelines on the width and height of the SDK UI when embedding it in your application.

The default recommended dimensions for optimal display are **360 pixels** in width and **912 pixels** in height. However, widths exceeding **360 pixels** are acceptable, and the height can be adjusted to match the enclosing window's dimensions.

# Audio Dictation In Web SDK For JavaScript
Source: https://developer.suki.ai/web-sdk/guides/dictation-javascript

Learn how to use dictation in the Suki Web SDK for JavaScript applications

This guide walks you through the process of integrating audio dictation using the Suki Web SDK in a JavaScript application (browser-based) using the JavaScript package provided by Suki.
You will create **Auth Manager** and **Dictation Client**, then start audio dictation by calling **`await dictationClient.show({ ... })`** from your own code when the user is ready.

Let's get started!

## Prerequisites

Before you begin, you must have the following requirements met:

* **Packages:** Install `@suki-sdk/js` and `@suki-sdk/core` packages.
* **Partner credentials:** Obtain `partnerId` and `partnerToken` from Suki after [Partner onboarding](/documentation/partner-onboarding).
* **Browser and layout:** Your app runs in a **browser**, with a real DOM and a dictation **container** that has height.

Refer to [Prerequisites](/web-sdk/prerequisites) guide for more details.

## Install the packages

Add both packages to the same project you load in the browser:

<CodeGroup title="Install the @suki-sdk/dictation and @suki-sdk/core packages">
  ```shell pnpm theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
  pnpm add @suki-sdk/core @suki-sdk/js
  ```

```shell npm theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
  npm install @suki-sdk/core @suki-sdk/js 
  ```

```shell yarn theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
  yarn add @suki-sdk/core @suki-sdk/js 
  ```
</CodeGroup>

<Tip>
  After you install, pull the SDK into your files with **`import`**, the same way as in the examples below. Use whatever approach your project already uses for other npm libraries.
</Tip>

## Step 1: Add container and field HTML

For this example we will assume you are using **`in-field`** mode as your preferred mode.

In **`in-field`** mode you need **two** nodes in the page: a **`div`** (or similar) that you pass as **`rootElement`**, where the dictation controls show up, and a **textarea** (or input) that **`onSubmit`** will update when the user finishes.

The dictation layer **matches the size of** **`rootElement`**, so that node should have a **height** you control. Refer to [Wrapper layout](/dictation-sdk/guides/configuration#wrapper-layout) guide for recommended markup and CSS.

```html HTML theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
<div id="dictation-root"></div>
<label for="clinical-notes">Clinical notes</label>
<textarea id="clinical-notes" rows="8">

``` ## Step 2: Create auth manager Now you need to create the **Auth Manager** for your application. In order to create the Auth Manager, you must have the `partnerId` and `partnerToken` credentials from Suki. Refer to [Partner onboarding](/documentation/partner-onboarding) guide to learn how to get these credentials. Once you have all the required credentials, create **one** auth manager for the page (or app shell). **Code example for creating auth manager** ```javascript JavaScript expandable theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}} import { SukiAuthManager } from "@suki-sdk/core"; const authManager = new SukiAuthManager({ partnerId: "YOUR_PARTNER_ID", // replace with your partner ID - required partnerToken: "YOUR_PARTNER_TOKEN", // replace with your partner token - required environment: "staging", // optional: "staging" | "production" loginOnInitialize: true, // optional: sign in as soon as this runs autoRegister: false, // optional: enable provider auto-registration providerId: "YOUR_PROVIDER_ID", // optional: provider identifier in your system providerName: "YOUR_PROVIDER_NAME", // optional: full provider display name providerOrgId: "YOUR_PROVIDER_ORG_ID", // optional: organization identifier for the provider in your system providerSpecialty: "YOUR_PROVIDER_SPECIALTY", // optional: clinical specialty }); ``` ## Step 3: Create dictation client After you have created the auth manager, you can create the **dictation client** for your application. The Dictation Client is the object that will be used to start the dictation session. Create **one** dictation client and reuse it for every **`show()`** call on that page. **Code example for creating dictation client** ```javascript JavaScript expandable theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}} import { DictationClient } from "@suki-sdk/js"; const dictationClient = new DictationClient({ authManager }); ``` ## Step 4: Call show() to start dictation Now you can start the dictation session by calling the **`show()`** method on the dictation client. Call **`await dictationClient.show({ ... })`** from a click handler (or similar) when the DOM is ready. Pass **`mode`**, **`fieldId`**, **`rootElement`**, **`onSubmit`**, and any optional fields you need. Refer to [Configuration](/dictation-sdk/guides/configuration) guide for more details on the available options and how to use them. **Code example for starting dictation** ```javascript JavaScript expandable theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}} async function startDictation() { const root = document.getElementById("dictation-root"); const notes = document.getElementById("clinical-notes"); if (!root || !notes) { console.error("Missing dictation-root or clinical-notes in the DOM"); return; } try { await dictationClient.show({ mode: "in-field", // replace with your preferred mode - required fieldId: "clinical-notes", // often the same string as the textarea id rootElement: root, // replace with the DOM element where the dictation controls will be shown - required initialText: notes.value ?? "", // replace with the initial text for the dictation session - optional onSubmit: ({ fieldId, text }) => { const el = document.getElementById(fieldId); if (el) el.value = text; }, onCancel: ({ fieldId }) => { console.log("Dictation cancelled", fieldId); }, onDraft: ({ fieldId, text }) => { const el = document.getElementById(fieldId); if (el) el.value = text; }, }); } catch (err) { console.error("Dictation show() failed", err); } } document.getElementById("start-dictation")?.addEventListener("click", () => { void startDictation(); }); ``` **`onSubmit`** is required for a good user experience. If you omit it, dictation often **closes immediately** after the user acts. ## Callbacks Every callback receives the same shape as shown in the code example below: ```javascript JavaScript theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}} { fieldId: string, text: string } ``` Refer to [Callbacks](/dictation-sdk/guides/callbacks) guide for more details on the available callbacks and how to use them. ## Switching fields Calling **`show()`** again **replaces** the active session. You do **not** need to call **`hide()`** manually just to move from one field to another: ```javascript JavaScript theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}} await dictationClient.show({ /* field A options */ }); await dictationClient.show({ /* field B options */ }); ``` ## Complete code example Below is a complete code example in JavaScript for in-field mode with a single field. ```javascript JavaScript expandable theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}} import { SukiAuthManager } from "@suki-sdk/core"; import { DictationClient } from "@suki-sdk/js"; const authManager = new SukiAuthManager({ partnerId: "YOUR_PARTNER_ID", // replace with your partner ID - required partnerToken: "YOUR_PARTNER_TOKEN", // replace with your partner token - required environment: "staging", // optional: "staging" | "production" loginOnInitialize: true, // optional: sign in as soon as this runs autoRegister: false, // optional: enable provider auto-registration providerId: "YOUR_PROVIDER_ID", // optional: provider identifier in your system providerName: "YOUR_PROVIDER_NAME", // optional: full provider display name providerOrgId: "YOUR_PROVIDER_ORG_ID", // optional: organization identifier for the provider in your system providerSpecialty: "YOUR_PROVIDER_SPECIALTY", // optional: clinical specialty }); const dictationClient = new DictationClient({ authManager }); async function startClinicalNotesDictation() { const root = document.getElementById("dictation-root"); const notes = document.getElementById("clinical-notes"); if (!root || !notes) return; try { await dictationClient.show({ mode: "in-field", fieldId: "clinical-notes", rootElement: root, initialText: notes.value ?? "", onSubmit: ({ fieldId, text }) => { const el = document.getElementById(fieldId); if (el) el.value = text; }, onCancel: ({ fieldId }) => { console.log("Cancelled", fieldId); }, }); } catch (e) { console.error(e); } } document.addEventListener("DOMContentLoaded", () => { document .getElementById("start-dictation") ?.addEventListener("click", () => void startClinicalNotesDictation()); }); ``` This page focuses on **`in-field`** dictation next to a specific input. If you want a **floating dictation panel** instead, set **`mode`** to **`"scratchpad"`** and follow [Scratchpad mode](/dictation-sdk/guides/scratchpad-mode) guide. ## Best practices * **Reuse one dictation client.** Build a single **DictationClient** for the page or shell and call it again for each dictation session. Creating a new client on every click or for every field often resets the hosted UI and feels flaky. * **Reuse one auth manager.** Create **SukiAuthManager** once and pass that same instance into the client, the same pattern as in the steps above. * **Handle when the user commits.** You must supply a submit handler so the SDK can deliver the final text. Without it, dictation often closes right after the user tries to finish. * **Pick a clear field label.** Each session needs a stable, unique **fieldId** in callbacks. Using the same value as the target input's **id** is a simple way to know which element to update. Refer to [Field IDs](/dictation-sdk/guides/configuration#field-ids-in-practice) guide for more details. * **Open dictation only when the host is ready.** The DOM node you use as the dictation host should exist and have real height before you open. Otherwise the dictation area can look blank. Refer to [Error handling](/dictation-sdk/guides/error-handling) and [In-field mode](/dictation-sdk/guides/in-field-mode) guides for more details. * **Catch failures when opening dictation.** Wrap the open call so auth or setup errors show up in your logs instead of disappearing. * **Move to another field by opening again.** A new open call replaces the active session. You usually do not need a separate hide step when you are only switching which field is dictating. ## Next steps Refer to the following guides for more information. [Configuration](/dictation-sdk/guides/configuration) to learn about the available options and how to use them. [React integration](/web-sdk/guides/dictation-react) to learn how to integrate audio dictation in a React application using the Suki Web SDK. # Audio Dictation In Web SDK For React Source: https://developer.suki.ai/web-sdk/guides/dictation-react Learn how to use dictation in the Suki Web SDK for React applications This guide walks you through the process of integrating the Suki Web SDK for audio dictation in a React application (browser-based) using the React package provided by Suki. You will create **Auth Manager** and **Dictation Client** (typically inside **`useMemo`** so they are not recreated every render), wrap your tree with **Dictation Provider**, and render **Dictation** when the user should dictate. Let's get started! ## Prerequisites Before you begin, you must have the following requirements met: * **Packages:** Install **`@suki-sdk/react`**, **`@suki-sdk/core`**. * **Partner credentials:** Obtain **`partnerId`** and **`partnerToken`** from Suki after [Partner onboarding](/documentation/partner-onboarding). * **Browser and layout:** Your app runs in a **browser**, with a real DOM and enough layout for the dictation UI. Refer to [Prerequisites](/web-sdk/prerequisites) guide for more details. ## Install the packages Add the following packages to the same project you load in the browser: ```shell pnpm theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}} pnpm add @suki-sdk/core @suki-sdk/react ``` ```shell yarn theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}} yarn add @suki-sdk/core @suki-sdk/react ``` ```shell npm theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}} npm install @suki-sdk/core @suki-sdk/react ``` After you install, pull the SDK into your files with **`import`**, the same way as in the examples below. Use whatever approach your project already uses for other npm libraries. ## Step 1: Add container and field layout For this example we will assume you are using **`in-field`** mode as your preferred mode. In **`in-field`** mode you need **two** parts in the UI: a **`div`** (or similar) that you can pass as **`rootElement`**, where the dictation controls show up, and a **textarea** (or input) that **`onSubmit`** will update when the user finishes. The dictation layer **matches the size of** **`rootElement`** when you set it, so that node should have a **height** you control. Refer to [Wrapper layout](/dictation-sdk/guides/configuration#wrapper-layout) guide for recommended markup and CSS. **Code example for container and field layout** ```jsx React theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}

Clinical notes

```

Wire **`value`**, **`onChange`**, and your start button in the same component (see Step 5).

## Step 2: Create auth manager

Now you need to create the **Auth Manager** for your application. In order to create the Auth Manager, you must have the **`partnerId`** and **`partnerToken`** credentials from Suki.

Refer to [Partner onboarding](/documentation/partner-onboarding) guide to learn how to get these credentials.

**Code example for creating auth manager**

```javascript JavaScript expandable theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
import { SukiAuthManager } from "@suki-sdk/core";

## Step 3: Create dictation client

After you have created the auth manager, you can create the **dictation client** for your application. The Dictation Client is the object the React components use under the hood.

**Code example for creating dictation client in React**

## Step 4: Wrap with DictationProvider

Pass the **`client`** from Step 3 into **`DictationProvider`**. Every component that renders **`<Dictation>`** must be a **child** of that provider.

**Code example for wrapping with DictationProvider**

```jsx React expandable theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
import { DictationProvider } from "@suki-sdk/react";

export function App() {
  const client = useMemo(/* ... Step 3 ... */, []);

return (
    <DictationProvider client={client}>
      {/* children that render <Dictation /> */}
    </DictationProvider>
  );
}
```

You can put **`DictationProvider`** at app root or only around the screen that needs dictation.

## Step 5: Render Dictation

Render **`<Dictation>`** only while that field should own the session (for example when the user clicked "Start dictation"). When **`<Dictation>`** unmounts, the SDK calls **`hide()`** for you.

**Code example for rendering Dictation in React**

```jsx React expandable theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
import { useState } from "react";
import { Dictation } from "@suki-sdk/react";

function NotesEditor() {
  const [notes, setNotes] = useState("");
  const [dictationActive, setDictationActive] = useState(false);

<Tip>
  You can also drive dictation with a single **`activeFieldId`** string and render one **`<Dictation>`** when it matches, which scales to multiple fields.
</Tip>

<Note>
  **`onSubmit`** is required for a good user experience. If you omit it, dictation often **closes immediately** after the user acts.
</Note>

## Callbacks

Props such as **`onSubmit`**, **`onCancel`**, and **`onDraft`** receive the same shape as in the JavaScript API:

```jsx React  theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
{ fieldId: string, 
text: string 
}
```

Refer to [Callbacks](/dictation-sdk/guides/callbacks) guide for more details on the available callbacks and how to use them.

## Switching fields

## Unmounting and hiding

When **`<Dictation>`** unmounts, the SDK **automatically** calls **`hide()`**. You do not need to call **`hide()`** yourself for normal React flows.

## Complete code example

Below is a complete code example in React for in-field mode with **`DictationProvider`**, a toggle button, and one field.

```jsx React expandable theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
import { useMemo, useState } from "react";
import { SukiAuthManager } from "@suki-sdk/core";
import { DictationClient } from "@suki-sdk/react";
import { DictationProvider, Dictation } from "@suki-sdk/react";

const [notes, setNotes] = useState("");
  const [dictationActive, setDictationActive] = useState(false);

## Best practices

* **Reuse one auth manager.** Create **SukiAuthManager** once inside the same **`useMemo`** as the client, as in the steps above.

* **Handle when the user commits.** You must pass **`onSubmit`** so the SDK can deliver the final text. Without it, dictation often closes right after the user tries to finish.

* **One active Dictation at a time.** Use boolean state or **`activeFieldId`** so you do not mount multiple dictation surfaces against the same **`client`** at once.

* **Rely on unmount for hide.** Removing **`<Dictation>`** is the normal way to tear down the UI; you usually do not call **`hide()`** yourself in React.
</Tip>

## Next steps

Refer to the following guides for more information.

<Icon icon="file-lines" /> [Configuration](/dictation-sdk/guides/configuration) to learn about the available options and how to use them.

<Icon icon="file-lines" /> [JavaScript integration](/web-sdk/guides/dictation-javascript) to learn how to integrate audio dictation in a plain JavaScript application using the Suki Web SDK.

# Error Handling In Web SDK
Source: https://developer.suki.ai/web-sdk/guides/error-handling

Learn how to handle errors and exceptions in the Web SDK

<span>Quick summary</span>
  </div>

<div>
    The SDK uses a consistent error structure with error codes, names, and optional reasons to help you handle errors like initialization failures, patient creation issues, and note submission problems.

<br />

Listen for SDK-wide errors by subscribing to the `error` event using either the `SukiClient` instance (JavaScript) or the `useSuki` hook (React). This allows you to log and respond to issues across authentication, session management, or note handling.
  </div>

<span>Last updated:</span>
    <span>June 2026</span>
  </div>
</div>

The SDK uses a consistent error structure to help you handle errors like initialization failures, patient creation issues, and note submission problems.

All SDK errors include an **error code**, **name**, and optional **reason** to make debugging easier.

## Listening for errors

<View title="JavaScript" icon="js">
  ```js JavaScript theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
      const unsubscribeError = sdkClient.on(
        "error",
        (error) => {
          console.error("SDK error occurred:", error);
          // Use error.code, error.details.name, and error.details.reason
        },
      );
  ```
</View>

<View title="React" icon="react">
  ```jsx React theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}

import { useSuki } from "@suki-sdk/react";
      import { useEffect } from "react";

const MyComponent = () => {
        const { on } = useSuki();

useEffect(() => {
          const unsubscribe = on("error", (error) => {
            console.error("SDK error occurred:", error);
            // Use error.code, error.details.name, and error.details.reason
          });

return () => {
            unsubscribe();
          };
        }, [on]);

return <div>App Content</div>;
      };

```
</View>

## Error object structure

Every error emitted by the SDK conforms to a predictable shape that includes a top-level code and a details object with contextual information.

```ts SukiError.ts theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
type SukiError = {
  code: "SUKI0001" | "SUKI0002" | ...;
  details: {
    name: string; // e.g., "init:sdk-init-failed"
    message: string;
    reason?: string; // e.g., "lib-error", "no-init"
  };
};
```

### Example

```json JSON theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
{
  "code": "SUKI0001",
  "details": {
    "name": "init:sdk-init-failed",
    "message": "SDK initialization failed",
    "reason": "lib-error"
  }
}
```

For more details on the error codes and their meanings, refer to the [error codes](/web-sdk/api-reference/types/suki-error#errorcode-identifier) section in the types reference.

## Handling specific errors

Use `switch` statements or conditional logic to handle specific error codes:

<View title="JavaScript" icon="js">
  ```js JavaScript theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
  const unsubscribeError = sdkClient.on("error", (error) => {
    switch (error.code) {
      case "SUKI0002":
        console.error("Authentication failed. Please log in again.");
        break;
      case "SUKI0009":
        console.error("Patient creation failed. Check input data.");
        break;
      case "SUKI0013":
        if (error.details.reason === "no-ambient") {
          console.error("Ambient session was not found.");
        }
        break;
      default:
        console.error("Unhandled SDK error:", error.details.message);
    }
  });
  ```
</View>

<View title="React" icon="react">
  ```jsx React theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
  useEffect(() => {
    const unsubscribe = on("error", (error) => {
      switch (error.code) {
        case "SUKI0002":
          console.error("Authentication failed. Please log in again.");
          break;
        case "SUKI0009":
          console.error("Patient creation failed. Check input data.");
          break;
        case "SUKI0013":
          if (error.details.reason === "no-ambient") {
            console.error("Ambient session was not found.");
          }
          break;
        default:
          console.error("Unhandled SDK error:", error.details.message);
      }
    });

return () => unsubscribe();
  }, [on]);
  ```
</View>

## Best practices

* Log or report the full `SukiError` object for debugging and support.
* Use `reason` field for granular handling or user messaging.
* Always show helpful, user-friendly messages when relevant.
* Implement retries for transient errors (e.g., token expiration or network interruptions) to ensure resilience.

## Next steps

<Icon icon="file-lines" /> Refer to the [Token refresh](/web-sdk/guides/token-refresh) guide to learn more about how to refresh the token and keep the session alive.

# Note Management
Source: https://developer.suki.ai/web-sdk/guides/note-management

Learn how to manage clinical notes, content retrieval, and note lifecycle with the Web SDK

<span>Quick summary</span>
  </div>

<div>
    After submitting an ambient session, the Headed Web SDK generates a clinical note in the background. Once ready, you can retrieve the note content and save it to your EHR.

<br />

Receive note content using either the `onNoteSubmit` prop (React only) or the `note-submission:success` event (React and JavaScript). The SDK provides the note ID, encounter ID, contents organized by sections, and LOINC codes for each section. When medication orders are enabled, the same payload includes an `orders` object. Generated notes will have titles that match the **`visitType`** value passed during session init.
  </div>

<span>Last updated:</span>
    <span>June 2026</span>
  </div>
</div>

After submitting an ambient session, the Headed Web SDK generates a clinical note in the background. Once ready, you can retrieve the note content and save it to your EHR.
When Medication orders are enabled, the note submission payload also returns structured Medication orders under **`orders`**. Refer to [Medication orders JSON schema](/web-sdk/medication-orders/payload-structure) for the orders payload structure and field definitions.

## Note generation

Note generation happens automatically after session submission. Generation time depends on connectivity:

* **Online**: Faster generation since audio is processed in real-time during the conversation
* **Offline**: Slower generation since the entire audio file must upload first after connection is restored

For more details, see the [Offline mode](/web-sdk/guides/ambient-offline-mode) guide.

## Receiving note content

When a note is successfully submitted, the Headed Web SDK provides the note content to your application. When Medication orders are enabled, the same response includes an **`orders`** object. Receive the payload using either method:

* **`onNoteSubmit` prop** (React only, recommended)
* **`note-submission:success` event** (React and JavaScript)

<View title="JavaScript" icon="js">
  ```js JavaScript theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
  const unsubscribeNoteSubmission = sdkClient.on("note-submission:success", (note) => {
    console.log("Note ID:", note.noteId);
    console.log("Encounter ID:", note.encounterId);
    console.log("Note contents:", note.contents);
    
    // Save to your EHR
    note.contents.forEach((section) => {
      console.log(`Section: ${section.title}`);
      console.log(`Content: ${section.content}`);
      console.log(`LOINC Code: ${section.loinc_code}`);
    });
  });
  ```
</View>

const { on } = useSuki();

useEffect(() => {
    const unsubscribeNoteSubmission = on("note-submission:success", (note) => {
      console.log("Note submitted:", note);
    });

return () => unsubscribeNoteSubmission();
  }, [on]);

return (
    <SukiAssistant
      onNoteSubmit={handleNoteSubmit}
      // other props
    />
  );
  ```
</View>

### Note titles in the Web SDK UI

When you pass **`visitType`** in **`ambientOptions`** at session init (for example in `mount`, **`ambientOptions`** on **`SukiAssistant`**, or **`setAmbientOptions`**), the Web SDK uses that value as the **title** for the generated note in the in-product patient note list. The generated note title will match the **`visitType`** value. This helps clinicians distinguish multiple notes created on the same day.

***

***

<Note>
  The generated note will have **Created At Timestamp** instead of **Today** date.
</Note>

If **`visitType`** is omitted, the UI keeps the previous generic title behavior and the note title will show as **Note**.

<Tip>
  Use values that match your integration contract (refer to the [visitTypes](/web-sdk/api-reference/types/ambient-options#param-visit-type) reference for more information on
  available enum values). For the full **`ambientOptions`** available parameters, refer to the [AmbientOptions](/web-sdk/api-reference/types/ambient-options) reference guide.
</Tip>

## Response structure

When a note is successfully submitted, you receive a response object with the following structure:

```json JSON theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
{
  "noteId": "82467ba8-71bc-46e2-8232-20d4d5629973",
  "encounterId": "encounter-12345",

"contents": [
    {
      "title": "History",
      "content": "The patient is a 50-year-old female who has been experiencing fever for the last 10 days...",
      "loinc_code": "18233-4",
      "diagnosis": null
    },
    {
      "title": "Review of Systems",
      "content": "- No additional symptoms or pertinent negatives discussed during the encounter.",
      "loinc_code": "10164-2",
      "diagnosis": null
    },
    {
      "title": "Assessment and Plan",
      "content": "Viral hepatitis B with hepatic coma",
      "loinc_code": "51847-2",
      "diagnosis": {
        "icdCode": "B19.11",
        "icdDescription": "Unspecified viral hepatitis B with hepatic coma",
        "snomedCode": "26206000",
        "snomedDescription": "Hepatic coma due to viral hepatitis B",
        "hccCode": "HCC-1",
        "panelRanking": 1,
        "billable": true,
        "problemLabel": "Unspecified viral hepatitis B with hepatic coma"
      }
    }
  ],
  "orders": { // [!code ++:6] New in v3.2.0
    "medication_orders": {
      "values": [],
      "partial_values": []
    }
  }
}
```

### Response fields

<ResponseField name="noteId" type="string">
  Unique identifier for the generated note
</ResponseField>

<ResponseField name="encounterId" type="string">
  Unique identifier for the encounter associated with the note
</ResponseField>

<ResponseField name="contents" type="Array<NoteContent>">
  Array of note sections. Each section contains:

* `title`: Section title (e.g., "History of Present Illness")
  * `content`: Section content in plain text
  * `loinc_code`: LOINC code for the section (optional)
  * `diagnosis`: Diagnosis information if applicable (optional). Refer to [Diagnosis](/web-sdk/api-reference/types/diagnosis) for complete structure.
</ResponseField>

<ResponseField name="orders" type="object">
  Structured orders returned when medication orders are enabled. Refer to [Medication orders JSON schema](/web-sdk/medication-orders/payload-structure) for field definitions.
</ResponseField>

<Note>
  **`orders`** is included only when Medication orders are enabled for your organization and you pass the Medications LOINC code **`52471-0`** in `ambientOptions.sections`. Refer to [Medication orders integration](/web-sdk/medication-orders/overview) to configure medication orders.
</Note>

For complete type definitions, refer to [NoteContent](/web-sdk/api-reference/types/note-content) and [Diagnosis](/web-sdk/api-reference/types/diagnosis).

## Next steps

<Icon icon="file-lines" /> Learn about [Token refresh](/web-sdk/guides/token-refresh) to keep sessions alive

<Icon icon="file-lines" /> Explore [Error handling](/web-sdk/guides/error-handling) for note submission failures

# Telehealth
Source: https://developer.suki.ai/web-sdk/guides/telehealth

Learn how to enable the telehealth feature in the Suki Web SDK

<span>Quick summary</span>
  </div>

<div>
    Telehealth sessions allow you to capture audio from different tabs on a browser window for remote patient care. This feature is opt-in and disabled by default.

<br />

The Web SDK supports audio capture from different tabs in the same browser window (with or without a headset), but does not support audio capture from local or native desktop applications like standalone Zoom or Teams apps.
  </div>

<span>Last updated:</span>
    <span>May 2026</span>
  </div>
</div>

Telehealth sessions are a special type of ambient session that you can use for remote patient care. The Suki Web SDK (version `2.1.0` and later) supports capturing audio from different tabs directly from your browser.

<Note>
  **Compatibility**:

* **Supported**: Audio capture from different tabs in the same browser window (with or without a headset).

* **Not Supported**: Audio capture from local or native desktop applications (e.g., a standalone Zoom or Teams app).
</Note>

## How to enable the Telehealth Audio Capture feature

Enable the Telehealth Audio Capture feature in the Suki Web SDK UI.

<Note> Telehealth Audio Capture feature is an **opt-in setting** and is **disabled by default**.</Note>

To enable Telehealth Audio Capture feature, follow these steps:

<Steps>
  <Step title="Navigate to Settings">
    In the Suki Web SDK UI, navigate to the **Ambient Settings** option.

<Step title="Turn on Capture Telehealth Audio">
    Turn on the **Capture Telehealth Audio** toggle button.

## How it works

When you enable Telehealth Audio Capture and click Start Ambient or Re-Ambient, the SDK prompts you to share your screen.

<Note>
  You must select the browser tab that contains your telehealth call.
</Note>

<Tip>
  In the browser's share modal, you must also select the **Also Share Tab Audio** (or similar) checkbox.
</Tip>

### Session behavior

The following are the different states of the ambient session when telehealth audio capture is enabled:

<CardGroup>
  <Card title="On Pause" icon="pause">
    If you close the shared tab or click the browser's **Stop Sharing** button, the ambient session will automatically pause.
  </Card>

<Card title="On Resume" icon="play">
    To restart the session, click **Resume** in the SDK. This action will open the browser's share modal again.
  </Card>
</CardGroup>

<Card title="On Window/Screen Selection" icon="window">
  The SDK uses experimental browser APIs to capture audio. While you must share a tab, selecting a window or screen by mistake should not result in an error.
</Card>

## Recommendations for partners

For the best compatibility and performance, follow these recommendations:

* Use the latest version of Google Chrome.

* Use browser-based telehealth workflows.

* When you use the browser's `Share screen` modal, you may see an option to share system audio if you select a specific window or your entire screen.

<Warning>
  Suki does not officially support sharing **system audio**. While these options may appear and might be experimentally available in different browsers or operating systems, they are inconsistent and may not function correctly.
</Warning>

Suki only supports sharing **tab audio**. You must ensure that you select a browser tab and enable the tab audio option when prompted.

## Error handling

<Accordion title="Ambient failed to start">
  **Cause**:
  This error occurs if you did not select the Also Share Tab Audio checkbox in the browser's share modal. The SDK requires the tab's audio stream to function.

**Solution**:
  Start the ambient session again. In the share modal, make sure you select the correct browser tab and enable the `Also Share Tab Audio` option.
</Accordion>

## Next steps

<Icon icon="file-lines" /> Refer to [Branding](/web-sdk/guides/branding) guide to learn more about how to brand the Suki Web SDK.

# Token Refresh
Source: https://developer.suki.ai/web-sdk/guides/token-refresh

Learn how to implement automatic token refresh for the Suki Web SDK

<span>Quick summary</span>
  </div>

<div>
    The SDK automatically handles access token refreshes to ensure uninterrupted access to Suki services. It monitors the token's expiration time and refreshes it in the background before it expires using the `partnerToken` you provided during initialization.

<br />

Update the `partnerToken` at runtime by calling the `setPartnerToken` method without requiring re-authentication.
  </div>

<span>Last updated:</span>
    <span>June 2026</span>
  </div>
</div>

This guide explains how to implement automatic token refresh for the Suki Web SDK.

## Authentication & token exchange

The Suki Platform uses a **token exchange mechanism** to securely authenticate and authorize your access to the SDK. Refer to [Partner authentication](/documentation/partner-authentication) guide for more information.

When you initialize the SDK, you must provide a `partnerToken` (which you receive from the EHR system). The SDK exchanges this `partnerToken` with the Suki Platform to get a **Suki access token**. All subsequent API calls use this Suki access token for authorization.

### Automatic token refresh

The SDK automatically handles access token refreshes to ensure you have uninterrupted access to Suki services. It monitors the token's expiration time and refreshes it in the background before it expires.

This process is fully automatic and uses the `partnerToken` you provided during initialization.

### Constraints

<Warning>
  **Important:**

* For the automatic refresh to succeed, the `partnerToken` you provided must still be **valid** at the time of the refresh. If your `partnerToken` expires, the SDK cannot get a new Suki access token, and API calls will fail.
  * Update the `partnerToken` at runtime by calling the `setPartnerToken` method; no re-authentication is required.
</Warning>

## Example

Here's how to update the token at runtime:

<View title="JavaScript" icon="js">
  ```js JavaScript theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
  // whenever the access token is refreshed, call `setPartnerToken` with the new token
  sdkClient.setPartnerToken("new-partner-token");
  ```
</View>

const MyComponent = ({ token }) => {
    const { setPartnerToken } = useSuki();

useEffect(() => {
      // whenever the access token is refreshed, call `setPartnerToken` with the new token
      setPartnerToken(token);
    }, [setPartnerToken, token]); // token is the new partner token you want to set

return <div>App Content</div>;
  };
  ```
</View>

## Next steps

<Icon icon="file-lines" /> Refer to [Telehealth](/web-sdk/guides/telehealth) guide to learn more about how Suki manages telehealth sessions.

# Web SDK Installation
Source: https://developer.suki.ai/web-sdk/installation

Install Suki.js Web SDK in your JavaScript or React application

<Callout title="Updates" icon="bell">
  **From Web SDK `v3.0.0+`:** You need `@suki-sdk/core` for `SukiAuthManager` for authenticating the Suki Web SDK.
</Callout>

We have modularized the Suki Web SDK into **framework-specific packages** so you only need to install the one that fits your environment.

The SDK is built for modern JavaScript and requires an [ES6 compatible browser](https://caniuse.com/?search=es6).

## Prerequisites

For the rest of this documentation, we will assume you have completed the [Partner onboarding](/documentation/partner-onboarding) process and that:

* You have received your `partnerId` from Suki

* Your partner configuration includes a valid [JWKS endpoint](/documentation/partner-authentication)

* Your authentication token contains the correct user identifier (e.g., `sub`, `email`)

## Install the package

### For plain JavaScript

Use the `@suki-sdk/js` package for plain JavaScript projects or with frameworks like **Vue**, **Angular**, or **Solid.js**. This package provides the core SDK functionality without tying it to a specific UI library.

To install the package, run one of the following commands:

<CodeGroup title="Install the @suki-sdk/js package">
  ```shell pnpm theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
  # [!code --:1] Removed in v3.0.0
  # pnpm add @suki-sdk/js
  # [!code ++:1] New in v3.0.0
  pnpm add @suki-sdk/js @suki-sdk/core
  ```

```shell npm theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
  # [!code --:1] Removed in v3.0.0
  # npm install @suki-sdk/js
  # [!code ++:1] New in v3.0.0
  npm install @suki-sdk/js @suki-sdk/core
  ```

```shell yarn theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
  # [!code --:1] Removed in v3.0.0
  # yarn add @suki-sdk/js
  # [!code ++:1] New in v3.0.0
  yarn add @suki-sdk/js @suki-sdk/core
  ```
</CodeGroup>

### For React

For React applications, you should use the `@suki-sdk/react` package. It includes React-specific hooks and components that make it easy to integrate Suki's functionality into your application.

To install the package, run one of the following commands:

<CodeGroup title="Install the @suki-sdk/react package">
  ```shell pnpm theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
  # [!code --:1] Removed in v3.0.0
  # pnpm add @suki-sdk/react
  # [!code ++:1] New in v3.0.0
  pnpm add @suki-sdk/react @suki-sdk/core
  ```

```shell npm theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
  # [!code --:1] Removed in v3.0.0
  # npm install @suki-sdk/react
  # [!code ++:1] New in v3.0.0
  npm install @suki-sdk/react @suki-sdk/core
  ```

```shell yarn theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
  # [!code --:1] Removed in v3.0.0
  # yarn add @suki-sdk/react
  # [!code ++:1] New in v3.0.0
  yarn add @suki-sdk/react @suki-sdk/core
  ```
</CodeGroup>

<Note>
  **Web SDK v3:** You need `@suki-sdk/core` for `SukiAuthManager`. See [Migrating to Web SDK v3](/web-sdk/product-updates/migration-to-v3) if you are upgrading from v2.
</Note>

## Next steps

<Icon icon="file-lines" /> Read the [Quickstart guide](/web-sdk/quickstart) to get started with the Suki SDK.

# Medication Orders Error Codes
Source: https://developer.suki.ai/web-sdk/medication-orders/error-codes

Learn how to handle errors and exceptions during Medication orders generation in the Headed Web SDK

<span>Quick summary</span>
  </div>

<div>
    Medication orders use <code>ORD\_SDK\_\*</code> error codes when generation fails or when one or more orders are missing required fields. Listen for Web SDK <code>error</code> events and inspect <code>error.code</code> to handle errors during Medication orders generation effectively.
  </div>

<span>Last updated:</span>
    <span>June 2026</span>
  </div>
</div>

The Headed Web SDK uses **`ORD_SDK_*`** error codes to identify errors during Medication orders generation.
This guide lists each code, its name, and when it applies so you can handle errors during Medication orders generation effectively.

## Medication orders error codes

The table below is the reference for Medication orders error codes, names, and descriptions.

## Handling Medication orders errors

Subscribe to the `error` event on `SukiClient` (JavaScript) or through the `useSuki()` hook (React). Check `error.code` for `ORD_SDK_*` values. For how to subscribe to SDK errors, refer to [Error handling](/web-sdk/guides/error-handling#listening-for-errors).

const { on } = useSuki();

useEffect(() => {
    const unsubscribe = on("error", (error) => {
      switch (error.code) {
        case "ORD_SDK_001":
          console.error("Order generation failed for the session:", error);
          break;
        case "ORD_SDK_003":
          console.error("Incomplete medication order:", error);
          break;
        default:
          break;
      }
    });

return () => unsubscribe();
  }, [on]);
  ```
</View>

## Next steps

<Icon icon="file-lines" /> [Medication orders overview](/web-sdk/medication-orders/overview)

<Icon icon="file-lines" /> [Medication orders payload structure](/web-sdk/medication-orders/payload-structure)

# Medication Orders Interoperability
Source: https://developer.suki.ai/web-sdk/medication-orders/interoperability

Learn how Web SDK Medication orders align with Ambient API structured data for shared ingestion and EHR mapping

<span>Quick summary</span>
  </div>

<div>
    Web SDK Medication orders and Ambient API structured data use the same Medication order object shape. If you use both workflows, you can reuse parsers, validators, and EHR mapping logic for complete and incomplete Medication orders.
  </div>

<span>Last updated:</span>
    <span>June 2026</span>
  </div>
</div>

The Headed Web SDK returns Medication orders when a provider submits a note. Ambient APIs return Medication orders through structured data responses. Both workflows use the same Medication order object shape, which helps you reuse ingestion, validation, and EHR mapping logic across Web SDK and API workflows.

This guide describes where Medication orders appear in each payload, how to use a shared ingestion pattern, which responsibilities belong to each workflow, and where to find related metadata references.

<Note>
  For the full payload structure of Medication orders in the Web SDK, refer to [Medication orders payload structure](/web-sdk/medication-orders/payload-structure).
</Note>

<Tip>
  This guide explains how the Web SDK and Ambient APIs return Medication orders. If your workflow uses both, contact Suki so we can help confirm the right setup for your integration.
</Tip>

## Payload alignment

The Web SDK and Ambient API place Medication orders in different parts of the response. The fields inside each Medication order are the same, so you can parse the order details the same way.

<CardGroup>
  <Card title="Web SDK Note Submission Payload" icon="globe">
    Read complete orders from **`orders.medication_orders.values`** and incomplete orders from **`orders.medication_orders.partial_values`**.
  </Card>

<Card title="Ambient API Structured Data" icon="code">
    Read complete orders from **`structured_data.orders.medication_orders.values`** and incomplete orders from **`structured_data.orders.medication_orders.partial_values`**.
  </Card>
</CardGroup>

You can retrieve Ambient API structured data from these endpoints:

<CardGroup>
  <Card title="Get Ambient Session Structured Data" icon="code" href="/api-reference/ambient-content/structured-data">
    Retrieve structured data for an ambient session.
  </Card>

<Card title="Get Encounter Structured Data" icon="code" href="/api-reference/ambient-content/encounter-structured-data">
    Retrieve structured data for an encounter.
  </Card>
</CardGroup>

## Shared ingestion pattern

If your application receives Medication orders from both the Headed Web SDK and Ambient APIs, you do not need two separate parsers for the order details. Read the order arrays from the correct response path, then pass each order object into the same parser, validator, or EHR mapping logic.

```mermaid actions={false} theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
flowchart LR
    A[Web SDK note submission] --> C[Shared medication order parser]
    B[Ambient API structured data] --> C
    C --> D[Your EHR or downstream system]

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

We recommend using the following approach for parsing Medication orders:

<Steps>
  <Step title="Read orders from the response">
    Use the Web SDK or Ambient API response path to read complete orders from **`values`** and incomplete orders from **`partial_values`**.
  </Step>

<Step title="Parse each order the same way">
    After you read the order arrays, parse each order object using the same Medication order field definitions, such as `drug_name`, `medication_code`, `dosage`, and `linked_diagnosis_codes`.
  </Step>

<Step title="Handle complete and incomplete orders separately">
    Send orders from **`values`** through your completed order workflow. Send orders from **`partial_values`** to manual review or additional handling.
  </Step>

<Step title="Validate metadata">
    Use [Orders Info API](/api-reference/info/orders) and related info endpoints to validate enums, such as status, frequency, and origin.
  </Step>
</Steps>

## Web SDK and Ambient API responsibilities

The Web SDK and Ambient APIs return aligned Medication order data, but each workflow has a different responsibility in your integration.

| Topic                           | Web SDK                                                                                              | Ambient API                                                                                                                           |
| :------------------------------ | :--------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------ |
| **Order generation trigger**    | LOINC **`52471-0`** in `ambientOptions.sections` and the **`enable_medication_orders`** feature flag | Session context, structured data retrieval, and API configuration documented in [Medication orders](/documentation/medication-orders) |
| **Provider review**             | Built-in **Medication orders** section in the note UI                                                | Your application UI                                                                                                                   |
| **Payload delivery**            | `note-submission:success` / `onNoteSubmit`                                                           | GET structured data endpoints                                                                                                         |
| **EHR submission**              | Partner application                                                                                  | Partner application                                                                                                                   |
| **Existing medication context** | The Web SDK focuses on generating and returning orders from the ambient session                      | Send existing medication orders through the [Context API](/api-reference/ambient-sessions/context)                                    |

## Context ingest on the API

When you use the Ambient API, you can send existing medication orders through the [Context API](/api-reference/ambient-sessions/context). Suki uses that context to reconcile and deduplicate against generated output.

The Web SDK does not replace the Context API. In the Web SDK flow, Medication orders are generated from the ambient session and returned in the note submission payload.

<Note>
  **Important**

If your integration uses both Web SDK and Ambient API workflows for the same encounter, keep the encounter identifiers and Web SDK LOINC configuration consistent.
</Note>

## Metadata and validation

Use the same metadata references when you validate or map Medication order fields:

<CardGroup>
  <Card title="Orders Metadata API" icon="prescription" href="/api-reference/info/orders">
    Reference coding systems, units, frequencies, and other order metadata.
  </Card>

<Card title="Medication Orders API Guide" icon="book" href="/documentation/medication-orders">
    Review platform-level details for EHR validation, PBC linking, and API reconciliation.
  </Card>
</CardGroup>

## FAQs

<Accordion title="What is the difference between the Web SDK and Ambient API Medication orders?">
  Both the Web SDK and Ambient REST APIs return Medication orders in the same object shape. The main difference is how the orders are generated and returned.

* The Web SDK generates orders from the ambient session and returns them in the note submission payload.
  * The Ambient REST APIs retrieve existing orders from the EHR and return them in the structured data response.
</Accordion>

<Accordion title="How do I validate Medication orders using REST APIs?">
  Use the [Orders Info API](/api-reference/info/orders) and related info endpoints to validate enums, such as status, frequency, and origin.
</Accordion>

<Accordion title="In Web SDK, how do I enable Medication orders?">
  Pass the LOINC code **`52471-0`** in `ambientOptions.sections` and the **`enable_generated_orders`** feature flag to enable Medication orders in the Web SDK.
</Accordion>

## Best practices

## Next steps

<Icon icon="file-lines" /> Refer to [Medication orders overview](/web-sdk/medication-orders/overview) to enable Medication orders in your Web SDK integration.

<Icon icon="file-lines" /> Refer to [Medication orders payload structure](/web-sdk/medication-orders/payload-structure) for the full field list.

<Icon icon="file-lines" /> Refer to [Get Ambient Session Structured Data](/api-reference/ambient-content/structured-data) to retrieve structured data for a session.

<Icon icon="file-lines" /> Refer to [Get Encounter Structured Data](/api-reference/ambient-content/encounter-structured-data) to retrieve structured data for an encounter.

# Medication Orders Overview
Source: https://developer.suki.ai/web-sdk/medication-orders/overview

Learn how Medication orders work in the Headed Web SDK, key benefits, use cases, and how to enable this capability

<span>Quick summary</span>
  </div>

<div>
    Medication orders in the Headed Web SDK generate structured medication lists from an ambient session and display them in the built-in Medication orders note section UI of the Headed Web SDK note page.
    To enable this capability, add the LOINC code `52471-0` in the `ambientOptions.sections` array. After the provider submits the note, the SDK returns an orders JSON payload that your application can send to the EHR.
  </div>

<span>Last updated:</span>
    <span>June 2026</span>
  </div>
</div>

The Suki Web SDK now natively supports Medication orders generation during ambient clinical sessions. During an ambient session, the Web SDK identifies recommended medications from the clinician's conversation, links them to active problems in the note, and displays them in the built-in **Medication orders** section for review.

Providers review the orders directly within the user interface and then submit the note. When the provider submits the note, the Suki Web SDK returns structured order data within the standard note submission payload.

<Note>
  **Configuration required**

To enable the Medication orders capability, you must provide the LOINC code `52471-0` in the `ambientOptions.sections` array. Learn more in [Enable Medication orders](#enable-medication-orders).
</Note>

## Prerequisites

Before enabling Medication orders, confirm the following:

* **Problems in the session** - To link orders to problems in the note, enable [Problem-Based Charting (PBC)](/web-sdk/guides/ambient-problem-based-charting) by passing an Assessment & Plan, Assessment, or Plan LOINC section and marking one section with `isPBNSection: true`.
* **Ambient session** - Create and start an ambient session using [Create session](/web-sdk/guides/ambient-implementation).

## Payload structure

After the provider reviews the orders and submits the note, the Web SDK returns the generated `orders` object in the standard note submission payload. The JSON response body includes the following parameters:

<ResponseField name="orders" type="object">
  Structured orders returned on note submission. Includes medication details, dosage instructions, duration, linked problems, and more.
</ResponseField>

<Note>
  The Web SDK does not submit orders directly to the EHR. Your application is responsible for validating and submitting orders to the EHR, the same way you persist note `contents`. Refer to [Medication orders payload structure](/web-sdk/medication-orders/payload-structure) for the note submission payload and field definitions.
</Note>

## Key features

<CardGroup>
  <Card title="Ambient-Based Order Generation" icon="microphone">
    The Web SDK automatically identifies and generates orders from the clinician's spoken conversation during an ambient clinical session.
  </Card>

<Card title="Built-in Review UI" icon="user">
    Providers review and complete generated orders within a dedicated, built-in section on the clinical note page.
  </Card>

<Card title="Inline Validation for Missing Fields" icon="file-text">
    When required ordering data is missing, the Web SDK displays inline dropdown menus within the interface. This allows the provider to complete all necessary details before submitting the final note.
  </Card>

<Card title="Automatic Deduplication" icon="file-text">
    The Web SDK automatically deduplicates generated orders against existing encounter orders from your Electronic Health Record (EHR) pre-charting data. The system removes exact matches based on medication name, form, and strength before displaying the list to the provider.
  </Card>

<Card title="Problem-Based Linking" icon="file-text">
    Providers can associate a medication order directly with a specific problem section within the clinical note when you enable Problem-Based Charting (PBC).
  </Card>

<Card title="Simple Configuration via LOINC" icon="file-text">
    You can activate this feature for any clinical session. To turn on Medication orders, pass the LOINC code `52471-0` in the `ambientOptions.sections` array.
  </Card>

<Card title="Structured JSON Payload" icon="file-text">
    The Web SDK returns the orders in the same note submission payload as `noteId`, `encounterId`, and `contents` so you can parse and save the data to your EHR easily.
  </Card>
</CardGroup>

## Use cases

Use Medication orders for the following Web SDK workflows:

<CardGroup>
  <Card title="Ambient Medication Orders Generation" icon="prescription">
    A provider wants to automatically generate medication orders purely from their clinical conversation during a standard ambient session. Pass the LOINC code `52471-0` in the `ambientOptions.sections` array when initializing the session.

The Web SDK identifies the mentioned medications, generates the list, and displays them in the Medication orders section. When the provider selects submit, the Web SDK delivers structured JSON data in your note submission payload.
  </Card>

<Card title="Incomplete Orders Handling" icon="file-text">
    A generated medication order is missing required clinical infrastructure data, such as a specific **RxCUI code** or a **linked diagnosis**. The Web SDK flags the omission and displays inline dropdown menus directly within the Medication orders interface.

The provider uses the dropdowns to finish the order before submitting. Upon submission, your application receives the orders data: fully completed orders arrive in the `values` array, while any remaining incomplete orders arrive in the `partial_values` array.
  </Card>

<Card title="Problem-Based Charting with Orders" icon="file-text">
    A clinic uses Problem-Based Charting (PBC) and wants providers to explicitly link new medication orders to active patient problems during the ambient session. Pass a PBC configuration object containing `isPBNSection: true` alongside the LOINC code `52471-0` in the same sections array.

The Web SDK generates both problem sections and medication orders simultaneously. The provider can then visually associate a medication order with a specific problem section directly in the user interface before submitting.
  </Card>

<Card title="Session Re-Ambienting and Updates" icon="file-text">
    A provider needs to restart or rerun the ambient recording feature within an encounter that already contains generated medication orders. The provider initiates a re-ambient session. The Web SDK automatically reviews the entire existing note context, including the previously generated orders, during its regeneration process.

The SDK returns an updated payload. Your application must be configured to either replace or merge this new payload with the prior order state for that encounter within your EHR workflow.
  </Card>
</CardGroup>

## Enable Medication orders

To enable the Medication orders capability in the Suki Web SDK, pass the LOINC code `52471-0` in the `ambientOptions.sections` array. You can pass this parameter when you mount the Web SDK or when you call the `AmbientOptions` method. The section name displays as **Medication** in the user interface.

### Test Medication orders

To test this feature in the Web SDK Playground, navigate to the **Ambient** tab and add `{ "loinc": "52471-0" }` to the **Sections** field.

<Tip>
  For a full list of supported clinical note sections, refer to [Note sections](/documentation/note-sections).
</Tip>

***

***

Alternatively, you can configure this directly in your application code using the following code configurations:

<Note>
  Combine the LOINC code `52471-0` with your other note sections and a PBC section when you need Problems in the same session.
</Note>

## Provider workflow

After the ambient session completes, the Web SDK displays a **Medication section** on the clinical note page. If you enable Problem-Based Charting (PBC), this section appears below the problem sections.
This user interface is built directly into the headed Web SDK note page.

During the review process, providers can perform the following actions:

* **Review medications from the visit:** View medication orders that the Web SDK generates from the ambient session clinical conversation.
* **Link orders to problems:** Use the problem selector to associate a medication order with a specific problem section in the note.
* **Complete missing fields inline:** Use inline dropdown menus within the Medication orders section to fill in missing required data.
* **Submit the note:** Select the submit button to send the note. When the provider submits the note, the SDK returns the note contents and structured order data directly to your application.

### Inline editing

Each generated medication order can include an [RxNorm RxCUI](https://www.nlm.nih.gov/research/umls/rxnorm/overview.html) value in the `medication_code` parameter. The presence of this code determines whether a provider can edit the order details inline:

| RxCUI status on the order | Provider can edit the order inline |
| :------------------------ | :--------------------------------- |
| **Present**               | No                                 |
| **Missing or empty**      | Yes                                |

<Note>
  Non-edit workflow
  The Web SDK uses a non-edit workflow by default. The interface does not include a full-screen editing panel. Providers must complete all missing fields using the inline controls within the Medication orders section.
</Note>

## Error handling

If order generation fails or orders are missing required fields, the Web SDK returns the **`ORD_SDK_001`** or **`ORD_SDK_003`** error codes. Refer to [Medication orders error codes](/web-sdk/medication-orders/error-codes) for the error codes and descriptions.

## Next steps

<Icon icon="file-lines" /> Learn about the [Medication orders payload structure](/web-sdk/medication-orders/payload-structure) to parse and save orders to your EHR.

<Icon icon="file-lines" /> Learn about the [Medication orders error codes](/web-sdk/medication-orders/error-codes) to handle errors during Medication orders generation.

<Icon icon="file-lines" /> Learn about [Problem-Based Charting](/web-sdk/guides/ambient-problem-based-charting) to enable Problem-Based Charting (PBC) in your Web SDK integration.

# Medication Orders Payload Structure
Source: https://developer.suki.ai/web-sdk/medication-orders/payload-structure

Learn about the Medication orders JSON payload structure returned on Web SDK note submission

<span>Quick summary</span>
  </div>

<div>
    The Medication orders payload structure includes multiple fields under the `orders` object. Understand the available fields that you receive in the Medication orders payload to parse and save orders to your EHR.
  </div>

<span>Last updated:</span>
    <span>June 2026</span>
  </div>
</div>

The Headed Web SDK returns Medication orders when a provider submits a note. The note submission payload includes `medication_orders` under `orders`, along with `noteId`, `encounterId`, and `contents`.

This guide describes the Medication orders payload structure and explains each field in a Medication order object.

<Note>
  Refer to [Medication orders overview](/web-sdk/medication-orders/overview) for instructions to enable Medication orders in your Web SDK integration.
</Note>

## Medication orders payload

When you submit a note, the Headed Web SDK returns a **note submission payload** after it successfully submits the note. The payload includes `noteId`, `encounterId`, and `contents`.

If you enable Medication orders, the payload also includes the `orders` object. Medication details are available in `orders.medication_orders`.

You can receive the payload using either of the following methods:

* **`onNoteSubmit` prop** (React only, recommended)
* **`note-submission:success` event** (React and JavaScript)

Refer to [Receiving note content](/web-sdk/guides/note-management#receiving-note-content) in Note management for how to handle note sections and the full response structure.

**Example schema:**

```json JSON theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
{
  "noteId": "82467ba8-71bc-46e2-8232-20d4d5629973",
  "encounterId": "encounter-12345",
  "contents": [],
  "orders": {
    "medication_orders": {
      "values": [],
      "partial_values": []
    }
  }
}
```

The note submission payload includes the `orders` object when you enable Medication orders in your Web SDK integration.

<Note>
  To enable Medication orders, pass the Medications LOINC code `52471-0` in `ambientOptions.sections`. Refer to [Medication orders overview](/web-sdk/medication-orders/overview) for instructions to enable Medication orders in your Web SDK integration.
</Note>

<ResponseField name="orders" type="object">
  Structured orders returned on note submission. For Medication orders, read **`orders.medication_orders`** with **`values`** and **`partial_values`**.
</ResponseField>

<Note>
  For **`noteId`**, **`encounterId`**, and **`contents`**, refer to [Response fields](/web-sdk/guides/note-management#response-fields) in Note management.
</Note>

## Medication order payload structure

The example below shows the payload structure for a single Medication order object.

```json JSON theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
{
  "drug_name": "Lisinopril",
  "medication_code": {
    "type": "RXCUI",
    "code": "314076"
  },
  "dosage": {
    "raw_value": "1 tablet",
    "quantity": 1,
    "unit": "TAB"
  },
  "frequency": {
    "raw_value": "Once daily",
    "structured_value": "ONE_A_DAY"
  },
  "instructions": "Take one tablet by mouth once daily",
  "medication_timing": {
    "raw_value": "In the morning",
    "structured_value": "IN_THE_MORNING"
  },
  "strength": {
    "raw_value": "10mg"
  },
  "format": {
    "raw_value": "Tablet"
  },
  "route": {
    "raw_value": "By mouth"
  },
  "linked_diagnosis_codes": [
    {
      "type": "ICD10",
      "code": "I10"
    }
  ],
  "number_of_refills": 3,
  "start_date": "2024-01-15T00:00:00Z",
  "end_date": "2024-04-15T00:00:00Z",
  "duration_in_days": 90,
  "status": "REFILLED",
  "metadata": {
    "origin": "EMR",
    "encounter_relation": "CURRENT_ENCOUNTER"
  }
}
```

## Available fields

Each field in a Medication order object can have the following values. Use these fields to parse the Medication orders payload and save orders to your EHR.

<Expandable title="Medication order fields">
  <ResponseField name="drug_name" type="string">
    Full medication name (for example `Lisinopril`). This field is required when Medication orders are enabled in your Web SDK integration.
  </ResponseField>

<ResponseField name="medication_code" type="object">
    Standardized medication identifier.

* **`type`:** Coding system (for example `RxCUI`). If this is present, you **cannot edit** the medication value in the Web SDK UI.
    * **`code`:** Code value.
  </ResponseField>

<ResponseField name="dosage" type="object">
    Amount per administration.

* **`raw_value`:** Human-readable dosage string. For example `1 tablet`.
    * **`quantity`:** Numeric quantity when structured. For example `1`.
    * **`unit`:** Unit code (for example `TAB`).
  </ResponseField>

<ResponseField name="frequency" type="object">
    Administration frequency.

* **`raw_value`:** Human-readable frequency.
    * **`structured_value`:** Structured value (for example `ONE_A_DAY`).
  </ResponseField>

<ResponseField name="instructions" type="string">
    Free-form sig or patient instructions.
  </ResponseField>

<ResponseField name="medication_timing" type="object">
    Timing modifiers.

* **`raw_value`:** Human-readable timing. For example `In the morning`.
    * **`structured_value`:** Structured value. For example `IN_THE_MORNING`.
  </ResponseField>

<ResponseField name="strength" type="object">
    Medication strength. Includes **`raw_value`**. For example `10mg`.
  </ResponseField>

<ResponseField name="format" type="object">
    Dosage form. Includes **`raw_value`**. For example `Tablet`.
  </ResponseField>

<ResponseField name="route" type="object">
    Route of administration. Includes **`raw_value`** (for example `By mouth`).
  </ResponseField>

<ResponseField name="linked_diagnosis_codes" type="array">
    Diagnoses linked to the order. Each entry includes **`type`** (for example `ICD10`) and **`code`**.
  </ResponseField>

<ResponseField name="number_of_refills" type="integer">
    Number of refills when specified.
  </ResponseField>

<ResponseField name="start_date" type="string">
    Start date-time in RFC3339 format. For example `2026-01-01T00:00:00Z`.
  </ResponseField>

<ResponseField name="end_date" type="string">
    End date-time in RFC3339 format.
  </ResponseField>

<ResponseField name="duration_in_days" type="integer">
    Duration in days when specified.
  </ResponseField>

<ResponseField name="status" type="string">
    Order status: **`ACTIVE`**, **`DISCONTINUED`**, or **`REFILLED`**.
  </ResponseField>

<ResponseField name="metadata" type="object">
    Provenance for the order.

* **`origin`:** `EMR` or `SUKI_AMBIENT`.
    * **`encounter_relation`:** `CURRENT_ENCOUNTER` or `PRIOR_ENCOUNTER` when **`origin`** is `EMR`.

<Note>
      When origin is `EMR`, the `encounter_relation` field is **required**.
    </Note>
  </ResponseField>
</Expandable>

## Example code

The example code below shows how to parse the Medication orders payload and save orders to your EHR.

<View title="JavaScript" icon="js">
  ```js JavaScript theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
  const unsubscribe = sdkClient.on("note-submission:success", (payload) => {
    console.log("Note ID:", payload.noteId);
    console.log("Encounter ID:", payload.encounterId);

const medOrders = payload.orders?.medication_orders ?? {};
    const values = medOrders.values ?? [];
    const partialValues = medOrders.partial_values ?? [];

values.forEach((order) => {
      console.log("Order:", order.drug_name, order.status);
    });

partialValues.forEach((order) => {
      console.log("Partial order:", order.drug_name);
    });
  });
  ```
</View>

<View title="React" icon="react">
  ```jsx React theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
  import { useCallback } from "react";

const handleNoteSubmit = useCallback((payload) => {
    const medOrders = payload.orders?.medication_orders ?? {};
    const values = medOrders.values ?? [];
    const partialValues = medOrders.partial_values ?? [];

values.forEach((order) => {
      saveOrderToEhr(order);
    });

partialValues.forEach((order) => {
      queueForManualReview(order);
    });
  }, []);

return <SukiAssistant onNoteSubmit={handleNoteSubmit} />;
  ```
</View>

## Best practices

<Tip>
  * Check for `orders` before you parse it. The object is returned only when Medication orders are enabled.
  * Treat `values` as ready for EHR workflows. Send `partial_values` for manual review or completion.
  * Store `noteId` and `encounterId` with each order batch for tracking and reconciliation.
  * Validate required fields before you submit orders to the EHR.
  * Log the full submission payload to help troubleshoot ingestion issues.
  * Do not assume the Web SDK submits orders. Your application must validate and write orders to the EHR.
  * Handle `ORD_SDK_*` errors during order generation and validation.
</Tip>

## Next steps

<Icon icon="file-lines" /> Refer to [Medication orders overview](/web-sdk/medication-orders/overview) to enable Medication orders in your Web SDK integration.

<Icon icon="file-lines" /> Refer to [Medication orders error codes](/web-sdk/medication-orders/error-codes) to handle errors during medication order generation.

# Minimized Layout Implementation
Source: https://developer.suki.ai/web-sdk/minimized-layout/implementation

Learn about the host responsibilities, layout signals, and validation for minimized ambient layout in the headed Web SDK

When the Suki Web SDK minimizes during ambient capture, the UI transforms into a compact floating widget. Recording and session behavior stay the same; the change is so your application can reclaim screen space for the chart or other primary content.

The SDK remains attached to your original **root element**. In minimized layout the iframe uses **fixed** positioning, so you must **shrink or move your host container** around that mount. If you leave the old reservation in place, you will see a large empty region where the full headed panel used to sit.

This guide outlines **host code** responsibilities versus what the **Web SDK** already handles. For mount placement, overflow, and transform guidance, read the [Minimized layout overview](/web-sdk/minimized-layout/overview).

<Note>
  Minimized layout applies only to the **headed Web SDK**. It requires **Web SDK `3.1.0`** or later.
</Note>

## Layout values from the hosted iframe

The hosted iframe sends one layout value at a time. Treat `minimized` and `minimized-paused` the same in your host layout: both mean the small overlay is active, so you should free the area you reserved for the full headed panel. When the value is `expanded`, give that slot back to the full panel.

| Status                 | Description                                                              | Action                                                                       |
| ---------------------- | ------------------------------------------------------------------------ | ---------------------------------------------------------------------------- |
| **`expanded`**         | The full headed panel is active in your mount slot.                      | Restore your usual width, height, min sizes, and flex rules for that region. |
| **`minimized`**        | The SDK is a small floating widget; ambient capture can still be active. | Collapse or hide your mount wrapper so chart content can expand.             |
| **`minimized-paused`** | The SDK uses minimized chrome while ambient is paused.                   | Collapse the host slot the same way you do for **`minimized`**.              |

## How to implement minimized layout

<Steps>
  <Step title="Initialize and mount">
    Use a **root element** reserved for the iframe, the same as the **`rootElement`** you pass to **`mount`** in **`@suki-sdk/js`**, or the parent tree where you render **`SukiAssistant`** in **`@suki-sdk/react`**.
  </Step>

<Step title="Collapse your mount wrapper">
    When **`layout`** is not **`expanded`**, set **`width`**, **`minWidth`**, **`height`**, and **`minHeight`** to **`0`**, or **hide the column** with flex rules (including **`flex-basis`** when that is what reserves space).
  </Step>

<Step title="Maintain visibility on the mount">
    Keep **`overflow: visible`** on the **mount node** while minimized so the **fixed-position** iframe is not clipped by a scrolling or clipping ancestor.
  </Step>

<Step title="Restore dimensions when expanded">
    When **`layout`** returns to **`expanded`**, restore your normal CSS dimensions or **flex basis** for the headed panel.
  </Step>

<Step title="Reclaim space for core content">
    The iframe **remains a child of your mount node** even when minimized. Because it is **fixed-positioned**, the parent does not need to stay large; your application should **reclaim that space** for core content next to or behind the widget.
  </Step>
</Steps>

<Note>
  **In React**

* The **`SukiAssistant`** component **does not** automatically collapse its container when the SDK minimizes.
  * You must use the **`onLayoutChange`** prop to collapse, hide, or restyle the container in your layout.
</Note>

### Code examples

Subscribe to **`ui:layout-change`** on the **`@suki-sdk/js`** instance after **`initialize`**.

In **`@suki-sdk/react`**, drive a **wrapper** around **`SukiAssistant`** from **`onLayoutChange`** so your slot tracks the SDK (the React sample shows a typical wrapper with inline styles; use classes or tokens in production if you prefer).

<View title="JavaScript" icon="js">
  ```js JavaScript theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
  sdk.on("ui:layout-change", ({ layout }) => {
    // layout: "expanded" | "minimized" | "minimized-paused"
    const mount = document.getElementById("suki-root");

if (layout === "expanded") {
      mount.style.width = "";
      mount.style.minWidth = "";
      mount.style.height = "";
      mount.style.minHeight = "";
    } else {
      mount.style.width = "0";
      mount.style.minWidth = "0";
      mount.style.height = "0";
      mount.style.minHeight = "0";
    }

mount.style.overflow = "visible";
  });
  ```
</View>

<View title="React" icon="react">
  ```tsx React theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
  import { useState } from "react";
  import { SukiAssistant } from "@suki-sdk/react";

// Minimal API: SukiAssistant must receive onLayoutChange; you collapse a parent you own.
  // layout: "expanded" | "minimized" | "minimized-paused"
  // onLayoutChange={(layout) => setIsMinimized(layout !== "expanded")}

export function HostWithSuki({ encounter }) {
    const [isMinimized, setIsMinimized] = useState(false);

return (
      <div
        className="suki-mount-host"
        data-minimized={isMinimized}
        style={
          isMinimized
            ? {
                width: 0,
                minWidth: 0,
                height: 0,
                minHeight: 0,
                overflow: "visible",
              }
            : {
                overflow: "visible",
                // Restore width, height, and flex values your layout uses when expanded.
              }
        }
      >
        <SukiAssistant
          encounter={encounter}
          onLayoutChange={(layout) => {
            // layout: "expanded" | "minimized" | "minimized-paused"
            setIsMinimized(layout !== "expanded");
          }}
        />
      </div>
    );
  }
  ```
</View>

<Warning>
  Without **`onLayoutChange`** (and without applying the same rules on a wrapper you control), a **360×640** (or similar) **invisible block** can remain in your layout even when the SDK is minimized, which displaces chart columns and other host content.
</Warning>

<Tip>
  Prefer class names, design tokens, or layout components instead of inline styles in production; the samples above show the state transition clearly.
</Tip>

## What you do not need to do

* **Iframe sizing:** do not re-implement iframe **width**, **height**, or **positioning**. The **`@suki-sdk/js`** package controls iframe geometry for **expanded** and **minimized** states when minimize is allowed. You only adjust **your** mount container.
* **Space recovery:** if your layout **does not** have an empty slot to reclaim (for example the SDK sits in a **dedicated overlay** and nothing else needs to grow into a reserved column), you can **skip** handling **`ui:layout-change`** for layout recovery. You should still follow [Configure the mount point](/web-sdk/minimized-layout/overview#configure-the-mount-point) on the overview so **fixed** positioning and stacking behave predictably.

## Validate in a test environment

Follow these steps to verify your integration end to end.

<Steps>
  <Step title="Enable the feature">
    To enable the feature for your organization, contact support.
  </Step>

<Step title="Start a session">
    Initiate **ambient** capture from the headed SDK UI or your controlled entry point. When capability and session state allow it, the iframe should become a **small floating widget**.
  </Step>

<Step title="Confirm the layout shift">
    * **In JavaScript:** after **`ui:layout-change`** fires and you **collapse the mount**, your main content should grow into the reclaimed space.

* **In React:** use **`onLayoutChange`** to collapse your container whenever **`layout`** is not **`expanded`**, and confirm the shift matches what you expect.
  </Step>

<Step title="Verify ambient dialogs">
    Confirm that **ambient** dialogs (for example **cancel**, **insufficient context**, and **audio-below-threshold**) appear correctly on the **minimized** surface when the product allows them there.
  </Step>
</Steps>

<Note>
  If you are unsure how minimize is enabled for staging or production, ask your Suki integration contact for the current rollout process.
</Note>

## Troubleshooting

<AccordionGroup>
  <Accordion title="Widget is misplaced or clipped">
    This is usually caused by **`transform`**, **`filter`**, or **`will-change`** on an **ancestor** of the mount. **Relocate** the mount outside transformed or filtered containers, set **`overflow: visible`** on the mount while minimized, and retest.

Read [Avoid transformed ancestors](/web-sdk/minimized-layout/overview#avoid-transformed-ancestors) to learn more about how to avoid this issue.
  </Accordion>

<Accordion title="Chart does not expand when the SDK minimizes">
    Explicitly set **`width`**, **`height`**, **`minWidth`**, **`minHeight`**, or **`flex-basis`** to **zero** (or hide the column) when **`layout`** is not **`expanded`**. Without collapsing, the layout keeps reserving the prior panel size (for example **360×640**). In React, drive that collapse from **`onLayoutChange`**.
  </Accordion>

<Accordion title="Ambient dialogs are hard to see">
    Verify the **feature flag** or **Remote Config** rollout enables minimize for the **user or organization**, and confirm the iframe is not clipped. Check **`z-index`** stacking and **`overflow`** on ancestors.
  </Accordion>
</AccordionGroup>

# Minimized Layout
Source: https://developer.suki.ai/web-sdk/minimized-layout/overview

Learn about the minimized layout, and when it gets enabled for the headed Web SDK in your application

<span>Quick summary</span>
  </div>

<div>
    The Suki Web SDK now supports a minimized layout designed during ambient sessions. This feature transforms the Suki Web SDK UI into a compact, viewport-aligned widget, freeing up screen space so clinicians can focus on the EHR or patient chart
    while Suki Web SDK captures audio in the background. This feature is available from version `3.1.0` and later.
  </div>

<span>Last updated:</span>
    <span>May 2026</span>
  </div>
</div>

**Minimized layout** is an alternate headed UI mode for **ambient** sessions in the headed Web SDK. The hosted Suki iframe shrinks to a small overlay so your application stays the main focus. Recording, pause, cancel, and generate still run through the same session;
only the surface area of the iframe changes to a small overlay.

<Note>
  **Important:**

* This applies only to the <strong>Headed Web SDK</strong>, where Suki runs inside the SDK iframe. It does <strong>not</strong> apply to the <strong>Headless Web SDK</strong>, headless-only apps, or API-only integrations.
  * Minimized layout frees up screen space for the EHR/chart while maintaining ambient awareness.
  * On critical errors, Web SDK automatically re-expands the UI to ensure visibility of required actions.
  * You control the surrounding layout to reclaim space for your own UI. You **do not control** when minimized layout is enabled.
</Note>

## When minimized layout is available

In the headed iframe, auto-minimize runs when the following conditions are met:

* **Ambient and re-ambient:** The minimized surface tracks an active **ambient**-style session in that iframe. It is not a partner-controlled "small UI" mode for non-ambient flows.
* **Minimize capability:** The hosted iframe evaluates policy and runtime constraints for the current user or organization before shrinking. The UI requests minimized layout only when **minimize capability** is on. If it is off, **ambient** stays **expanded** and auto-minimize does not run.

## Where minimized layout helps

Minimized layout helps in the following scenarios:

* **Desk and chart reference (web):** A provider runs an ambient session at the desk; the SDK minimizes so they can read the patient chart, orders, or other partner content while capture continues, including before moving to an exam room.
* **Dense or portrait layouts:** On short, narrow, or vertical viewports, the full headed panel competes with the chart. Minimized mode keeps a small control surface so host UI stays scannable.

<Note>
  When minimize capability is off, the iframe stays **fully expanded** for ambient and partners will not see auto-minimize.
</Note>

## Key features

<CardGroup>
  <Card title="Auto-Minimize" icon="window">
    When **ambient** (or **re-ambient**) **recording** is active and minimize is supported, the UI moves to a small rectangular overlay automatically. No separate partner action is required to shrink the surface.
  </Card>

<Card title="Core Controls on the Widget" icon="sliders">
    From the minimized surface users can **pause** (center), **cancel** (top-left), or **generate notes** (bottom-right) without opening the full headed panel. Cancel still uses the standard confirmation step before ending the session.
  </Card>
</CardGroup>

<Card title="Auto-Expand on Errors" icon="triangle-exclamation">
  On **409 Conflict** (for example session collisions or state locks), the SDK exits minimized layout and returns to the full headed view so the user can complete **Remote Completion** or other recovery UI.
</Card>

## How minimized layout works

Suki turns on **minimize capability** in the hosted configuration for eligible partners and users. On your side, ship a **correct mount** and **reclaim layout space** so the minimized iframe does not leave a large empty slot in your app.

### Configure the mount point

In minimized layout, the SDK draws a small overlay using `position: fixed`. Fixed positioning is resolved against the **nearest containing block**, not always the browser viewport. If that block is wrong, the widget can shift, clip, or disappear.

Follow these rules when you choose the DOM node where the Web SDK mounts.

#### Where to mount

Mount the Web SDK root on a stable, full-viewport ancestor, for example:

* Mount on `document.body`
* A full-height app shell you control (main layout wrapper)
* A side panel that is **not** nested under an element that applies CSS transforms

Prefer a host layout with a **dedicated slot** (for example a flex or grid track) sized for the full headed iframe while expanded, and **collapsible** when minimized so the rest of your UI can grow into the freed space.

<Note>
  Do not mount inside **modals**, **animated drawers**, or other subtrees that sit under transformed or heavily layered stacking ancestors. Those patterns can trap or clip `position: fixed` descendants, misalign the widget to the viewport, or break expected z-order.
</Note>

#### Avoid transformed ancestors

Do not mount the SDK inside subtrees that set `transform`, `filter`, or `will-change` in a way that creates a new containing block for fixed descendants. Those properties create new stacking contexts; `position: fixed` on the iframe may then resolve to the wrong box, which can look like offscreen placement, clipping, or odd layering.

If you cannot move the mount, remove or isolate those properties on ancestors above the mount node.

#### Keep overflow visible

While minimized, set the mount element (and any immediate wrappers you own) to `overflow: visible` so the fixed iframe is not clipped by `overflow: hidden` or `auto` scrollers.

<Tip>
  If your layout normally clips overflow, toggle visibility only around the minimized state, or mount on a sibling outside the scrolling region.
</Tip>

### Reclaim screen space

The SDK sizes and positions the **iframe** for both headed and minimized modes. Your app still owns the **mount container** around that iframe. If that container keeps the same width and height as the full headed panel (often about **360×640** px reserved in your layout), you will see a large empty gap even though the SDK UI is already small.

After minimize, shrink or collapse that container so your grid, flex, or split view can grow into the freed space.

**Recommended approaches**:

* Drop or lower `min-height` / `min-width` on the mount wrapper while minimized.
* Switch the mount slot to `auto` height, a smaller fixed height, or hide a dedicated “SDK column” until the user expands again.

Match the reserved area to the minimized footprint you want, or remove the reservation entirely if the widget is fully `fixed` and does not need layout flow space.

## Next steps

<Icon icon="file-lines" /> Listen for minimize capability from the parent integration and wire mount sizing in code on the [Implementation](/web-sdk/minimized-layout/implementation) page.

# Web SDK Overview
Source: https://developer.suki.ai/web-sdk/overview

A collection of JavaScript & React libraries to build web applications on top of Suki ambient intelligence capabilities with pre-built UI components

The Suki Web SDK provides **pre-built UI components** and **React hooks** that let you seamlessly integrate <Tooltip href="/Glossary/a">ambient</Tooltip> intelligence capabilities directly into your web application.

Because this SDK includes all necessary user interface elements, you can quickly embed Suki's ambient intelligence capabilities without having to design the frontend yourself.

To integrate Suki's AI capabilities, use **Suki.js**, our core **JavaScript/TypeScript SDK**. This package provides the essential methods and events for embedding the Suki Web SDK into your application.

With the Suki Web SDK, you can add features like:

* Ambient note generation
* Medical transcription
* Note management

## Supported platforms

The SDK is supported on the following platforms:

<CardGroup>
  <Card title="React" icon="react">
    The SDK is supported on React.

Install the Suki Web SDK for React:

<div>
      <button>
        <span>Install for React</span>

<span><svg><polyline /></svg> Command Copied!</span>
      </button>
    </div>
  </Card>

<Card title="Vanilla JavaScript" icon="js">
    The SDK is supported on Vanilla JavaScript.

Install the Suki Web SDK for Vanilla JavaScript:

<div>
      <button>
        <span>Install for JavaScript / TypeScript</span>

<span><svg><polyline /></svg> Command Copied!</span>
      </button>
    </div>
  </Card>
</CardGroup>

<Card title="Other Frameworks" icon="angular">
  The SDK is supported on other frameworks like Vue, Angular, etc.
</Card>

<Info>
  While it is optimized for **React**, you can also easily integrate it with **vanilla JavaScript** or other frameworks.
</Info>

## How it works

The following diagram illustrates the Web SDK architecture and workflow:

```mermaid actions={false} theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
%%{init: {'theme':'base', 'themeVariables': { 'primaryColor':'#FFE148','primaryTextColor':'#111827','lineColor':'#6B7280','fontSize':'14px','edgeLabelBackground':'#FFFFFF','tertiaryColor':'#F9FAFB','tertiaryTextColor':'#111827','tertiaryBorderColor':'#D1D5DB'}}}%%
graph TB
    subgraph client["Your web application"]
        direction TB
        A["Application code<br/><small>React / JavaScript / Other Frameworks</small>"]
        B["Suki Web SDK<br/><small>@suki-sdk/js or @suki-sdk/react</small>"]
        C["Pre-built UI<br/><small>Recording • Transcription • Notes</small>"]
        A --> B
        B --> C
    end
    
    subgraph platform["Suki backend"]
        direction TB
        D["Authentication service<br/>"]
        E["Ambient service<br/>"]
        F["AI engine<br/>"]
    end
    
    B -->|Authenticate| D
    C -->|Stream audio| E
    E -->|Process| F
    F -->|Return results| C
    
    style client fill:#FFFADE,stroke:#D1D5DB,stroke-width:2px,color:#111827
    style platform fill:#FFF394,stroke:#FFE148,stroke-width:2px,color:#111827
    style A fill:#ffffff,stroke:#9CA3AF,stroke-width:2px,color:#111827
    style B fill:#FFE148,stroke:#111827,stroke-width:3px,color:#111827
    style C fill:#ffffff,stroke:#9CA3AF,stroke-width:2px,color:#111827
    style D fill:#ffffff,stroke:#9CA3AF,stroke-width:2px,color:#111827
    style E fill:#ffffff,stroke:#9CA3AF,stroke-width:2px,color:#111827
    style F fill:#ffffff,stroke:#9CA3AF,stroke-width:2px,color:#111827
```

### Architecture workflow

<Steps>
  <Step title="Client Side (Your Web Application)" icon="user">
    * Your React, JavaScript, or web app that integrates the SDK
    * Core SDK package that handles authentication, session management, and communication
    * Pre-built UI for recording, transcription, and note display
  </Step>

<Step title="Suki Backend" icon="server">
    * Validates partner credentials (Partner ID and token)
    * Manages audio streaming and processing
    * Processes audio in real-time and generates structured clinical notes
  </Step>

<Step title="Data Flow" icon="arrow-right">
    <Callout>
      1. Initialize SDK with partner credentials → Authenticate with Suki's backend
      2. Mount pre-built UI with encounter data
      3. User starts recording → SDK streams audio to Ambient Service
      4. AI Engine processes audio and generates notes
      5. Results return through Suki Backend → UI displays the note and transcript
    </Callout>
  </Step>
</Steps>

## Key features

<CardGroup>
  <Card title="Ambient Note Generation" icon="file-text">
    The SDK allows you to automatically capture spoken patient encounters and generate structured clinical notes in real time.

<Accordion title="Context-Aware Processing">
      It uses AI to intelligently organize medical conversations into the correct clinical sections.
    </Accordion>

<Accordion title="Smart Formatting">
      It leverages [LOINC codes](/documentation/note-sections) to segment content into sections like `HPI`, `Assessment`, and `Physical Exam`.
    </Accordion>

<Accordion title="Background Processing">
      The feature runs passively in the background during consultations so it does not disrupt the provider's workflow.
    </Accordion>
  </Card>

<Card title="Medical Transcription" icon="microphone">
    Integrate high-accuracy medical transcription that supports specialty-specific terminology and multiple languages and accents.

<Accordion title="Specialty-Specific Terminology">
      The transcription supports specialty-specific terminology.
    </Accordion>

<Accordion title="Multiple Languages and Accents">
      The transcription supports multiple languages and accents.
    </Accordion>
  </Card>
</CardGroup>

<Card title="Note Management" icon="file-text">
  The SDK includes features for managing clinical notes within your application.

<Accordion title="Note Editor">
    A rich-text editor designed specifically for AI-generated clinical content. It supports editing, formatting, and section-level interaction.
  </Accordion>

<Accordion title="Note Archive">
    A feature that allows users to view and manage both current and historical notes associated with a patient.
  </Accordion>
</Card>

## Key benefits

The web SDK provides the following benefits:

<AccordionGroup>
  <Accordion icon="clock" title="Fast Integration">
    Quickly add Suki's features using our built-in UI.
  </Accordion>

<Accordion icon="fast-forward" title="Optimized Performance">
    Built for accuracy and speed in a web environment.
  </Accordion>

<Accordion icon="user" title="Focus on Your Application">
    Let our components handle the Suki UI so your team can focus on your product.
  </Accordion>
</AccordionGroup>

## Next steps

<Icon icon="file-lines" /> Refer to our [Installation guide](/web-sdk/installation) to get started with the Suki SDK.

# Web SDK Prerequisites
Source: https://developer.suki.ai/web-sdk/prerequisites

Requirements and setup needed before integrating the Suki Web SDK

<Callout title="Updates" icon="bell">
  **Web SDK v3.0.0 and later**

Configure auth by creating `SukiAuthManager` from `@suki-sdk/core` with your Partner ID, JWT, and provider details, then pass that manager instance to `initialize()` or `init()` as `authManager`.

For a step-by-step migration, refer to the [Migrating to Web SDK v3](/web-sdk/product-updates/migration-to-v3) guide.
</Callout>

This guide outlines the technical requirements your application must meet to integrate with the Suki Platform web SDK.

## Browser support

Your application must use a browser that is **ES6-compatible**. Check the full compatibility list [here](https://caniuse.com/?search=es6).

## Authentication requirements

Your authentication system must meet the following requirements:

* It must be OAuth-compliant.

* It must provide a JWT token that contains a consistent, unique user identifier.

* It must have a publicly accessible JWKS endpoint for token signature validation.

For more information on the authentication requirements, refer to the [Partner authentication](/documentation/partner-authentication) guide.

## Information you must provide

As a Suki development partner, you must provide the following items to your Suki contact before you can integrate the Suki Web SDK:

* **Partner name**: A unique name that identifies your EMR/EHR.

* **JWKS endpoint**: The publicly accessible URL that Suki will use to validate the signature on user JWT tokens. This is provided by your identity provider.

* **Host URLs**: The public URLs for your test and production client applications where you will embed the Suki Web SDK. We need these URLs to add your application to our allowlist.

## Information you will receive from Suki

Before you can start the integration, your Suki contact will provide you with the following:

* **Partner ID**: A unique identifier issued by Suki.

For more information on the information you will receive from Suki, refer to the [Partner onboarding](/documentation/partner-onboarding) guide.

# Web SDK Changelog
Source: https://developer.suki.ai/web-sdk/product-updates/changelog

Web SDK product updates and announcements

Suki's SDK versioning policy is based on the semantic versioning standard. For example, in version 1.2.3, 1 is the major version, 2 is the minor version, and 3 is the patch version.

When we release a new SDK version for new features or bug fixes, we increment one of these three version components depending on the type of change introduced.

<Update label="Medication orders" description="June 2026">
  ### Enhancements

* **Medication orders**: The Web SDK now supports **Medication orders generation during ambient sessions**. You can enable this feature by passing the LOINC code `52471-0` in the `ambientOptions.sections` array. Learn more about how to enable this feature in the [Medication orders overview](/web-sdk/medication-orders/overview) guide.

**Implementation**

<View title="JavaScript" icon="js">
    ```js theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
    sdkClient.mount({
      rootElement: document.getElementById("suki-root"),
      encounter: encounter,
      ambientOptions: {
        sections: [
          { loinc: "52471-0" }, // Medication Orders LOINC code
        ],
      },
    });
    ```
  </View>

<View title="React" icon="react">
    ```jsx theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
    <SukiAssistant
      encounter={encounter}
      ambientOptions={{
        sections: [{ loinc: "52471-0" }],
      }}
    />
    ```
  </View>

<Note>
    Medication orders are supported for **v2** and **v3** versions of the Web SDK.
  </Note>

* Use this feature to display suggested medications during provider-patient conversations in the built-in **Orders section** on the clinical note page.
</Update>

<Update label="v3.1.0" description="May 2026">
  ### Enhancements

* **Minimized layout**: The Web SDK now supports a minimized layout during ambient sessions. It turns the Suki Web SDK UI into a compact, viewport-aligned widget so partners reclaim screen space for their own UI (for example, the EHR or patient chart) while Suki Web SDK continues to capture audio in the background.

* Learn more about how to implement minimized layout in the [Minimized layout implementation](/web-sdk/minimized-layout/implementation) guide.

**Implementation**

<View title="JavaScript" icon="js">
    ```js theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
    sdk.on("ui:layout-change", ({ layout }) => {
      // layout: "expanded" | "minimized" | "minimized-paused"
    })
    ```
  </View>

<View title="React" icon="react">
    ```jsx theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
    <SukiAssistant
      encounter={encounter}
      onLayoutChange={(layout) => {
        // layout: "expanded" | "minimized" | "minimized-paused"
        setIsMinimized(layout !== "expanded");
      }}
    />
    ```
  </View>
</Update>

<Update label="v3.0.0" description="April 2026">
  ### Major changes - <Badge icon="exclamation-triangle">Breaking changes</Badge>

* Suki Web SDK will now follow the same authentication flow as the other Suki SDKs.
    You will now need to pass a `SukiAuthManager` instance from `@suki-sdk/core` instead of passing partner
    fields directly on the `initialize()` for **JavaScript** or `init()` for **React** calls.

**Code example**

<View title="JavaScript" icon="js">
    ```js theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
    import { SukiAuthManager } from "@suki-sdk/core";
    import { initialize } from "@suki-sdk/js";

const authManager = new SukiAuthManager({
      partnerId: "your-partner-id",
      partnerToken: "your-partner-token",
      environment: "staging",
      autoRegister: true,
      loginOnInitialize: true,
      providerId: "your-provider-id",
      providerName: "Your Provider",
      providerOrgId: "your-org-id",
      providerSpecialty: "FAMILY_MEDICINE",
    });

initialize({
      authManager,
    });
    ```
  </View>

<View title="React" icon="react">
    ```tsx theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
    // Use inside <SukiProvider>. See the Web SDK Quickstart for a full app shell.
    import { useEffect, useMemo } from "react";
    import { SukiAuthManager } from "@suki-sdk/core";
    import { useSuki } from "@suki-sdk/react";

function SukiInit() {
      const authManager = useMemo(
        () =>
          new SukiAuthManager({
            partnerId: "your-partner-id",
            partnerToken: "your-partner-token",
            environment: "staging",
            autoRegister: true,
            loginOnInitialize: true,
            providerId: "your-provider-id",
            providerName: "Your Provider",
            providerOrgId: "your-org-id",
            providerSpecialty: "FAMILY_MEDICINE",
          }),
        [],
      );

const { init, isInitialized } = useSuki();

useEffect(() => {
        if (!isInitialized) {
          init({ authManager });
        }
      }, [init, isInitialized, authManager]);

return null;
    }
    ```
  </View>

* **Dictation capability**: Dictation capability is supported out of the box with `v3.0.0` of the Web SDK.

Refer to the [Migrating to Web SDK v3](/web-sdk/product-updates/migration-to-v3) guide for more details.
</Update>

<Update label="v2.2.0" description="April 2026">
  ### Enhancements

* **Added additional context parameters**: Pass **optional session-level metadata** in `ambientOptions` to improve note generation accuracy. Pass the following parameters along with LOINC codes at session init (in `mount` or `setAmbientOptions`):

* **visitType**: Enum values include `NEW_PATIENT`, `ESTABLISHED_PATIENT`, `WELLNESS`, `ED`.
    * **encounterType**: Enum values include `AMBULATORY`, `INPATIENT`, `ED`.
    * **providerRole**: Enum values include `PRIMARY/ATTENDING`, `CONSULTING`.
    * **reasonForVisit**: String, maximum `255` characters.
    * **chiefComplaint**: String, maximum `255` characters.

* All new parameters are **optional**; absence does not break existing flows.

* Free text fields (`reasonForVisit`, `chiefComplaint`) enforce a **255-character limit**.

**Code example**

```json theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
  {
    "ambientOptions": {
      "visitType": "ESTABLISHED_PATIENT", 
      "encounterType": "AMBULATORY",
      "providerRole": "PRIMARY/ATTENDING",
      "reasonForVisit": "Follow-up for hypertension",
      "chiefComplaint": "Headache"
    }
  }
  ```

* **Custom note titles from visit type**: When you pass **`visitType`** in **`ambientOptions`**, the Web SDK uses that value as the **title** for the generated note in the in-product patient note list, instead of the generic **Note** label. That makes it easier for clinicians to tell multiple notes apart on the same day. If **`visitType`** is omitted, the UI keeps the previous generic title behavior.
</Update>

<Update label="v2.1.2" description="March 2026">
  ### Enhancements

* **Notification Webhook**: The Web SDK now supports notification webhook. Receive notifications about session completion or failure by implementing your own webhook endpoint.
    Learn more about how webhook works and how to implement your own webhook endpoint to receive them in the [Notification webhook for partners](/documentation/webhook/overview) documentation.

* **Existing patient diagnoses for Problem-Based Charting**: Pass the patient's existing diagnoses (e.g. from the EMR) into an ambient session using the `diagnoses` block in `ambientOptions`. The session merges them with what's discussed during the visit so you avoid duplicate problems in the note. Use this when you have at least one PBC section (`isPBNSection: true`); each diagnosis needs one **ICD10** code. Refer to the [Existing patient diagnoses](/web-sdk/guides/ambient-problem-based-charting#existing-patient-diagnoses) guide for more details.
</Update>

<Update label="v2.1.1" description="Jan 2026">
  ### Enhancements

* **Multilingual capability**: The Web SDK now supports multilingual capability by default. Patients and providers can speak in their preferred language; the SDK generates the clinical note in English. No configuration is required, and you do not need to contact Technical Support to enable this feature.
  * **Optional patient fields**: The `birthDate` and `gender` properties are now optional in the `Patient` type. Omit these fields when creating patient objects if the information isn't available, making it easier to integrate patient data from systems where this information may be missing.

### Removed

* **AmbientOptions**: The `prefill.noteTypeIds` property is no longer supported in the `AmbientOptions` type. You must use the `sections` property instead.
</Update>

<Update label="v2.1.0" description="Nov 2025">
  ### New features

* **Telehealth audio capture**: Capture audio directly from separate tabs from the same browser window hosting your telehealth session. This ensures accurate ambient clinical documentation during virtual visits via Zoom, Teams, and other telehealth platforms.

<Note>
    This feature is an **opt-in setting** and is **disabled by default**. To enable this feature, follow the steps in the [Telehealth guide](/web-sdk/guides/telehealth).
  </Note>
</Update>

<Update label="v2.0.4" description="Sep 2025">
  ### Enhancements

* **Enhanced event monitoring**: Added 6 new authentication events and 5 new ambient session lifecycle events to the `EmitterEvents` type. These events provide granular visibility into login, registration, token refresh, and session state changes, helping you build better error handling and user feedback in your application.

* **Improved offline handling**: Offline mode now includes a 15-second buffer to handle temporary connection problems. This gives you time to show connection status notifications in your UI before the session transitions to offline mode, improving the user experience during brief network interruptions.

* **User feedback collection**: Collect user feedback on AI-generated content directly through the SDK. This helps you gather insights on note quality and user satisfaction.
</Update>

<Update label="v2.0.3" description="June 2025">
  ### New features

* **Bearer token authentication**: Added support for Bearer token authentication by allowing you to pass `providerId` during SDK initialization. This provides more flexibility for authentication workflows.

```js main.js theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
  import { initialize } from "@suki-sdk/js";

initialize({
    partnerId: "your-partner-id",
    partnerToken: "your-partner-token",
    providerId: "provider-id"
  });
  ```

```jsx App.tsx theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
  import { useSuki } from "@suki-sdk/react";

const { init } = useSuki();

useEffect(() => {
    init({
      partnerId: "your-partner-id",
      partnerToken: "your-partner-token",
      providerId: "provider-id"
    });
  }, []);
  ```

### Bug fixes

* Fixed incorrect `isAmbientInProgress` and `isAmbientPaused` flags in `ambient:update` events
  * Fixed `activeAmbientId` not resetting in the `useSuki` hook after a session is submitted or cancelled

### Additional changes

* Removed insert script option from section editing in the note page
</Update>

<Update label="v2.0.2" description="May 2025">
  ### New features

* **Problem-based charting support**: Added support for problem-based charting (PBN) with LOINC codes. Use the `isPBNSection` property in your `ambientOptions` to enable problem-based note generation for specific sections.

```json theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
  {
    "ambientOptions": {
      "sections": [
        {
          "loinc": "10164-2", // History of Present Illness
          "isPBNSection": true
        }
      ]
    }
  }
  ```

Read more about problem-based charting in the [Ambient guide](/web-sdk/guides/ambient-problem-based-charting).
</Update>

<Update label="v2.0.1" description="May 2025">
  ### Enhancements

* **Updated default UI options**: Updated default values for `uiOptions` to match the latest UI configuration. Close button, start ambient button, dictation, copy, and insert script features are now enabled by default, while the create empty note button is disabled by default.
</Update>

<Update label="v2.0.0" description="April 2025">
  ### Major changes - <Badge icon="exclamation-triangle">Breaking changes</Badge>

* **Automated user registration**: Programmatically create organizations and users during SDK initialization, reducing manual setup and accelerating onboarding workflows.

* **LOINC code integration**: Standardize note sections using LOINC codes, improving note quality, scalability, and integration consistency across healthcare systems.

* **Expanded theme customization**: Enhanced theme options with additional properties for greater control over SDK appearance. Refer to the [Theming guide](/web-sdk/examples/theming-and-customization) for examples and customization options.
</Update>

<Update label="v1.0.3" description="February 2025">
  ### Bug fixes

* Various bug fixes and stability improvements
</Update>

<Update label="v1.0.2" description="December 2024">
  ### Bug fixes

* Various bug fixes and stability improvements
</Update>

<Update label="v1.0.1" description="December 2024">
  ### Bug fixes

* Various bug fixes and stability improvements
</Update>

<Update label="v1.0.0" description="December 2024">
  ### New features

* **Initial stable release**: Enhanced user experience with visual improvements, faster note generation, and improved stability
</Update>

<Update label="v0.5.0" description="July 2024">
  ### New features

* **Initial release**: Clinical note creation by listening to provider-patient conversations
</Update>

# Migrating To Web SDK v2
Source: https://developer.suki.ai/web-sdk/product-updates/migration-to-v2

Complete guide to migrate from Suki.js v1 to v2 with enhanced provider onboarding, LOINC standardization, and improved UI customization

<Warning>
  We will remove this guide in future updates. If you are still on v1.x, complete your migration to `v2.0.0` first before you migrate to `v3.0.0`.
</Warning>

<span>Quick summary</span>
  </div>

<div>
    The `v2.0.0` release adds new features and changes that enhance clinical documentation workflows.

<br />

<Danger>
      The new version introduces breaking changes that require immediate attention.

Refer to [Breaking changes reference](/web-sdk/product-updates/migration-to-v2#breaking-changes-reference) for more information.
    </Danger>

<table>
      <thead>
        <tr>
          <th>Change Category</th>
          <th>Details</th>
          <th>Migration Impact</th>
        </tr>
      </thead>

<tbody>
        <tr>
          <td><strong>Required Provider Information</strong></td>
          <td>Two new required fields:<br />• <code>providerName</code> (string): The full name of the healthcare provider using the SDK<br />• <code>providerOrgId</code> (string): The unique identifier of the healthcare organization</td>
          <td>These fields enable automatic provider onboarding in the Suki system without manual registration. Add both fields to your initialization configuration.</td>
        </tr>

<tr>
          <td><strong>Ambient Options Restructure</strong></td>
          <td><strong>Deprecated</strong>: <code>prefill.noteTypeIds</code> approach (is removed from `v2.1.1` and is no longer supported)<br /><strong>New</strong>: <code>sections</code> array using LOINC codes for standardized note sections</td>
          <td>You must migrate from <code>noteTypeIds</code> to LOINC-based section configurations. The <code>prefill.noteTypeIds</code> approach is deprecated and will be removed in future versions.</td>
        </tr>

<tr>
          <td><strong>Theme Configuration Changes</strong></td>
          <td><strong>Renamed</strong>: <code>primaryColor</code> → <code>primary</code><br /><strong>New properties</strong>: <code>background</code>, <code>secondaryBackground</code>, <code>foreground</code>, <code>warning</code></td>
          <td>Update all <code>primaryColor</code> references to <code>primary</code> in your theme configuration. New properties are optional but recommended for better visual control.</td>
        </tr>

<tr>
          <td><strong>Mount Configuration</strong></td>
          <td><code>ambientOptions</code> parameter is now required when mounting the SDK. You must provide at least one section defined using LOINC codes.</td>
          <td>Previously optional in v1.x, now required in v2.0. You must provide <code>ambientOptions</code> with at least one section defined using LOINC codes when calling <code>mount()</code>.</td>
        </tr>
      </tbody>
    </table>
  </div>

<span>Last updated:</span>
    <span>June 2026</span>
  </div>
</div>

The v2.0.0 release of Suki.js includes significant improvements that enhance clinical documentation workflows and standardize healthcare integrations. This guide provides step-by-step instructions to migrate your integration from v1.x to v2.0.

### Improvements

The `v2.0.0` release adds new features and changes that enhance clinical documentation workflows. Key improvements include:

* Automatic provider registration
* Standardized LOINC codes for note sections
* Expanded theme customization options
* Improved section editing with dictation copy capabilities
* Enhanced error handling with better validation and reporting

## Migration steps

Follow these steps in order to migrate your integration from v1.x to v2.0.

### Step 1: Update package version

Update to the latest version of the Suki SDK:

<View title="JavaScript" icon="js">
  <CodeGroup>
    ```shell pnpm theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
    pnpm add @suki-sdk/js@latest
    ```

```shell npm theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
    npm install @suki-sdk/js@latest
    ```

```shell yarn theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
    yarn add @suki-sdk/js@latest
    ```
  </CodeGroup>
</View>

<View title="React" icon="react">
  <CodeGroup>
    ```shell pnpm theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
    pnpm add @suki-sdk/react@latest
    ```

```shell npm theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
    npm install @suki-sdk/react@latest
    ```

```shell yarn theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
    yarn add @suki-sdk/react@latest
    ```
  </CodeGroup>
</View>

### Step 2: Update provider initialization

Add the required provider information to your initialization configuration. The initialization process now requires additional provider information for automatic onboarding.

<View title="JavaScript" icon="js">
  #### Before (v1.x)

```js JavaScript theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
  import { initialize } from "@suki-sdk/js";

const sdkClient = initialize({
    partnerId: "your-partner-id",
    partnerToken: "your-token",
    enableDebug: true,
    theme: {
      primaryColor: "#4287f5",
    },
  });
  ```

#### After (v2.0)

```js JavaScript theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
  import { initialize } from "@suki-sdk/js";

const sdkClient = initialize({
    // Required partner details
    partnerId: "your-partner-id",
    partnerToken: "your-token",
    providerName: "Dr. John Q. Doe", // NEW: Required
    providerOrgId: "organization-id", // NEW: Required

// Optional fields
    providerSpecialty: "FAMILY_MEDICINE", // NEW: Optional
    enableDebug: true,
    logLevel: "info", // NEW: Optional
    isTestMode: false, // NEW: Optional
    theme: {
      primary: "#4287f5", // CHANGED: renamed from primaryColor
      background: "#ffffff", // NEW: Optional
      secondaryBackground: "#f5f5f5", // NEW: Optional
      foreground: "#333333", // NEW: Optional
      warning: "#ff9900", // NEW: Optional
    },
  });
  ```
</View>

<View title="React" icon="react">
  #### Before (v1.x)

```jsx React theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
  import { SukiProvider, useSuki } from "@suki-sdk/react";

const initOptions = {
    partnerId: "your-partner-id",
    partnerToken: "your-token",
    enableDebug: true,
    theme: {
      primaryColor: "#4287f5",
    },
  };

function App() {
    const { init, isInitialized } = useSuki();

useEffect(() => {
      if (!isInitialized) {
        init(initOptions);
      }
    }, [init, isInitialized]);

return <div>Your app content</div>;
  }
  ```

#### After (v2.0)

```jsx React theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
  import { SukiProvider, useSuki } from "@suki-sdk/react";

const initOptions = {
    // Required partner details
    partnerId: "your-partner-id",
    partnerToken: "your-token",
    providerName: "Dr. John Q. Doe", // NEW: Required
    providerOrgId: "organization-id", // NEW: Required

function App() {
    const { init, isInitialized } = useSuki();

useEffect(() => {
      if (!isInitialized) {
        init(initOptions);
      }
    }, [init, isInitialized]);

return <div>Your app content</div>;
  }
  ```
</View>

#### New required fields explained

<AccordionGroup>
  <Accordion title="providerName (Required)" icon="user">
    The full name of the healthcare provider using the SDK, including first name, middle name (if applicable), and last name separated by spaces.

This information enables automatic provider onboarding in the Suki system without manual registration.

**Example**: `"Dr. Jane Marie Smith"`
  </Accordion>

<Accordion title="providerOrgId (Required)" icon="building">
    The unique identifier of the healthcare organization to which the provider belongs in your system.

This ID maps the provider to the correct organization and keeps data separate across organizations in the Suki platform. This should match the organization ID in your system's database for consistency across platforms.

**Example**: `"northwell-1234"` or `"memorial-hermann-5678"`
  </Accordion>

<Accordion title="providerSpecialty (Optional)" icon="stethoscope">
    The medical specialty of the provider, which helps tailor the SDK's functionality to specific clinical contexts.

If omitted, the system defaults to `"FAMILY_MEDICINE"` as the provider specialty. This information improves the relevance of automated suggestions and templates during onboarding.

Refer to the [Specialties documentation](/documentation/specialties) for a comprehensive list of supported specialties.
  </Accordion>
</AccordionGroup>

### Step 3: Update ambient options configuration

Replace the deprecated `prefill.noteTypeIds` approach with the new LOINC-based section configuration. We completely redesigned the ambient options structure to use standardized LOINC codes instead of custom note type IDs.

<View title="JavaScript" icon="js">
  #### Before (v1.x)

#### After (v2.0)

```js JavaScript theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
  sdkClient.mount({
    rootElement: document.getElementById("suki-root"),
    encounter: encounterDetails,
    ambientOptions: {
      sections: [
        {
          loinc: "29545-1", // Physical Examination
        },
        {
          loinc: "10164-2", // History of Present Illness
        },
        {
          loinc: "51847-2", // Assessment and Plan
          isPBNSection: true, // NEW: Problem-based charting support
        },
      ],
    },
  });
  ```
</View>

<View title="React" icon="react">
  #### Before (v1.x)

```jsx React theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
  <SukiAssistant
    encounter={encounter}
    ambientOptions={{
      prefill: {
        noteTypeIds: ["note-type-1", "note-type-2"],
      },
    }}
    onNoteSubmit={(note) => {
      console.log("Note submitted:", note);
    }}
  />
  ```

#### After (v2.0)

```jsx React theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
  <SukiAssistant
    encounter={encounter}
    ambientOptions={{
      sections: [
        {
          loinc: "29545-1", // Physical Examination
        },
        {
          loinc: "10164-2", // History of Present Illness
        },
        {
          loinc: "51847-2", // Assessment and Plan
          isPBNSection: true, // NEW: Problem-based charting support
        },
      ],
    }}
    onNoteSubmit={(note) => {
      console.log("Note submitted:", note);
    }}
  />
  ```
</View>

<Note>
  The `prefill.noteTypeIds` approach is still supported but deprecated and will be removed in future versions. We strongly recommend migrating to the new section-based configuration using LOINC codes.

Refer to the [Note sections documentation](/documentation/note-sections) for a complete list of supported sections and corresponding LOINC codes.
</Note>

### Step 4: Update UI options

The `uiOptions` property now provides more granular control over the SDK's user interface elements, including new section editing capabilities.

<View title="JavaScript" icon="js">
  #### Before (v1.x)

#### After (v2.0)

```js JavaScript theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
  sdkClient.mount({
    rootElement: document.getElementById("suki-root"),
    encounter: encounterDetails,
    ambientOptions: { /* ... */ },
    uiOptions: {
      showCloseButton: true,
      showCreateEmptyNoteButton: true,
      showStartAmbientButton: true, // NEW: Control ambient button visibility
      sectionEditing: { // NEW: Section-level editing controls
        enableDictation: true, // NEW: Voice input for sections
        enableCopy: true, // NEW: Copy functionality
      },
    },
    onClose: () => {
      console.log("SDK closed");
    },
  });
  ```
</View>

<View title="React" icon="react">
  #### Before (v1.x)

#### After (v2.0)

```jsx React theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
  <SukiAssistant
    encounter={encounter}
    ambientOptions={{ /* ... */ }}
    uiOptions={{
      showCloseButton: true,
      showCreateEmptyNoteButton: true,
      showStartAmbientButton: true, // NEW: Control ambient button visibility
      sectionEditing: { // NEW: Section-level editing controls
        enableDictation: true, // NEW: Voice input for sections
        enableCopy: true, // NEW: Copy functionality
      },
    }}
    onClose={() => {
      console.log("SDK closed");
    }}
  />
  ```
</View>

#### UI options reference

Use the UI configuration options to control the visibility and functionality of various interface elements like buttons and editing features.

<Expandable title="UI Options Properties">
  <ResponseField name="showCloseButton" type="boolean">
    Controls visibility of the close button in the header.
  </ResponseField>

<ResponseField name="showCreateEmptyNoteButton" type="boolean">
    Controls visibility of the "Create Empty Note" button on the patient profile.
  </ResponseField>

<ResponseField name="showStartAmbientButton" type="boolean">
    Controls visibility of the "Start Ambient" button for ambient mode initiation.
  </ResponseField>

<ResponseField name="sectionEditing.enableDictation" type="boolean">
    Controls the microphone icon for voice input (activates voice-to-text feature).
  </ResponseField>

<ResponseField name="sectionEditing.enableCopy" type="boolean">
    Controls the copy icon for text copying functionality.
  </ResponseField>
</Expandable>

<Tip>
  You should only provide explicit values when you need to enable specific features. For example:

```js JavaScript theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
  // Enable only the copy feature and showStartAmbientButton
  uiOptions: {
    showStartAmbientButton: true,
    sectionEditing: {
      enableCopy: true
    }
  }
  ```
</Tip>

### Step 5: Update note submission handling

Update your note submission handlers to work with the new response structure that includes LOINC codes and enhanced diagnosis information.

#### Before (v1.x)

#### After (v2.0)

```js JavaScript theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
onNoteSubmit: (note) => {
  console.log("Note ID:", note.noteId);
  note.contents.forEach((section) => {
    console.log(`Section: ${section.title} - ${section.content}`);
    console.log(`LOINC Code: ${section.loinc_code}`); // NEW: LOINC code included
    if (section.diagnosis) { // NEW: Enhanced diagnosis information
      console.log(`Diagnosis: ${section.diagnosis.icdDescription}`);
    }
  });
}
```

#### Example response structure

The note submission payload now includes LOINC codes for better standardization:

```json JSON theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
{
  "noteId": "82467ba8-71bc-46e2-8232-20d4d5629973",
  "contents": [
    {
      "title": "History",
      "content": "The patient is a 50-year-old female who has been experiencing fever for the last 10 days...",
      "loinc_code": "18233-4",
      "diagnosis": null
    },
    {
      "title": "Review of Systems",
      "content": "- No additional symptoms or pertinent negatives discussed during the encounter.",
      "loinc_code": "10164-2",
      "diagnosis": null
    },
    {
      "title": "Assessment and Plan",
      "content": "Viral hepatitis B with hepatic coma",
      "loinc_code": "51847-2",
      "diagnosis": {
        "icdCode": "B19.11",
        "icdDescription": "Unspecified viral hepatitis B with hepatic coma",
        "snomedCode": "26206000",
        "snomedDescription": "Hepatic coma due to viral hepatitis B",
        "hccCode": "HCC-1",
        "panelRanking": 1,
        "billable": true,
        "problemLabel": "Unspecified viral hepatitis B with hepatic coma"
      }
    }
  ]
}
```

Refer to [NoteContent](/web-sdk/api-reference/types/note-content) for the complete structure of the note content.

## Complete migration examples

Here are complete examples showing the migration from v1.x to v2.0:

<View title="JavaScript" icon="js">
  <CodeGroup>
    ```js Before (v1.x) expandable theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
    import { initialize } from "@suki-sdk/js";

const encounterDetails = {
      identifier: "encounter-id",
      patient: {
        identifier: "patient-id",
        name: {
          use: "official",
          family: "Doe",
          given: ["John"],
          suffix: ["MD"],
        },
        birthDate: "1990-01-01",
        gender: "Male",
      },
    };

const sdkClient = initialize({
      partnerId: "your-partner-id",
      partnerToken: "your-token",
      enableDebug: true,
      theme: {
        primaryColor: "#4287f5",
      },
    });

```js After (v2.0) expandable theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
    import { initialize } from "@suki-sdk/js";

const sdkClient = initialize({
      // Required partner details
      partnerId: "your-partner-id",
      partnerToken: "your-token",
      providerName: "Dr. John Q. Doe",
      providerOrgId: "organization-id",

// Optional fields
      providerSpecialty: "CARDIOLOGY",
      enableDebug: true,
      theme: {
        primary: "#4287f5",
        background: "#ffffff",
        secondaryBackground: "#f5f5f5",
        foreground: "#333333",
        warning: "#ff9900",
      },
    });

<View title="React" icon="react">
  <CodeGroup>
    ```jsx Before (v1.x) expandable theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
    import React, { useEffect } from "react";
    import { SukiAssistant, SukiProvider, useSuki } from "@suki-sdk/react";

const initOptions = {
      partnerId: "your-partner-id",
      partnerToken: "your-token",
      enableDebug: true,
      theme: {
        primaryColor: "#4287f5",
      },
    };

const encounter = {
      identifier: "encounter-123",
      patient: {
        identifier: "patient-456",
        name: {
          use: "usual",
          family: "Smith",
          given: ["John"],
          suffix: [],
        },
        birthDate: "1980-01-15",
        gender: "male",
      },
    };

function App() {
      const { init, isInitialized } = useSuki();

useEffect(() => {
        if (!isInitialized) {
          init(initOptions);
        }
      }, [init, isInitialized]);

return (
        <SukiAssistant
          encounter={encounter}
          ambientOptions={{
            prefill: {
              noteTypeIds: ["note-type-1", "note-type-2"],
            },
          }}
          onNoteSubmit={(note) => {
            console.log("Note submitted:", note.noteId);
          }}
          uiOptions={{
            showCloseButton: true,
            showCreateEmptyNoteButton: true,
          }}
          onClose={() => {
            console.log("SDK closed");
          }}
        />
      );
    }

function AppWithProvider() {
      return (
        <SukiProvider>
          <App />
        </SukiProvider>
      );
    }

export default AppWithProvider;
    ```

```jsx After (v2.0) expandable theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
    import React, { useEffect } from "react";
    import { SukiAssistant, SukiProvider, useSuki } from "@suki-sdk/react";

const initOptions = {
      // Required partner details
      partnerId: "your-partner-id",
      partnerToken: "your-token",
      providerName: "Dr. John Q. Doe",
      providerOrgId: "organization-id",

function App() {
      const { init, isInitialized } = useSuki();

useEffect(() => {
        if (!isInitialized) {
          init(initOptions);
        }
      }, [init, isInitialized]);

return (
        <SukiAssistant
          encounter={encounter}
          ambientOptions={{
            sections: [
              {
                loinc: "29545-1", // Physical Examination
              },
              {
                loinc: "10164-2", // History of Present Illness
              },
              {
                loinc: "51847-2", // Assessment and Plan
                isPBNSection: true,
              },
            ],
          }}
          onNoteSubmit={handleNoteSubmit}
          uiOptions={{
            showCloseButton: true,
            showCreateEmptyNoteButton: true,
            showStartAmbientButton: true,
            sectionEditing: {
              enableDictation: true,
              enableCopy: true,
            },
          }}
          onClose={() => {
            console.log("SDK closed");
          }}
        />
      );
    }

function AppWithProvider() {
      return (
        <SukiProvider>
          <App />
        </SukiProvider>
      );
    }

export default AppWithProvider;
    ```
  </CodeGroup>
</View>

## Breaking changes reference

This section provides detailed information about each breaking change and its migration impact.

### Provider information

<ResponseField name="providerName" type="string">
  The provider's full name. This field is now required during SDK initialization to enable automatic provider onboarding to the Suki system.

**Migration Impact**: Previously optional, now required in `InitializationConfig`.
</ResponseField>

<ResponseField name="providerOrgId" type="string">
  The unique identifier for the provider's organization. This field is now required during SDK initialization.

**Migration Impact**: Previously optional, now required in `InitializationConfig`. This enables seamless provider registration without manual onboarding steps.
</ResponseField>

### AmbientOptions structure

<Warning>
  The `ambientOptions` structure has been completely redesigned in v2.0. The previous `prefill.noteTypeIds` approach is deprecated.
</Warning>

<ResponseField name="sections" type="array">
  An array of section objects that define which note sections to generate. Each section is identified by a LOINC code for improved standardization and interoperability with healthcare systems.

**v1.x Deprecated approach**:

```typescript TypeScript theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
  ambientOptions: {
    prefill: {
      noteTypeIds: ['soap', 'hpi']
    }
  }
  ```

**v2.0 Required approach**:

```typescript TypeScript theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
  ambientOptions: {
    sections: [
      { loinc: '48765-2' }, // Allergies
      { loinc: '10164-2' }  // History of Present Illness
    ]
  }
  ```

**Migration impact**: You must replace all `noteTypeIds` references with LOINC-based section configurations. Refer to the [Note sections documentation](/documentation/note-sections) for complete LOINC code mappings.
</ResponseField>

### Theme configuration

<ResponseField name="primary" type="string">
  Renamed from `primaryColor`. Defines the primary brand color for the SDK interface.

**Migration impact**: Update all `primaryColor` references to `primary` in your theme configuration.
</ResponseField>

<ResponseField name="background" type="string">
  New property. Defines the main background color for the SDK interface.

**Migration impact**: This is a new optional property that enhances UI customization capabilities.
</ResponseField>

<ResponseField name="secondaryBackground" type="string">
  New property. Defines the secondary background color for panels and cards within the SDK interface.

**Migration impact**: This is a new optional property that provides more granular control over the visual hierarchy.
</ResponseField>

<ResponseField name="foreground" type="string">
  New property. Defines the primary text color for the SDK interface.

**Migration impact**: This is a new optional property that ensures text readability across different background colors.
</ResponseField>

<ResponseField name="warning" type="string">
  New property. Defines the color used for warning messages and alerts.

**Migration impact**: This is a new optional property that improves the visibility of important notifications.
</ResponseField>

### Mount configuration

<ResponseField name="ambientOptions" type="AmbientOptions">
  Configuration options for ambient mode functionality. This field is now required when mounting the SDK.

**Migration Impact**: Previously optional in v1.x, now required in v2.0. You must provide `ambientOptions` with at least one section defined when calling `mount()`.

**Example**:

```typescript TypeScript  theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
  await sukiSDK.mount({
    target: document.getElementById('suki-container'),
    ambientOptions: {
      sections: [
        { loinc: '48765-2' }
      ]
    }
  });
  ```
</ResponseField>

## Troubleshooting

### Common migration errors

<AccordionGroup>
  <Accordion title="Initialization Errors">
    * `missing-partner-details`: Provider information is incomplete
    * `no-partner-token`: Authentication token is missing
    * `no-init`: SDK not properly initialized
  </Accordion>

<Accordion title="Ambient Mode Errors">
    * `no-ambient`: Ambient mode not available
    * `ambient-in-progress`: Another ambient session is active
    * `already-started`: Ambient session already running
  </Accordion>

<Accordion title="LOINC Code Errors">
    * `unsupported-loinc-codes`: One or more LOINC codes are not supported
    * `no-supported-loinc-codes`: No valid LOINC codes provided
  </Accordion>
</AccordionGroup>

### Validation checklist

After migration, verify the following:

* All required provider information is supplied in initialization (`providerName` and `providerOrgId`)
* `AmbientOptions` uses the new section-based configuration with LOINC codes
* Theme configuration uses the new property names (`primary` instead of `primaryColor`)
* Section editing features are configured as needed (`sectionEditing.enableDictation` and `sectionEditing.enableCopy`)
* All UI options are properly configured
* Note submission handlers account for new LOINC code fields (`section.loinc_code`)

## Next steps

<CardGroup>
  <Card title="Note Sections" icon="list" href="/documentation/note-sections">
    Learn about supported LOINC codes and section configurations
  </Card>

<Card title="Specialties" icon="stethoscope" href="/documentation/specialties">
    View the complete list of supported medical specialties
  </Card>

<Card title="Error Handling" icon="triangle-exclamation" href="/web-sdk/guides/error-handling">
    Implement proper error handling for your integration
  </Card>

<Card title="Basic Usage" icon="play" href="/web-sdk/examples/basic-usage">
    See complete examples of the v2.0 implementation
  </Card>

<Card title="Migration to v3" icon="rocket" href="/web-sdk/product-updates/migration-to-v3">
    Move authentication to SukiAuthManager from @suki-sdk/core
  </Card>
</CardGroup>

# Migrating To Web SDK v3
Source: https://developer.suki.ai/web-sdk/product-updates/migration-to-v3

Learn how to migrate from Web SDK v2 to v3

<span>Quick summary</span>
  </div>

<div>
    <b>Breaking change:</b> From Web SDK `v3.0.0+`, the Web SDK authentication is shared with the other Suki SDKs using a <code>SukiAuthManager</code> from <code>@suki-sdk/core</code>. You cannot rely on passing <code>partnerId</code>, <code>partnerToken</code>, and related fields only through <code>initialize()</code> or <code>init()</code> without constructing <code>SukiAuthManager</code> first.

<br />

<Danger>
      Plan dependency upgrades and auth refactors before rolling v3 to production. Start with [What changed](#what-changed) and [How to migrate](#how-to-migrate), then [Before and after (v2 vs v3)](#before-and-after-v2-vs-v3) for code examples.
    </Danger>
  </div>

<span>Last updated:</span>
    <span>June 2026</span>
  </div>
</div>

In v2.x.x, you managed login by passing partner credentials, provider details, and related fields within a single `initialize()` (JavaScript) or `init()` (React) call.
In v3.0.0+, you must split these tasks. You still require a **partner token**, but you no longer provide all fields during the initialization call. Instead, you create an instance of the `SukiAuthManager` class from the `@suki-sdk/core` package.

The Suki Web SDK now requires this instance to manage authentication state.

### Implementation steps

Follow these steps to configure authentication:

1. **Generate a partner token**: Obtain a partner token for the current user, following the same requirement as v2.

2. **Create a SukiAuthManager instance**: Create one `SukiAuthManager` instance for your entire application. Pass in the token, the **environment** (staging or production), and the **partner** and **provider** details you previously used in v2.

3. **Initialize the SDK**: Call `initialize()` (JavaScript) or `init()` (React) and include the `authManager` instance along with your other Web SDK options. The Web SDK reads the authentication state directly from the `authManager`.

## What changed

| Topic                           | v2                                                                                                                                                                                                                                               | v3                                                                                                                                                             |
| :------------------------------ | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Where auth config lives         | Partner fields passed directly into <code>initialize()</code> / <code>init()</code>                                                                                                                                                              | You build <code>new SukiAuthManager(\{ ... })</code> and pass <code>\{ authManager }</code> into <code>initialize()</code> or <code>init()</code>              |
| New dependency                  | Not required                                                                                                                                                                                                                                     | <code>@suki-sdk/core</code> (provides <code>SukiAuthManager</code>)                                                                                            |
| Stage vs production / test mode | Optional <code>isTestMode</code> on <code>initialize()</code> / <code>init()</code> options (Refer to [InitOptions](/web-sdk/api-reference/types/init-options) and [Migration to v2](/web-sdk/product-updates/migration-to-v2)) for more details | Set <code>environment</code> on <code>SukiAuthManager</code>. Do not use <code>isTestMode</code> on the Web SDK `init()` call for environment selection in v3. |

<Note>
  In Web SDK v2, setting **`isTestMode`** to true would route the SDK to stage endpoints. In v3, **`isTestMode` is deprecated** for environment selection.

* Configure **staging versus production** through **`environment`** on **`SukiAuthManager`**, then pass **`authManager`** into **`initialize()`** or **`init()`**.

* Remove **`isTestMode`** from your init options when you migrate.
</Note>

## How to migrate

Follow the steps below to migrate to Web SDK v3.0.0+.

<Steps>
  <Step title="Install and upgrade packages" icon="download">
    Add **`@suki-sdk/core`**. Upgrade **`@suki-sdk/js`** or **`@suki-sdk/react`** to v3. Refer to [Install packages](#step-1-install-packages) for more details.
  </Step>

<Step title="Create SukiAuthManager" icon="key">
    Instantiate **`SukiAuthManager`** with your partner token, provider fields, and **`environment`** (staging/production). This replaces using **`isTestMode`** on v2 init options for stage endpoints. Create **once per session** after the partner token is available.
  </Step>

<Step title="Pass authManager into the Web SDK" icon="plug">
    Replace inline auth arguments on <code>initialize()</code> (JavaScript) or <code>init()</code> (React) with a single <code>authManager</code> instance.
  </Step>

<Step title="Validate in staging" icon="check">
    Run your usual flows (login, mount, sessions) in a non-production environment before promoting to production.
  </Step>
</Steps>

## Step 1: Install packages

<View title="JavaScript" icon="js">
  <CodeGroup>
    ```shell pnpm theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
    pnpm add @suki-sdk/js@latest @suki-sdk/core
    ```

```shell npm theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
    npm install @suki-sdk/js@latest @suki-sdk/core
    ```

```shell yarn theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
    yarn add @suki-sdk/js@latest @suki-sdk/core
    ```
  </CodeGroup>
</View>

<View title="React" icon="react">
  <CodeGroup>
    ```shell pnpm theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
    pnpm add @suki-sdk/react@latest @suki-sdk/core
    ```

```shell npm theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
    npm install @suki-sdk/react@latest @suki-sdk/core
    ```

```shell yarn theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
    yarn add @suki-sdk/react@latest @suki-sdk/core
    ```
  </CodeGroup>
</View>

## Step 2: Implement authentication with SukiAuthManager

Create a `SukiAuthManager` instance, then pass `authManager` into the Web SDK.

### Code example: create SukiAuthManager

<View title="JavaScript" icon="js">
  ```javascript JavaScript theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
  import { SukiAuthManager } from "@suki-sdk/core";

const authManager = new SukiAuthManager({
    partnerId,
    partnerToken,
    environment: "production",
    autoRegister: false,
    loginOnInitialize: true,
    providerId,
    providerName,
    providerOrgId,
    providerSpecialty,
  });
  ```
</View>

<View title="React" icon="react">
  In React, create the manager **inside a component** with `useMemo` so you do not instantiate it on every render or at module scope. Adjust the dependency array when `partnerId`, `partnerToken`, or other constructor
  inputs change.

```tsx React theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
  import { useMemo } from "react";
  import { SukiAuthManager } from "@suki-sdk/core";

function YourBootstrap() {
    const authManager = useMemo(
      () =>
        new SukiAuthManager({
          partnerId,
          partnerToken,
          environment: "production",
          autoRegister: false,
          loginOnInitialize: true,
          providerId,
          providerName,
          providerOrgId,
          providerSpecialty,
        }),
      [partnerId, partnerToken],
    );

return <>{/* your app content */}</>;
  }
  ```
</View>

<Note>
  Create the manager **once per session** after your identity token is available for authentication.
</Note>

## Step 3: Initialize the Web SDK

<View title="JavaScript" icon="js">
  In JavaScript, create the `SukiAuthManager` instance once per stable set of credentials.

```javascript JavaScript highlight={2,12-17} theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
  import { SukiAuthManager } from "@suki-sdk/core";
  import { initialize } from "@suki-sdk/js";

initialize({
    authManager, // new in v3
    enableDebug: false,
    theme,
  });
  ```

<Note>
    The returned SDK client behavior remains aligned with v3 release notes for `@suki-sdk/js`.
  </Note>

### Before and after: JavaScript `initialize` (v2 vs v3)

<CodeGroup>
    ```javascript JavaScript - SDK (v2)  theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
    import { initialize } from "@suki-sdk/js";

initialize({
      partnerId,
      partnerToken,
      enableDebug: true,
      isTestMode: true,
      theme
    });
    ```

```javascript JavaScript - SDK (v3)  theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
    import { SukiAuthManager } from "@suki-sdk/core";
    import { initialize } from "@suki-sdk/js";

const authManager = new SukiAuthManager({
      partnerId,
      partnerToken,
      environment: "staging",
    });

initialize({
      authManager,
      enableDebug: true,
      theme
    });
    ```
  </CodeGroup>
</View>

<View title="React" icon="react">
  In a component under `SukiProvider`, use the `SukiAuthManager` from Step 2 with `useSuki()`. In a `useEffect`, call `init({ authManager, ... })` only when `!isInitialized` so you do not initialize twice. See the [Quickstart](/web-sdk/quickstart) for a full example.

```tsx React highlight={1,3,17-28} theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
  import { useEffect, useMemo } from "react";
  import { SukiAuthManager } from "@suki-sdk/core";
  import { useSuki } from "@suki-sdk/react";

function YourAppContent() {
    const authManager = useMemo(
      () =>
        new SukiAuthManager({
          partnerId,
          partnerToken,
          environment: "production",
          autoRegister: false,
          loginOnInitialize: true,
        }),
      [partnerId, partnerToken],
    );

const { init, isInitialized } = useSuki();

useEffect(() => {
      if (!isInitialized) {
        init({
          authManager,
          uiOptions,
          ambientOptions,
        });
      }
    }, [authManager, init, isInitialized]);

return (
      <div>
        {/* your app content */}
      </div>
    );
  }
  ```

Create the manager once per stable set of credentials (see `useMemo` dependencies). Apply this inside your provider tree, not at module scope.

### Before and after: React `init` (v2 vs v3)

<CodeGroup>
    ```tsx React - SDK (v2) theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
    import { useEffect } from "react";
    import { useSuki } from "@suki-sdk/react";

const initOptions = {
      partnerId,
      partnerToken,
      providerName,
      providerOrgId,
      isTestMode,
      enableDebug,
      theme,
    };

function App() {
      const { init } = useSuki();

useEffect(() => {
        init(initOptions);
      }, [init]);

return (
        <div>
          {/* your app content */}
        </div>
      );
    }
    ```

```tsx React - SDK (v3) theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
    import { useEffect, useMemo } from "react";
    import { SukiAuthManager } from "@suki-sdk/core";
    import { useSuki } from "@suki-sdk/react";

function App() {
      const authManager = useMemo(
        () =>
          new SukiAuthManager({
            partnerId,
            partnerToken,
            environment: "production",
            autoRegister: false,
            loginOnInitialize: true,
            providerId,
            providerName,
            providerOrgId,
            providerSpecialty,
          }),
        [
          partnerId,
          partnerToken,
          autoRegister,
          loginOnInitialize,
          providerId,
          providerName,
          providerOrgId,
          providerSpecialty,
        ],
      );

const { init, isInitialized } = useSuki();

useEffect(() => {
        if (!isInitialized) {
          init({
            authManager,
            enableDebug,
            theme,
          });
        }
      }, [authManager, init, isInitialized]);

return (
        <div>
          {/* your app content */}
        </div>
      );
    }
    ```
  </CodeGroup>
</View>

## Migration checklist (v2 vs v3)

* Upgrade `@suki-sdk/js` or `@suki-sdk/react` to v3
* Add dependency `@suki-sdk/core` (required for `SukiAuthManager`)
* Replace inline auth configuration with `new SukiAuthManager(...)`
* Pass `authManager` into `initialize()` in the JavaScript SDK or `init()` in the React SDK
* Remove **`isTestMode`** from init options; set **`environment`** on **`SukiAuthManager`** instead of using **`isTestMode`** for stage versus production behavior

## Next steps

<CardGroup>
  <Card title="InitOptions" icon="gear" href="/web-sdk/api-reference/types/init-options">
    Learn about the options you can pass on init option types
  </Card>

<Card title="AuthConfig (SukiAuthManager)" icon="key" href="/dictation-sdk/guides/configuration#authconfig">
    All fields you can pass into SukiAuthManager
  </Card>

<Card title="Migration To v2" icon="memo" href="/web-sdk/product-updates/migration-to-v2">
    Start here if you are still on Web SDK v1.x.x
  </Card>

<Card title="Web SDK Quickstart" icon="rocket" href="/web-sdk/quickstart">
    Handle Web SDK errors after you migrate
  </Card>
</CardGroup>

# Web SDK Quickstart
Source: https://developer.suki.ai/web-sdk/quickstart

Get started with Suki.js Web SDK - from installation to mounting the SDK UI

This guide walks you through setting up Suki.js in your existing JavaScript or React application, from installation to mounting the SDK UI.

**What will you do**

1. Install the Suki Web SDK package for your framework (JavaScript or React)
2. Initialize the SDK by creating a `SukiAuthManager` from `@suki-sdk/core` with your partner token and provider fields
3. Mount the SDK UI into your application using the `encounter` object.

<Tip>
  **Using an AI coding tool?**

npx skills add [https://developer.suki.ai](https://developer.suki.ai)

## Prerequisites

For the rest of this documentation, we assume the following setup is complete:

* You have received your `partnerId` from Suki.

* Your host URLs are on the Suki allowlist.

* Your partner configuration in the Suki Platform points to your correct JWKS endpoint.

* Your JWT token contains the key that you specified as your **User identifier field**.

## Install the Suki SDK package

To begin, install the Suki web SDK package in your project. Choose the appropriate package based on your framework:

<Tip>
  You must choose the appropriate package based on your framework. Refer to the [Installation guide](/web-sdk/installation) for more information.
</Tip>

<View title="JavaScript" icon="js">
  <CodeGroup>
    ```shell pnpm theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
    pnpm add @suki-sdk/js @suki-sdk/core
    ```

```shell npm theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
    npm install @suki-sdk/js @suki-sdk/core
    ```

```shell yarn theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
    yarn add @suki-sdk/js @suki-sdk/core
    ```
  </CodeGroup>
</View>

<View title="React" icon="react">
  <CodeGroup>
    ```shell pnpm theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
    pnpm add @suki-sdk/react @suki-sdk/core
    ```

```shell npm theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
    npm install @suki-sdk/react @suki-sdk/core
    ```

```shell yarn theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
    yarn add @suki-sdk/react @suki-sdk/core
    ```
  </CodeGroup>
</View>

For detailed setup instructions, refer to the [Installation guide](/web-sdk/installation).

### Step 1: Initialize the SDK

Initialize the Suki SDK by creating `SukiAuthManager` from `@suki-sdk/core` with the following **required** fields:

* `partnerId` <Badge>Required</Badge> - Your partner ID from Suki
* `partnerToken` <Badge>Required</Badge> - Your partner token from Suki
* `providerName` <Badge>Required</Badge> - The full name of the provider
* `providerOrgId` <Badge>Required</Badge> - The organization ID of the provider

Then pass this `authManager` into `initialize()` in JavaScript or `init()` in React.

Run initialization **once**, usually from your app **entry point**, so your app can sign in to Suki and use Web SDK features.

<View title="JavaScript" icon="js">
  Import `@suki-sdk/core` and `@suki-sdk/js`, create `SukiAuthManager` with your partner token and provider fields, then call `initialize({ authManager })`. Do this in your main application file (for example `index.js` or `app.js`).

```js main.js theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
  import { SukiAuthManager } from "@suki-sdk/core";
  import { initialize } from "@suki-sdk/js";

const sdkClient = initialize({
    authManager,
  });
  ```
</View>

<View title="React" icon="react">
  In **Web SDK v3**, your app root only needs `SukiProvider` from `@suki-sdk/react` (no partner props on the provider). In a child component, create `SukiAuthManager` from `@suki-sdk/core` with your `partnerId`, `partnerToken`, and provider fields, then call `init({ authManager })` from `useSuki()` when the SDK is not initialized yet. See `ComponentA.jsx` in the example below.

<CodeGroup>
    ```jsx App.jsx theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
    import { SukiProvider } from "@suki-sdk/react";

function App() {
      return (
        <SukiProvider>
          {/* init({ authManager }) runs in a child (ComponentA.jsx), not here */}
          <ComponentA />
        </SukiProvider>
      );
    }
    ```

```jsx ComponentA.jsx theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
    import { useEffect, useMemo } from "react";
    import { SukiAuthManager } from "@suki-sdk/core";
    import { useSuki } from "@suki-sdk/react";

function ComponentA() {
      const authManager = useMemo(
        () =>
          new SukiAuthManager({
            partnerId: "f80c8db8-a4d0-4b75-8d63-56c82b5413f0", // Replace with your actual partner ID
            partnerToken:
              "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiYWRtaW4iOnRydWUsImlhdCI6MTUxNjIzOTAyMn0.KMUFsIDTnFmyG3nMiGM6H9FNFUROf3wh7SmqJp-QV30", // Replace with your actual partner token
            providerName: "John doe", // Replace with the full name of the provider
            providerOrgId: "1234", // Replace with the provider's organization ID
            environment: "production",
            loginOnInitialize: true,
            providerId,
            providerName,
            providerOrgId,
            providerSpecialty,
          }),
        [],
      );

const { init, isInitialized } = useSuki();

useEffect(() => {
        if (!isInitialized) {
          init({ authManager });
        }
      }, [init, isInitialized, authManager]);

return (
        // rest of your code
        <>{/* your ComponentA content */}</>
      );
    }
    ```
  </CodeGroup>
</View>

### Mount the SDK UI

After initializing the web SDK, you can mount the Suki UI into your application using the [`encounter`](/web-sdk/api-reference/types/encounter) object. This object provides patient context for ambient documentation and transcription.

<Note>
  **Encounter and patient IDs:** **`patient.identifier`** and **`encounter.identifier`** (when you set it) must each be strings **at most 36 characters** (<Tooltip href="/Glossary/v#varchar-36">varchar(36)</Tooltip>). Longer values can fail during composition or ambient setup. See [Patient](/web-sdk/api-reference/types/patient) and [Encounter](/web-sdk/api-reference/types/encounter).
</Note>

<Note>
  If you face any issues while mounting the SDK UI, make sure you are using the correct package and framework.
</Note>

<View title="JavaScript" icon="js">
  ```js main.js theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
  import { SukiAuthManager } from "@suki-sdk/core";
  import { initialize } from "@suki-sdk/js";

const sdkClient = initialize({
    authManager,
  });

// unsubscribe from the init event when no longer needed
  window.addEventListener("beforeunload", () => {
    unsubscribeInit();
  });
  ```
</View>

<View title="React" icon="react">
  ```jsx ComponentA.jsx theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
  import { useEffect, useMemo } from "react";
  import { SukiAuthManager } from "@suki-sdk/core";
  import { useSuki, SukiAssistant } from "@suki-sdk/react"; // Mount UI: add SukiAssistant

const { init, isInitialized } = useSuki();

// replace this with your actual encounter data
    const currentEncounter = {  // Mount UI: encounter for SukiAssistant
      identifier: "6ec3920f-b0b1-499d-a4e9-889bf788e5ab",
      patient: {
        identifier: "905c2521-25eb-4324-9978-724636df3436",
        name: {
          use: "official",
          family: "Doe",
          given: ["John"],
          suffix: ["MD"],
        },
        birthDate: "1990-01-01",
        gender: "Male",
      },
    };

useEffect(() => {
      if (!isInitialized) {
        init({ authManager });
      }
    }, [init, isInitialized, authManager]);

return ( //Mount UI: SukiAssistant 
      <SukiAssistant encounter={currentEncounter} />
      // rest of your code
    );
  }
  ```
</View>

## Next steps

<Icon icon="file-lines" /> Refer to our [Ambient documentation guide](/web-sdk/guides/ambient) to learn more about how to use the Suki Web SDK to create your first ambient session.