> ## Documentation Index
> Fetch the complete documentation index at: https://developer.suki.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Web SDK Quickstart

> Install the Web SDK, create SukiAuthManager, and mount SukiAssistant with encounter data in JavaScript or React

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

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

<Tip>
  **Using an AI coding tool?**

  Copy the prompt below to point your agent at the Ambient skill and [Documentation MCP](/documentation/references/mcp). For every task skill, refer to [AI coding tools](/documentation/references/ai-coding-tools).

  <Prompt description="Fetch the Ambient skill and connect the documentation MCP." icon="gear" iconType="regular" actions={["copy", "cursor"]}>
    Build ambient clinical documentation with Suki for Partners.
    Fetch the Ambient build skill:
    [https://developer.suki.ai/.well-known/agent-skills/suki-ambient/SKILL.md](https://developer.suki.ai/.well-known/agent-skills/suki-ambient/SKILL.md)
    Connect the documentation MCP for page search:
    [https://developer.suki.ai/documentation/references/mcp](https://developer.suki.ai/documentation/references/mcp)
  </Prompt>
</Tip>

## 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**.

## Create your first Web SDK Ambient session

<Steps>
  <Step title="Install the Suki SDK Package">
    Install the Suki Web SDK package in your project. Choose the appropriate package based on your framework.

    <Tip>
      You must choose the appropriate package based on your framework. Refer to the [Installation guide](/web-sdk/installation) for more information.
    </Tip>

    <View title="JavaScript" icon="js">
      <CodeGroup>
        ```shell pnpm theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
        pnpm add @suki-sdk/js @suki-sdk/core
        ```

        ```shell npm theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
        npm install @suki-sdk/js @suki-sdk/core
        ```

        ```shell yarn theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
        yarn add @suki-sdk/js @suki-sdk/core
        ```
      </CodeGroup>
    </View>

    <View title="React" icon="react">
      <CodeGroup>
        ```shell pnpm theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
        pnpm add @suki-sdk/react @suki-sdk/core
        ```

        ```shell npm theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
        npm install @suki-sdk/react @suki-sdk/core
        ```

        ```shell yarn theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
        yarn add @suki-sdk/react @suki-sdk/core
        ```
      </CodeGroup>
    </View>

    For detailed setup instructions, refer to the [Installation guide](/web-sdk/installation).
  </Step>

  <Step title="Initialize the SDK">
    Initialize the Suki SDK by creating `SukiAuthManager` from `@suki-sdk/core` with the following **required** fields:

    * `partnerId` <Badge color="red" size="sm">Required</Badge> - Your `partnerId` from Suki.
    * `partnerToken` <Badge color="red" size="sm">Required</Badge> - Your `partnerToken` from Suki.
    * `providerName` <Badge color="red" size="sm">Required</Badge> - The full name of the provider.
    * `providerOrgId` <Badge color="red" size="sm">Required</Badge> - 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.

    <View title="JavaScript" icon="js">
      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`).

      ```js main.js theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
      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,
      });
      ```
    </View>

    <View title="React" icon="react">
      In **Web SDK v3**, your app root only needs `SukiProvider` from `@suki-sdk/react` (no partner props on the provider). In a child component, create `SukiAuthManager` from `@suki-sdk/core` with your `partnerId`, `partnerToken`, and provider fields, then call `init({ authManager })` from `useSuki()` when the SDK is not initialized yet. See `ComponentA.jsx` in the example below.

      <CodeGroup>
        ```jsx App.jsx theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
        import { SukiProvider } from "@suki-sdk/react";

        function App() {
          return (
            <SukiProvider>
              {/* init({ authManager }) runs in a child (ComponentA.jsx), not here */}
              <ComponentA />
            </SukiProvider>
          );
        }
        ```

        ```jsx ComponentA.jsx theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
        import { useEffect, useMemo } from "react";
        import { SukiAuthManager } from "@suki-sdk/core";
        import { useSuki } from "@suki-sdk/react";

        function ComponentA() {
          const authManager = useMemo(
            () =>
              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 { init, isInitialized } = useSuki();

          useEffect(() => {
            if (!isInitialized) {
              init({ authManager });
            }
          }, [init, isInitialized, authManager]);

          return (
            // rest of your code
            <>{/* your ComponentA content */}</>
          );
        }
        ```
      </CodeGroup>
    </View>
  </Step>

  <Step title="Mount the SDK UI">
    After initializing the Web SDK, mount the Suki UI into your application using the [`encounter`](/web-sdk/api-reference/types/encounter) object. This object provides patient context for Ambient documentation and transcription.

    <Note>
      **Encounter and patient IDs:**

      * `patient.identifier` is **required**. **`encounter.identifier`** is **optional**. Both must be strings of **at most 36 characters** (<Tooltip tip="VARCHAR is a variable-length SQL string type. varchar(36) caps these identifiers at 36 characters. See the Glossary." cta="View in Glossary" href="/Glossary/v#varchar-36">varchar(36)</Tooltip>). 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](/web-sdk/api-reference/types/patient), [Encounter](/web-sdk/api-reference/types/encounter) type definitions for more information.
    </Note>

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

    <View title="JavaScript" icon="js">
      ```js main.js theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
      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();
      });
      ```
    </View>

    <View title="React" icon="react">
      ```jsx ComponentA.jsx theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
      import { useEffect, useMemo } from "react";
      import { SukiAuthManager } from "@suki-sdk/core";
      import { useSuki, SukiAssistant } from "@suki-sdk/react"; // Mount UI: add SukiAssistant

      function ComponentA() {
        const authManager = useMemo(
          () =>
            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 { init, isInitialized } = useSuki();

        // replace this with your actual encounter data
        const currentEncounter = {  // Mount UI: encounter for SukiAssistant
          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",
          },
        };

        useEffect(() => {
          if (!isInitialized) {
            init({ authManager });
          }
        }, [init, isInitialized, authManager]);

        return ( //Mount UI: SukiAssistant
          <SukiAssistant encounter={currentEncounter} />
          // rest of your code
        );
      }
      ```
    </View>
  </Step>
</Steps>

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

## Available cookbooks

<div className="hp-io-method-grid tut-hub-card-grid" data-cookbook-related-grid>
  <a className="hp-io-method-card tut-hub-method-card" href="/documentation/cookbooks/seed-patient-context-for-web-sdk">
    <div className="tut-hub-card-media" aria-hidden="true" />

    <div className="hp-io-method-card-body">
      <div className="tut-hub-card-badges">
        <span className="hp-wn-badge hp-wn-badge-new">Ambient</span>
        <span className="hp-wn-badge cookbook-hub-badge-surface cookbook-hub-badge-surface--sdk">Web SDK</span>
      </div>

      <h3 className="hp-io-method-card-title">Seed Patient Context for the Web SDK</h3>

      <p className="hp-io-method-card-desc cookbook-hub-card-desc">
        Seed patient context for Web SDK.
      </p>

      <div className="hp-io-method-card-meta tut-hub-card-foot" aria-label="5 min">
        <div className="tut-hub-card-foot-meta">
          <span className="hp-io-method-card-meta-time">5 min</span>
        </div>
      </div>
    </div>
  </a>
</div>

## Available tutorials

<div className="hp-io-method-grid tut-hub-card-grid">
  <a className="hp-io-method-card tut-hub-method-card" href="/documentation/tutorials/web-sdk-ambient-react">
    <div className="tut-hub-card-media" aria-hidden="true" />

    <div className="hp-io-method-card-body">
      <span className="hp-wn-badge hp-wn-badge-new">Web SDK</span>
      <h3 className="hp-io-method-card-title">Build a Web SDK Ambient Session</h3>

      <p className="hp-io-method-card-desc">
        Authenticate, initialize the Web SDK in React, and mount SukiAssistant for an ambient encounter.
      </p>

      <div className="hp-io-method-card-meta tut-hub-card-foot" aria-label="15 min, Intermediate">
        <div className="tut-hub-card-foot-meta">
          <span className="hp-io-method-card-meta-time">15 min</span>
          <span className="tut-hub-level">Intermediate</span>
        </div>
      </div>
    </div>
  </a>
</div>

## Next steps

<Icon icon="file-lines" iconType="solid" /> Refer to our [Ambient documentation guide](/web-sdk/guides/ambient) to learn more about how to use the Suki Web SDK to create your first ambient session.