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 ambient session in just a few steps.

What You’ll Accomplish

By completing this guide, you will:

Set up authentication with Suki Platform
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 clinical note with transcript

Estimated Time: 30-45 minutes

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 Need Before Starting

To integrate your application with Suki Platform, 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)

Required Information From Suki

You’ll need the following from Suki to get started:

Partner ID - Unique identifier provided by Suki

How Does Authentication Work

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

Step 2: Integration Setup For API And SDKs

Once you have chosen your integration method, you can follow the following setup guide below to start building your application with Suki for Partners.

Web SDK

Install the Package

Choose the appropriate package for your framework:

JavaScript
React

Bash

npm install @suki-sdk/js

Initialize SDK

Wrap your app with SukiProvider and initialize the SDK:

import { initialize } from "@suki-sdk/js";

  const sdkClient = initialize({
    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
  });

Mount UI

In the same component where you initialized the SDK, mount the SukiAssistant component with encounter data:

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 sdkClient = initialize({
        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
      });

      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.

Mobile SDK

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:isMultingual
    ] 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.

Direct API

Authenticate and Get Token

Get your access token by calling the login endpoint: If not registered in Suki, you will need to call the register endpoint first. Call the Register endpoint 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 will receive a SKIPPED status, meaning no clinical note was generated.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:

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

For Mobile SDK:

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

For Direct API:

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 with speaker identification
GET request to /api/v1/ambient/session/{ambient_session_id}/status returns:
- status - Session status (created, ready, running, aborted, skipped, failed, completed)

Step 3:Advance Configuration (Optional But Recommended)

You can configure the generated note in many ways. For example, if you want to generate a customized clinical note, you should 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"
    }
  ]
}

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

Success Checklist

Before moving to production, ensure you have successfully completed these steps:

Authentication Works

You can 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

You can 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

You can 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 speaker identification is correct
LOINC sections match your requested configuration
Error handling is implemented for all API calls

Troubleshooting

Common Issues

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

Getting Help

Technical Issues: Review our FAQs
Integration Support: Contact our support team
Partnership Questions: Reach out to our partnership team

Welcome

​Overview

​What You’ll Accomplish

​What You Need Before Starting

OAuth-compliant authentication system

JWT tokens with consistent user identifiers

Publicly accessible JWKS endpoint

ES6 compatible browser

​Required Information From Suki

​How Does Authentication Work

​Step 1: Choose Your Integration Path

Web SDK

Mobile SDK

Direct APIs

​Step 2: Integration Setup For API And SDKs

​Web SDK

​Mobile SDK

​Direct API

​Verify Success

​Step 3:Advance Configuration (Optional But Recommended)

​Next Steps

Ambient Documentation Guide

Authentication Setup

Note Sections

API Reference

​Success Checklist

​Troubleshooting

​Common Issues

​Getting Help

Overview

What You’ll Accomplish

What You Need Before Starting

Required Information From Suki

How Does Authentication Work

Step 1: Choose Your Integration Path

Step 2: Integration Setup For API And SDKs

Web SDK

Mobile SDK

Direct API

Verify Success

Step 3:Advance Configuration (Optional But Recommended)

Next Steps

Success Checklist

Troubleshooting

Common Issues

Getting Help