Suki SDKs & APIs Technical Execution

Technical Execution

Learn how to integrate Suki SDKs and APIs into your product. This guide covers how integration works, what partners need, a typical timeline, and critical technical requirements by surface.

For business context, use cases, and partnership outcomes, start with thefor product and engineering leaders.

How Integration Works?

All Suki integrations follow the same four implementation phases, regardless of the SDK or API you choose. The exact implementation details vary by integration option. Use the expanded sections below for product-specific guidance and implementation checklists.

Setup and Configuration

Partner ID, security (JWKS), and environment setup. Install the Web or Headless package, embed the Mobile SDK, or configure REST API clients.

Authentication

Connect your IdP, issue partner tokens, and validate access for embedded SDKs or server-side REST API calls.

Ambient Session and AI

Run sessions with Web or Headless UI, native mobile capture, or API-driven flows. Stream audio, receive transcript and structured clinical note.

Note Delivery

Receive structured payloads (JSON), map to your formats, and route to chart, record, or downstream systems.

What partners need

To use our developer tools, you need to have the following:

Identity and Security

Use your existing identity and access management system, such as OAuth 2.0. Suki integrates with the authentication framework you already use.

Development Environment

Support for a modern web or mobile application. Suki integrates with standard development frameworks and deployment models.

Clinical Configuration

Configure Suki to match your clinical specialties, documentation workflows, and organizational requirements for high quality outputs.

Structured Data Integration

Receive structured clinical data and connect it to your EHR, care management, billing, or other downstream systems.

Audio Capabilities

Support secure audio capture through standard browser or mobile microphone access over HTTPS.

User and Organization Context

Provide user and organization identifiers so Suki can securely associate sessions with the correct clinician, role, and tenant.

01 Kickoff

Partner onboarding and environment setup.

Week 1

02 Build & customize

SDK integration and UI customization so the experience matches your product.

Week 2–3

03 Validate & ship

Testing, QA, and production deployment with confidence.

Week 4

04 Go-live

Go live with a controlled rollout, monitor usage and quality, and iterate.

Go-live

Goal Aligned plan, scope, and success criteria.

Goal Integrated solution in your environment.

Goal Validated solution that meets quality and security standards.

Goal Successful launch and continuous improvement.

Total time to value: 2-4 weeks From start to production launch. Compare that to 6-12 months building ambient AI from scratch.

Integration Checklists

These five areas require attention for smooth deployment. Each requirement is standard for modern healthcare web applications.

Authentication

Requirements

OAuth 2.0 compliant identity provider or custom JWT generation system
Publicly accessible JWKS endpoint (HTTPS) for token verification
JWT tokens signed with RS256 algorithm
Required claims: exp, iss, aud, and user identifier

Why it matters: Secure authentication is the foundation of trust. Get this right from the start, and everything else flows smoothly.

Partner Authentication Guide

Installation

Requirements

React or JavaScript development environment
Node.js with npm, pnpm, or yarn package manager
ES6 compatible browser environment

Package selection

React apps: install @suki-sdk/react
Non-React browser apps: install @suki-sdk/js

Why it matters: Match the package to the stack. React apps get React-optimized components. The JS package targets browser JavaScript outside React. This avoids unnecessary complexity.

Installation Guide

Specialties information

Requirements

List of medical specialties the application supports
Understanding of LOINC codes for clinical note sections
Mapping between encounter types and appropriate LOINC codes

Why it matters: 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.

Supported Specialties LOINC Codes and Note Sections Specialty Context

Note output and downstream integration

Requirements

Infrastructure to receive note submission events or callbacks
Logic to parse LOINC-encoded JSON structure
Workflow to map Suki’s output format to your systems of record or handoff targets

Why it matters: 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.

Note Submission and Retrieval

Microphone permissions

Requirements

Microphone access permission flow in the application
HTTPS connection for production (required for microphone access)
Iframe configuration if embedding: add allow=“microphone; clipboard-write; clipboard-read” attributes

Why it matters: Audio capture is essential. Without proper microphone permissions, the system can’t function. Ensure permissions are requested and iframe configurations are correct.

Iframe Permissions Guide

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.

Authentication and tokens

Requirements

Implement tokenProvider protocol so the mobile SDK can request authentication tokens when needed
Pass PartnerID, ProviderInfo, and related fields to initialize as described in configuration guide
Use .stage for development and .prod for production

Why it matters: The SDK exchanges tokens with Suki services on a predictable contract. A correct token provider and initialization payload avoid auth failures during sessions.

Partner Authentication Prerequisites Configuration

Installation and platform

Requirements

Xcode project targeting iOS 13.0 or later
SukiAmbientCore.framework added, embedded, and set to Embed & Sign
NSMicrophoneUsageDescription in Info.plist with a clear, user-facing explanation

