Web SDK Quickstart

This guide walks you through setting up Suki.js in your existing JavaScript or React application, from installation to mounting the SDK UI. What will you do

Install the Suki Web SDK package for your framework (JavaScript or React).
Initialize the SDK by creating a SukiAuthManager from @suki-sdk/core with your partnerToken and provider fields.
Mount the SDK UI into your application using the encounter object.

Using an AI coding tool?Copy the prompt below to point your agent at the Ambient skill and Documentation MCP. For every task skill, refer to AI coding tools.

Fetch the Ambient skill and connect the documentation MCP.

Open in Cursor

Prerequisites

For the rest of this documentation, we assume the following setup is complete:

You have received your partnerId from Suki.
Your host URLs are on the Suki allowlist.
Your partner configuration in the Suki Platform points to your correct JWKS endpoint.
Your JWT token contains the key that you specified as your User identifier field.

Steps

Install the Suki SDK Package

Install the Suki Web SDK package in your project. Choose the appropriate package based on your framework.

You must choose the appropriate package based on your framework. Refer to the Installation guide for more information.

pnpm add @suki-sdk/js @suki-sdk/core

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

yarn add @suki-sdk/js @suki-sdk/core

For detailed setup instructions, refer to the Installation guide.

Initialize the SDK

Initialize the Suki SDK by creating SukiAuthManager from @suki-sdk/core with the following required fields:

partnerId Required - Your partnerId from Suki.
partnerToken Required - Your partnerToken from Suki.
providerName Required - The full name of the provider.
providerOrgId Required - The organization ID of the provider.

Then pass this authManager into initialize() in JavaScript or init() in React.Run initialization once, usually from your app entry point, so your app can sign in to Suki and use Web SDK features.

Import @suki-sdk/core and @suki-sdk/js, create SukiAuthManager with your partnerToken and provider fields, then call initialize({ authManager }). Do this in your main application file (for example index.js or app.js).

main.js

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
  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",
  loginOnInitialize: true,
  providerId,
  providerName,
  providerOrgId,
  providerSpecialty,
});

const sdkClient = initialize({
  authManager,
});

Mount the SDK UI

After initializing the Web SDK, mount the Suki UI into your application using the encounter object. This object provides patient context for Ambient documentation and transcription.

Encounter and patient IDs:

patient.identifier is required. encounter.identifier is optional. Both must be strings of at most 36 characters (). Longer values can fail during composition or ambient setup.
From Web SDK v3.2.0, if you set encounter.identifier, use a UUID. The Web SDK maps that value to emr_encounter_id for ambient interoperability and encounter note retrieval.
Non-UUID values can break past-note loading even when ambient session start, pause, and submit still work. See Patient, Encounter type definitions for more information.

If you face any issues while mounting the SDK UI, make sure you are using the correct package and framework.

main.js

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",
  loginOnInitialize: true,
  providerId,
  providerName,
  providerOrgId,
  providerSpecialty,
});

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

Verify your integration

After you record and stop your first ambient session, you should see:

The generated clinical note automatically appears in the mounted SukiAssistant UI panel.
Sections are organized according to your LOINC configuration.
The transcript is available within the UI.

Next steps

Refer to our Ambient documentation guide to learn more about how to use the Suki Web SDK to create your first ambient session.

Get Started

Concepts & Feature Guides

API Reference

Resources

Web SDK Quickstart

Prerequisites

Steps

Verify your integration

Next steps

​Prerequisites

​Steps

​Verify your integration

​Next steps

Prerequisites

Steps

Verify your integration

Next steps