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.
Technical Execution
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.
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
- Web SDK
- Mobile SDK
- Suki REST APIs
- Headless Web SDK
- Dictation SDK
- Form Filling SDK
- Form Filling APIs
- Patient Summary APIs
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.
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.
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.
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.
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.
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 protocolso the mobile SDK can request authentication tokens when needed - Pass
PartnerID,ProviderInfo, and related fields toinitializeas described in configuration guide - Use
.stagefor development and.prodfor 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.
Installation and platform
Requirements
- Xcode project targeting iOS 13.0 or later
SukiAmbientCore.frameworkadded, embedded, and set to Embed & SignNSMicrophoneUsageDescriptioninInfo.plistwith 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.
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
initializewhen 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.
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.
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_tokenvia login usingpartner_id,partner_token, andprovider_idas 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.
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.
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.
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.
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.
Installation and runtime
Requirements
- React 18.0 or higher
- Install
@suki-sdk/platform-reactwith 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.
Partner configuration
Requirements
partnerIdfrom 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.
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
allowattributes for microphone (and clipboard if needed)
Why it matters: You own the experience. Explicit permission and error paths keep capture reliable for clinicians.
Dictation embeds a hosted iframe in your web app. You supply partner credentials, mount the Dictation UI in your layout, and wire SukiAuthManager and DictationClient (or React equivalents) instead of building capture UI yourself.
Authentication and partner credentials
Requirements
partnerIdandpartnerTokenfrom Suki after partner onboardingSukiAuthManagerfrom@suki-sdk/corewith 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.
Installation and runtime
Requirements
- Browser client with
HTMLIFrameElementandpostMessage(not Node.js or SSR-only rendering for the iframe) - Install
@suki-sdk/coreplus@suki-sdk/dictationor@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.
Layout and iframe hosting
Requirements
- A mount container (
rootElement) with real height and a stable layout box overflow: visibleon wrappers when minimized or floating so the iframe is not clipped- If embedded in an iframe, appropriate
allowattributes for microphone and clipboard as needed
Why it matters: The hosted Dictation UI sizes to your DOM. Clipping or zero-height containers hide Dictation or break interaction.
Session modes and callbacks
Requirements
- Choose in-field or scratchpad mode and pass
ShowOptionsper 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.
Form filling embeds a hosted iframe in your web app. You supply partner credentials and Medical form template IDs, mount the Form filling UI in your layout, and wire SukiAuthManager and FormFillingClient (or React equivalents) instead of building capture UI yourself.
Authentication and partner credentials
Requirements
partnerIdandpartnerTokenfrom Suki after partner onboardingSukiAuthManagerfrom@suki-sdk/corewith 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.
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/coreplus@suki-sdk/form-fillingor@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.
Templates, layout, and CSP
Requirements
template_idUUIDs from Suki support inform_template_ids(staging and production IDs differ)- A mount container with explicit height so the hosted UI is visible
frame-srcin Content-Security-Policy allowinghttps://sdk.suki.ai(production) orhttps://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.
Session workflow, callbacks, and webhooks
Requirements
- Single-form or multi-form sessions: pass one or more
template_idvalues per workflow - Wire
onSubmit, cancel, and error callbacks; mapstructured_data.generated_valuesinto 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.
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.
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.
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/streamusing the Form fillingambient_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.
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.
Patient Summary is API-first. Your backend authenticates, ingests FHIR data into the Clinical Knowledge Graph (CKG), triggers asynchronous summary generation, polls job status, then retrieves full or pre-visit summaries for display in your schedule and chart UI.
Authentication and tokens
Requirements
- OAuth-compliant authentication and JWTs with consistent user identifiers
- Publicly accessible JWKS endpoint (HTTPS) for token verification
- Obtain
sdp_suki_tokenfor generation, status, and retrieval calls - Generate and sign the SDP JWT required for CKG Data Ingestion
Why it matters: Patient Summary uses different auth surfaces for CKG ingestion and summary APIs. Misconfigured tokens surface as auth failures across upload, generation, and retrieval.
Endpoints and environments
Requirements
- Correct base URL and API version for stage versus production
- Versioned Patient Summary paths under
/api/v1/patient-summary/… - CKG ingestion paths under
/api/v1/fhir-push/… - 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.
CKG ingestion and generation
Requirements
- Ingest FHIR R4 bundles into CKG and wait until ingestion status is
COMPLETED - Keep
fhir_encounter_idandfhir_practitioner_idconsistent across ingestion, generation, and retrieval - Trigger scheduled or single-encounter generation from your backend
- Poll summary job status until a terminal status (
COMPLETED,FAILED, orABORTED)
Why it matters: Summaries are generated from CKG data only. Incomplete ingestion or identifier mismatch produces empty, failed, or missing results.
Retrieval and operations
Requirements
- Retrieve the full Patient Summary or pre-visit section only after status is
COMPLETED - Map summary sections into schedule, chart, or patient-profile UI
- Design empty states for no upcoming appointment and limited prior history
- Retry, logging, and PHI-safe observability aligned with your SLA
Why it matters: Clinical value lands when completed summaries reach the right clinician surface. Plan retrieval, empty states, and handoff before go-live.