Why it matters: Apple enforces microphone disclosure and embedding rules. A correct deployment target and framework embedding prevent runtime crashes and App Store rejection.

Prerequisites Mobile SDK Installation

Session lifecycle and delegates

Requirements

Session delegate implementation for lifecycle and status updates
Recording flows aligned with your UX: start, pause, resume, end, and cancel as needed
Background recording flag in initialize when your product requires it

Why it matters: ambient capture is stateful. Delegates keep your UI and backend logic in sync with SDK events and errors.

Create Session Recording Controls

Content and downstream integration

Requirements

Logic to poll or receive structured content when a session completes
Mapping of structured output into your EHR, exports, or internal services
Offline mode awareness: recording can continue when the network is unstable; sync when connectivity returns

Why it matters: Clinical value lands when notes reach the right system. Plan retrieval and persistence before go-live.

Session Status and Content Retrieval

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.

Authentication and tokens

Requirements

HTTPS-only clients; obtain an sdp_suki_token via login using partner_id, partner_token, and provider_id as documented
Partner JWTs issued consistently with your JWKS and Suki validation rules
Secure storage and rotation of credentials in your services

Why it matters: API access is token-driven. Misconfigured login or partner tokens surface as 401s across session and content calls.

Authentication API Quickstart

Endpoints and environments

Requirements

Correct base URL and API version for stage versus production
Use of versioned paths (for example, /api/v1/…) per resource
Follow our HTTPS guidelines and documented status codes

Why it matters: Environment mix-ups cause subtle failures. Pin URLs per environment in configuration, not in scattered constants.

API Overview HTTPS Guidelines

ambient operations

Requirements

REST flows for ambient session lifecycle and ambient content as your integration requires
Audio or streaming integrations where the API uses WebSockets for real-time transmission
Webhook or polling patterns if your architecture consumes async completion signals

Why it matters: ambient features span REST and streaming. Plan both client behavior and server-side orchestration up front.

Ambient session Management Ambient Content Retrieval

Operational readiness

Requirements

Retry and error-handling policies aligned with your SLA and the platform’s HTTP semantics
Logging and monitoring that avoid PHI in unsecured logs
Load and rate expectations validated with your Suki contact for high-volume workloads

Why it matters: Production APIs need observability and safe handling of transient failures, especially in clinical workflows.

Webhook Notifications

Partner authentication and tokens are the same as the Web SDK. Headless differs because you build your own UI and integrate useAuth, ambient hooks, and related APIs instead of pre-built components.

Authentication

Requirements

Same partner authentication checklist as the Web SDK tab.

OAuth 2.0 compliant identity provider or custom JWT generation system
Publicly accessible JWKS endpoint (HTTPS) for token verification
JWT tokens signed with RS256 algorithm
Required claims: exp, iss, aud, and user identifier

Why it matters: It is the same trust model as the Web SDK. In Headless you connect tokens through useAuth and related hooks; auth gaps block Ambient APIs until identity is wired correctly.

Partner Authentication Guide Headless Authentication

Installation and runtime

Requirements

React 18.0 or higher
Install @suki-sdk/platform-react with npm, pnpm, or yarn
ES6-compatible browser environment

Why it matters: The package ships React hooks. Version and bundler assumptions must match what we test and support.

Headless Installation

Partner configuration

Requirements

partnerId from Suki during onboarding
Test and production host URLs allowlisted for your app
User identifier field in the JWT agreed during onboarding and reflected in tokens

Why it matters: Headless initialization fails fast when hosts or user identity keys do not match what Suki configured for your tenant.

Prerequisites Partner Onboarding

ambient hooks and browser permissions

Requirements

Integrate ambient and session hooks per quickstart; handle pending, error, and completion states in your UI
Microphone permission UX and HTTPS in production
If you embed in an iframe, set appropriate allow attributes for microphone (and clipboard if needed)

Why it matters: You own the experience. Explicit permission and error paths keep capture reliable for clinicians.

Headless Quickstart Ambient Hook

Dictation embeds a hosted iframe in your web app. You supply partner credentials, mount the surface in your layout, and wire SukiAuthManager and DictationClient (or React equivalents) instead of building capture UI yourself.

Authentication and partner credentials

Requirements

partnerId and partnerToken from Suki after partner onboarding
SukiAuthManager from @suki-sdk/core with provider fields and staging or production environment
Successful login before the Dictation iframe can initialize

Why it matters: Invalid or missing credentials block iframe initialization. Auth must be stable before clinicians open Dictation.

Partner Authentication Guide Dictation Authentication

Installation and runtime

Requirements

