Step-by-step guided journey to integrate Suki using Ambient, Form filling, or Patient Summary workflows with the Web SDK, Headless Web SDK, Mobile SDK, Form filling SDK, or REST APIs
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.
Estimated Total Time: 4-6 weeks from start to production deployment
Depending on the workflow you choose, you will need to choose the best integration method for your application. Ambient, Dictation, and Form filling offer SDK and API paths. Patient Summary is API-first: your application owns the clinician UI while you call Patient Summary APIs for CKG ingestion, generation, and retrieval.Refer to the Integration paths overview for more information about the different workflows and how to choose the best integration method for your application.
Install @suki-sdk/core plus @suki-sdk/react for React or @suki-sdk/js for plain JavaScript
npm install @suki-sdk/react @suki-sdk/core
Next: Initialize auth and the SDK client (see quickstart for your stack)
2
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.
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
3
First Ambient Session (45 Min)
Mount the SDK UI with an encounter and walk through recording and note generationWhat you’ll build: A simple flow that starts Ambient documentation, captures audio, and returns a clinical noteNext: Test with sample audio and verify note generation
Goal: Install the Headless Web SDK and wire authentication and ambient hooks in React
1
Install Package (15 Min)
Install the Headless Web SDK in a React 18+ project
npm install @suki-sdk/platform-react
Confirm your test and production host URLs are on the Suki allowlist (see Headless Web SDK prerequisites).Next: Add PlatformClient and PlatformClientProvider
Next: Authenticate with useAuth inside the provider tree
3
Authentication Hooks (45 Min)
Add the useAuth hook under the provider with your partnerId and partnerToken (see the Authentication hook guide)
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
4
Session and Recording (60 to 90 Min)
Create a session with useAmbient, then use useAmbientSession for recording lifecycle and statusWhat you’ll build: Your own controls and layout (start, pause, submit) backed by hook state, plus retrieval of note content when processing completesNext: Follow the quickstart through your first end-to-end recording, then harden error handlingFor step-by-step code, use the quickstart and Authentication hook, Ambient hook, and Ambient session hook guides.
Create a basic ambient session with recording capabilitiesWhat you’ll build: A view controller that can create sessions, record audio, and retrieve generated notesNext: Test with device microphone and verify functionality
Work with Suki’s Support team to get template_id UUIDs for form_template_ids.Next: Create SukiAuthManager and FormFillingClient once per page
2
Basic Configuration (30 Min)
Create SukiAuthManager from @suki-sdk/core with your partnerId, partnerToken, and provider fields. Create FormFillingClient with that auth manager. In React, wrap with FormFillingProvider and reuse the same client with useMemo.
import { useMemo } from 'react';import { SukiAuthManager } from '@suki-sdk/core';import { FormFillingClient, FormFillingProvider } from '@suki-sdk/form-filling-react';const client = useMemo(() => { const authManager = new SukiAuthManager({ partnerId: 'YOUR_PARTNER_ID', partnerToken: 'YOUR_PARTNER_TOKEN', environment: 'staging', loginOnInitialize: true, }); return new FormFillingClient({ authManager });}, []);
Next: Open a Form filling session with form_template_ids and correlation_id
3
First Form Filling Session (45 Min)
Give Form filling a container with explicit height, then call client.start() or render <FormFilling> with your template IDs and encounter ID as correlation_id.What you’ll build: A simple flow that opens the hosted Form filling UI, captures visit conversation by voice, and returns structured form output through onSubmit and your Partner webhookNext: Test with a supported Medical form template and verify structured outputFor step-by-step code, use the quickstart and Configuration and Session workflow guides.
Goal: Implement Form filling REST APIs and the shared Partner WebSocket in your application
1
Authentication Implementation (60 Min)
Implement the authentication flow to get Suki tokens for Form filling REST callsKey endpoints: /api/v1/auth/register, /api/v1/auth/loginNext: Test token generation and call Form filling session APIs with sdp_suki_token
2
Session and Context (75 Min)
Create a Form filling session and optionally seed template context before audio captureKey endpoints:
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.
Next: List templates if needed, then open the audio WebSocket
3
Audio Streaming (90 Min)
Stream visit audio on the Partner WebSocket using your Form filling session IDConnection: wss:// to GET /ws/stream (same wire format as ambient; see Ambient audio streaming)Sequence: START_TIME, AUDIO chunks (Base64 PCM), AUDIO with EOF (RU9G), close the WebSocket, then call session end on RESTNext: Poll status or configure a webhook for completion
4
Structured Output (45 Min)
End the session, monitor processing, and retrieve populated form fieldsKey endpoints:
POST/api/v1/form-filling/session/{ambient_session_id}/end - End session.
GET/api/v1/form-filling/session/{ambient_session_id}/structured-data - Get generated_values and non_generated_values.
Optional: Webhook notifications when processing finishesWhat you’ll build: An end-to-end flow from login through structured form output in your UI or downstream systemsNext: Test in-person and virtual scenarios, then harden error handling
Goal: Select how to integrate Patient Summary for pre-visit workflows in your application
Patient Summary APIs
Best for: Custom web, mobile, or backend integrations that own schedule and chart UI
Upload FHIR data into Suki’s Clinical Knowledge Graph (CKG).
Trigger asynchronous generation for a schedule or a single encounter.
Retrieve full and pre-visit summaries for clinical review.
Patient Summary does not currently ship a client SDK or hosted clinician UI. Integrate through the Patient Summary APIs and render summary sections in your own application.
Prerequisites: and working authentication from Foundation setup (Steps 1–2), plus ability to sign the SDP JWT required for CKG ingestionTime: 1-2 hours to evaluate options and read the decision guide
Goal: Implement Patient Summary REST APIs for CKG ingestion, summary generation, and retrieval
1
Authentication Implementation (60 Min)
Implement the authentication flow to get Suki tokens for Patient Summary REST calls, and confirm you can sign the SDP JWT used for CKG Data IngestionKey endpoints: /api/v1/auth/register, /api/v1/auth/loginNext: Test token generation, then request a CKG upload URL with your SDP JWT bearer token
2
CKG FHIR Ingestion (75 Min)
Request an upload URL, upload a FHIR R4 bundle, and poll ingestion status until CKG processing completesKey endpoints:
Keep fhir_encounter_id and fhir_practitioner_id consistent between the ingested FHIR resources and later generation or retrieval calls. Do not trigger summary generation while ingestion is still running.
Next: Trigger summary generation for an encounter or a provider schedule
3
Summary Generation (60 Min)
Enqueue asynchronous Patient Summary generation for a single encounter or a provider’s scheduled appointmentsKey endpoints:
POST/api/v1/patient-summary/generate/encounter - Generate for one encounter.
POST/api/v1/patient-summary/generate/provider-schedule - Generate for a schedule batch.
Next: Poll job status until generation completes
4
Status and Retrieval (45 Min)
Poll generation status, then retrieve the full Patient Summary or pre-visit section for your schedule or chart UIKey endpoints:
GET/api/v1/patient-summary/{patient_summary_id} - Get full summary.
GET/api/v1/patient-summary/{patient_summary_id}/pre_visit - Get pre-visit summary.
What you’ll build: An end-to-end flow from FHIR upload through pre-visit summary display in your schedule, chart, or patient-profile UINext: Test morning clinic preparation and on-demand encounter scenarios, then harden empty states and error handlingFor step-by-step guidance, use the quickstart and Generate Patient Summaries and Retrieve Patient Summaries guides.
