Skip to main content
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 in just a few steps.
New to Suki?Consider following our comprehensive Learning path for a structured, step-by-step journey from onboarding to production deployment with progress tracking and time estimates.
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 with
Estimated Time: 30-45 minutes
Using an AI coding tool?Copy the following prompt to add the Suki developer documentation as a skill and MCP server 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.

Install the Suki developer docs as a skill to get context on Suki's developer tools, APIs, and SDKs. Add the MCP server for documentation search.

Open in Cursor

​
Before you begin

To integrate your application with Suki developer tools, you must meet the following requirements:

OAuth-compliant authentication system

For secure user management

JWT tokens with consistent user identifiers

For user authentication

Publicly accessible JWKS endpoint

For token validation

ES6 compatible browser

Modern browser support (for Web SDK)
You’ll also need the following from Suki to get started:
  • : 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 () 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 and Partner authentication guides for more information.
Need Access?If you don’t have the required information yet, contact our partnership team to begin the onboarding process.

​
Step 1: Choose your use case and workflow

Select the integration method that best fits your application requirements: Refer to the Choose your workflow 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.

Web SDK

Best for: React/JavaScript web applicationsPre-built UI components with automatic state management

Mobile SDK

Best for: Native iOS applicationsNative framework optimized for mobile audio capture

Ambient APIs

Best for: Custom implementationsMaximum flexibility with direct API control
Headless Web SDK and Dictation SDK are additional integration options on Suki for Partners (Beta). Use the quickstarts below for install steps and configuration.
1

Install the package

Choose the appropriate package for your framework:
Bash
npm install @suki-sdk/js @suki-sdk/core
2

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 and Migrating to Web SDK v3.
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,
});
3

Mount UI

In the same component where you initialized the SDK, mount the SukiAssistant component with encounter data:
      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,
      });

      const unsubscribeInit = sdkClient.on("init:change", (isInitialized) => {
        if (isInitialized) {
          sdkClient.mount({
            rootElement: document.getElementById("suki-root"), // The root element to mount the SDK into
            encounter: encounterDetails,
          });
        }
      });

      // unsubscribe from the init event when no longer needed
      window.addEventListener("beforeunload", () => {
        unsubscribeInit();
      });
4

Start recording

Click the recording button in the Suki web SDK UI to start capturing the conversation.
5

Record for at least 1 minute

Record a test conversation. The session should be at least 1 minute long for note generation to occur.
6

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.
For complete web SDK capabilities, refer to the Web SDK section of the documentation.

​
Verify success

After completing your first session, you should see:
  • 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
Configure the generated note in many ways. For example, to generate a customized clinical note, refer to the LOINC codes to define the sections you want to generate.
{
  "sections": [
    {
      "loinc": "10164-2",
      "title": "History of Present Illness"
    },
    {
      "loinc": "51847-2", 
      "title": "Assessment and Plan"
    }
  ]
}

​
Success checklist

Before moving to production, ensure you have successfully completed these steps:
  • 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
  • Create an ambient session with patient information
  • You receive an ambient_session_id in the response
  • The session status is valid (not FAILED)
  • WebSocket connection establishes successfully
  • Audio chunks are being sent to Suki
  • No connection errors or timeouts occur
  • Session duration is at least 1 minute
  • 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)
  • 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

​
Troubleshooting

Problem: Login request returns 401 Unauthorized errorSolution:
  • 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
Problem: Cannot create ambient session or receive error responseSolution:
  • 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 () 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
Problem: WebSocket connection fails or immediately disconnectsSolution:
  • 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)
Problem: Session completes but status is SKIPPED and no note is generatedSolution:
  • 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
A SKIPPED status is expected for sessions shorter than 1 minute or with no audible speech. This is not a system error.
Problem: Audio streams but transcript is empty or note not generatedSolution:
  • 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
Problem: Session completes but content endpoint returns no data or incomplete noteSolution:
  • 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

​
Next steps

Refer to the Ambient Documentation Guide to learn more about how ambient documentation works. Refer to the Authentication Setup to understand how to authenticate your application with Suki. Refer to the Note Sections to customize the clinical note structure and LOINC codes. Refer to the API Reference to explore detailed API specifications.
Last modified on June 12, 2026