Browser client with HTMLIFrameElement and postMessage (not Node.js or SSR-only rendering for the iframe)
Install @suki-sdk/core plus @suki-sdk/dictation or @suki-sdk/dictation-react
HTTPS in production for secure iframe and platform calls

Why it matters: Dictation is browser-hosted. Package and runtime choices must match the integration track you ship.

Dictation Installation Dictation Quickstart

Layout and iframe hosting

Requirements

A mount container (rootElement) with real height and a stable layout box
overflow: visible on wrappers when minimized or floating so the iframe is not clipped
If embedded in an iframe, appropriate allow attributes for microphone and clipboard as needed

Why it matters: The hosted surface sizes to your DOM. Clipping or zero-height containers hide Dictation or break interaction.

Dictation Prerequisites Dictation Configuration

Session modes and callbacks

Requirements

Choose in-field or scratchpad mode and pass ShowOptions per session
Wire submit, cancel, and draft callbacks so your app persists dictated text
Error handling for auth failures, layout issues, and iframe load problems

Why it matters: You own the surrounding UX. Mode and callback wiring determine how dictated content returns to your fields or charts.

In-Field Mode Dictation Callbacks

Form filling embeds a hosted iframe in your web app. You supply partner credentials and Medical form template IDs, mount the surface in your layout, and wire SukiAuthManager and FormFillingClient (or React equivalents) instead of building capture UI yourself.

Authentication and partner credentials

Requirements

partnerId and partnerToken from Suki after partner onboarding
SukiAuthManager from @suki-sdk/core with optional provider fields and staging or production environment
Successful login before the Form filling iframe can initialize

Why it matters: Invalid or missing credentials block iframe initialization. Auth must be stable before clinicians open Form filling.

Partner Authentication Guide Form filling Authentication

Installation and runtime

Requirements

Browser client with a sized container for the hosted iframe (not Node.js or SSR-only rendering for the iframe)
Install @suki-sdk/core plus @suki-sdk/form-filling or @suki-sdk/form-filling-react
HTTPS in production for secure iframe, microphone access, and platform calls

Why it matters: Form filling is browser-hosted. Package and runtime choices must match the integration track you ship.

Form filling Installation Form filling Quickstart

Templates, layout, and CSP

Requirements

template_id UUIDs from Suki support in form_template_ids (staging and production IDs differ)
A mount container with explicit height so the hosted UI is visible
frame-src in Content-Security-Policy allowing https://sdk.suki.ai (production) or https://sdk.suki-stage.com (staging)
Optional correlation_id (your encounter ID) to match results in callbacks and webhooks

Why it matters: Unsupported template IDs fail at start time. Zero-height containers or blocked iframe origins hide Form filling or trigger handshake errors.

Form filling Prerequisites Form filling Configuration

Session workflow, callbacks, and webhooks

Requirements

Single-form or multi-form sessions: pass one or more template_id values per workflow
Wire onSubmit, cancel, and error callbacks; map structured_data.generated_values into your EHR
Register a partner webhook for production so structured data reaches your server if the tab closes before processing finishes

Why it matters: Submit starts processing; structured JSON arrives later. Browser callbacks plus server webhooks keep form data from being lost.

Session Workflow Webhook Handler Example

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.

Authentication and tokens

Requirements

OAuth-compliant authentication and JWTs with consistent user identifiers
Publicly accessible JWKS endpoint (HTTPS) for token verification
Partner credentials: register providers, then obtain a Suki Token via login

Why it matters: Form filling REST and WebSocket calls are token-driven. Misconfigured login or JWKS surfaces as auth failures across the workflow.

Form filling authentication Partner Authentication Guide

Endpoints and environments

Requirements

Correct base URL and API version for stage versus production
Versioned Form filling paths under /api/v1/form-filling/…
HTTPS-only clients and documented HTTP status handling

Why it matters: Environment mix-ups cause subtle failures. Pin URLs and credentials per environment in configuration.

Form filling API Overview HTTPS Guidelines

Session lifecycle and audio streaming

Requirements

Create a Form filling session and seed context (template and encounter metadata) when needed
Stream audio on GET /ws/stream using the Form filling ambient_session_id
End the session and monitor status until processing completes

Why it matters: Capture spans REST and WebSocket. Use the Form filling session ID on the shared stream so audio maps to the correct workflow.

Form filling API quickstart Ambient Audio Streaming

Structured output and operations

Requirements

Poll status and structured-data endpoints, or subscribe to webhooks for completion
Map structured form fields into your EHR, exports, or internal services
Retry, logging, and PHI-safe observability aligned with your SLA

Why it matters: Clinical value lands when populated forms reach the right system. Plan retrieval, validation, and handoff before go-live.

Form filling content retrieval Webhook Notifications