Quickstart Guide

Overview

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.

Install the Suki developer docs as skill to get context on Suki’s developer tools, APIs, and SDKs.npx skills add https://developer.suki.aiThen add the Suki developer docs MCP server for access to documentation search. Follow the MCP instructions at https://developer.suki.ai/documentation/mcp.

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 integration path

Select the integration method that best fits your application requirements: Refer to the Integration decision guide to help you decide.

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

Direct 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.

Step 2: Integration setup for API and SDKs

Once you have chosen your integration method, select an option below. The setup guide for your chosen path will appear on this page.

Web SDK
Mobile SDK
Direct APIs

Install the package

Choose the appropriate package for your framework:

JavaScript
React

Bash

npm install @suki-sdk/js @suki-sdk/core

Bash

npm install @suki-sdk/react @suki-sdk/core

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,
});

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();
      });

Start recording

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

Record for at least 1 minute

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

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.

Install the framework

Add the Suki Mobile SDK to your iOS project following the Installation guide.

Initialize the SDK

Configure the SDK when your application starts:

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)")
}

Create session

Initialize an ambient session with patient information:

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)")
        }
    })

Start recording

Begin capturing the clinical conversation:

do {
    try SukiAmbientCore.shared.start()
} catch {
    print("Recording failed: \(error)")
}

Record for at least 1 minute

Capture audio for at least 1 minute to ensure note generation occurs.

End session

Stop the recording and trigger note generation:

do {
    try SukiAmbientCore.shared.end()
} catch {
    print("End session failed: \(error)")
}

Retrieve generated content

Get the generated clinical note and transcript:

// 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)")
    }
}

For complete mobile SDK capabilities, refer to the Mobile SDK section of the documentation.

Authenticate and get token

Get your access token by calling the login endpoint. If you have not registered with Suki, call the Register endpoint first to register a new user.

curl -X POST https://sdp.suki.ai/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 and must be included as sdp_suki_token header for all subsequent API calls.

Create ambient session

Start a new ambient session:

curl -X POST https://sdp.suki.ai/api/v1/ambient/session/create \
  -H "sdp_suki_token: YOUR_SUKI_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "ambient_session_id": "123dfg-456dfg-789dfg-012dfg",
    "encounter_id": "123dfg-456dfg-789dfg-012dfg",
    "multilingual": false
  }'

Save the ambient_session_id from the response. You’ll need it to stream audio and retrieve content.

Stream audio via WebSocket

Connect to the WebSocket endpoint to stream audio in real-time:

curl --request GET \
--url https://sdp.suki-stage.com/ws/stream \
--header 'ambient_session_id: <ambient_session_id>' \
--header 'sdp_suki_token: <sdp_suki_token>'

For non-browser clients, use separate headers: sdp_suki_token and ambient_session_id in the WebSocket upgrade request.

End session

Signal that the conversation is over to trigger note generation:

curl -X POST "https://sdp.suki.ai/api/v1/ambient/session/YOUR_SESSION_ID/end" \
  -H "sdp_suki_token: YOUR_SUKI_TOKEN"

Retrieve generated content

After ending the session, wait a few seconds for processing, then fetch the clinical note:

curl -X GET "https://sdp.suki.ai/api/v1/ambient/session/YOUR_SESSION_ID/content?cumulative=false" \
  -H "sdp_suki_token: YOUR_SUKI_TOKEN"

Session Duration RequirementYour 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 of the documentation.

Verify success

After completing your first session, you should see:

For Web SDK
For Mobile SDK
For SDP APIs

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

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

GET request to /api/v1/ambient/session/{ambient_session_id}/content returns:
- summary - Array of structured clinical note sections
GET request to /api/v1/ambient/session/{ambient_session_id}/transcript returns:
- final_transcript - Complete conversation transcript
GET request to /api/v1/ambient/session/{ambient_session_id}/status returns:
- status - Session status (created, ready, running, aborted, skipped, failed, completed)

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

Authentication Works

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

Session Creation Works

Create an ambient session with patient information
You receive an ambient_session_id in the response
The session status is valid (not FAILED)

Audio streaming works

WebSocket connection establishes successfully
Audio chunks are being sent to Suki
No connection errors or timeouts occur
Session duration is at least 1 minute

Content Retrieval Works

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)

Integration Quality

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

Common issues
Getting help

Authentication Failed - 401 Unauthorized

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

Session Creation Failed

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 valid UUIDs if provided
Check that multilingual is a boolean value (true/false)
Verify your partner account has the necessary permissions for ambient sessions

WebSocket Connection Failed

Problem: WebSocket connection fails or immediately disconnectsSolution:

Verify you’re using the correct WebSocket URL: wss://sdp.suki.ai/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)

Session status shows SKIPPED

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.

Audio Not Processing

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’re sending the end_of_stream message when done
Verify microphone permissions are granted in your application
Test with a known working audio sample first

Content Retrieval Returns Empty or Incomplete Data

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

Ambient Documentation Guide

Learn more about how ambient documentation works

Authentication Setup

Understand how to authenticate your application with Suki

Note Sections

Customize clinical note structure and LOINC codes

API Reference

Explore detailed API specifications

Get Started

Onboarding & Authentication

Product Capabilities

Guides

Help & Support

Quickstart Guide

Overview

Before you begin

OAuth-compliant authentication system

JWT tokens with consistent user identifiers

Publicly accessible JWKS endpoint

ES6 compatible browser

How authentication works

Step 1: Choose your integration path

Web SDK

Mobile SDK

Direct APIs

Step 2: Integration setup for API and SDKs

Verify success

Step 3: Advanced configuration (optional but recommended)

Success checklist

Troubleshooting

Next steps

Ambient Documentation Guide

Authentication Setup

Note Sections

API Reference

Get Started

Onboarding & Authentication

Product Capabilities

Guides

Help & Support

Documentation Index

​Overview

​Before you begin

OAuth-compliant authentication system

JWT tokens with consistent user identifiers

Publicly accessible JWKS endpoint

ES6 compatible browser

​How authentication works

​Step 1: Choose your integration path

Web SDK

Mobile SDK

Direct APIs

​Step 2: Integration setup for API and SDKs

​Verify success

​Step 3: Advanced configuration (optional but recommended)

​Success checklist

​Troubleshooting

​Next steps

Ambient Documentation Guide

Authentication Setup

Note Sections

API Reference

Overview

Before you begin

How authentication works

Step 1: Choose your integration path

Step 2: Integration setup for API and SDKs

Verify success

Step 3: Advanced configuration (optional but recommended)

Success checklist

Troubleshooting

Next steps