Form Filling Implementation In Web SDK For JavaScript

Start Form filling sessions in JavaScript with SukiAuthManager, FormFillingClient, and start() callbacks in Web SDK

This guide shows how to integrate Form filling capabilities into a browser-based JavaScript application with the Suki Web SDK. You will create the Auth Manager and Form filling Client, then start a Form filling session by calling await formFillingClient.start({ ... }) from your own code when the clinician is ready.

Use this approach if you are building with vanilla JavaScript, or another non-React framework, and want to control when and where Form filling appears in your interface.

Let’s get started!

Prerequisites

Before you start:

• Install @suki-sdk/js and @suki-sdk/core or update to the latest version.
• Get your partnerId from Partner onboarding. Pass a partnerToken (JWT from your identity provider) with that Partner ID to sign in.
• Decide which forms to fill: Suki defined form templates (ask Suki support for the template IDs), your own form schema, or both. Refer to Dynamic Form filling.
• Have an encounter ID ready to pass as correlation_id.
• Run the app in a browser over HTTPS, with microphone access, and a container with height for the Form filling UI.

For more setup detail, refer to Prerequisites.

Install the packages

Add both packages to the same project you load in the browser:

pnpm

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

After you install, pull the SDK into your files with import, the same way as in the examples below. Use whatever approach your project already uses for other npm libraries. Import FormFillingClient from @suki-sdk/js. You do not need @suki-sdk/form-filling.

Step 1: Add container HTML

The hosted Form filling UI mounts inside the element you pass as rootElement. That node must have real height, or the iframe looks blank.

HTML

<div id="suki-form-container" style="width: 100%; height: 600px;"></div>
<button type="button" id="fill-forms-btn">Fill Forms with Suki</button>

Refer to Configuration for recommended CSS.

Step 2: Create auth manager

Now create the Auth Manager. You need your partnerId from Partner onboarding and a partnerToken (JWT from your identity provider).

Create one auth manager for the page (or app shell).

Code example for creating auth manager

JavaScript

import { SukiAuthManager } from "@suki-sdk/core";

const authManager = new SukiAuthManager({
  partnerId: "YOUR_PARTNER_ID", // replace with your partner ID - required
  partnerToken: "YOUR_PARTNER_TOKEN", // replace with your partner token - required
  environment: "staging", // optional: "staging" | "production"
  loginOnInitialize: true, // optional: sign in as soon as this runs
  autoRegister: false, // optional: enable provider auto-registration
  providerId: "YOUR_PROVIDER_ID", // optional: provider identifier in your system
  providerName: "YOUR_PROVIDER_NAME", // optional: full provider display name
  providerOrgId: "YOUR_PROVIDER_ORG_ID", // optional: organization identifier for the provider in your system
  providerSpecialty: "YOUR_PROVIDER_SPECIALTY", // optional: clinical specialty
});

Step 3: Create Form filling client

After you have created the auth manager, you can create the Form filling client for your application. The Form filling Client is the object that will be used to start the Form filling session.

Create one Form filling client and reuse it for every start() call on that page.

Code example for creating Form filling client

JavaScript

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

const formFillingClient = new FormFillingClient({
  authManager,
  onError: (err) => console.error(err.code, err.reason, err.message),
});

Step 4: Call start() to open Form filling

Now you can start the Form filling session by calling the start() method on the Form filling client.

Call await formFillingClient.start({ ... }) from a click handler (or similar) when the DOM is ready. Pass rootElement, forms, onSubmit, and any optional fields you need. In forms, use Suki template IDs, your own schema, or both. Refer to Configuration for the full option list.

Code example for starting Form filling (static + dynamic)

JavaScript

async function openFormFilling() {
  const root = document.getElementById("suki-form-container");

  if (!root) {
    console.error("Missing suki-form-container in the DOM");
    return;
  }

  await formFillingClient.start({
    rootElement: root, // DOM element where Form filling mounts - required
    correlation_id: "YOUR_ENCOUNTER_ID", // encounter or appointment ID - optional but recommended
    forms: [ // New in v3.3.1
      { form_template_id: "YOUR_TEMPLATE_ID" },
      {
        id: "partner-vitals-1",
        name: "Custom vitals",
        type: "VITALS_ASSESSMENT",
        schema: {
          items: [
            {
              id: "heart_rate",
              type: "int",
              question: "Heart rate?",
              unit: "bpm",
              min: 0,
              max: 300,
            },
          ],
        },
      },
    ],
    onReady: () => {
      console.log("Form UI ready");
    },
    onSubmit: (result) => {
      for (const row of result.structured_data.generated_values ?? []) {
        // Dynamic: match row.partner_form_id === "partner-vitals-1" // New in v3.3.1
        // Static: match row.form_template_id or title
        console.log(row.partner_form_id, row.form_template_id, row.data);
      }
    },
    onCancel: () => {
      console.log("Form filling cancelled");
    },
  });
}

document.getElementById("fill-forms-btn")?.addEventListener("click", () => {
  void openFormFilling();
});

onSubmit is required. It runs when structured JSON is ready after processing, not when the clinician taps submit in the hosted UI.

start() does not throw errors. If something goes wrong, the SDK calls onError on FormFillingClient (or the form-filling:error event). Set that up when you create the client in Step 3.

Each forms[] entry must use exactly one of form_template_id (Suki template) or schema (your form). You can mix both entry types in one session.

Callbacks

You can pass onReady, onSubmit, and onCancel on start(), or listen with formFillingClient.on() for handlers that stay active across many sessions:

JavaScript

formFillingClient.on("form-filling:submitted", (result) => {
  console.log(result.ambient_session_id);
});

Refer to Callbacks for the FormFillingResult shape and Events for every event and payload.

Starting another session

Calling start() again replaces the active session. You do not need to call stop() manually just to open Form filling again:

JavaScript

await formFillingClient.start({ /* encounter A options */ });
await formFillingClient.start({ /* encounter B options */ });

Complete code example

Below is a complete code example in JavaScript for Form filling with a single container and button.

JavaScript

import { SukiAuthManager } from "@suki-sdk/core";
import { FormFillingClient } from "@suki-sdk/js";

const authManager = new SukiAuthManager({
  partnerId: "YOUR_PARTNER_ID", // replace with your partner ID - required
  partnerToken: "YOUR_PARTNER_TOKEN", // replace with your partner token - required
  environment: "staging", // optional: "staging" | "production"
  loginOnInitialize: true, // optional: sign in as soon as this runs
  autoRegister: false, // optional: enable provider auto-registration
  providerId: "YOUR_PROVIDER_ID", // optional: provider identifier in your system
  providerName: "YOUR_PROVIDER_NAME", // optional: full provider display name
  providerOrgId: "YOUR_PROVIDER_ORG_ID", // optional: organization identifier for the provider in your system
  providerSpecialty: "YOUR_PROVIDER_SPECIALTY", // optional: clinical specialty
});

const formFillingClient = new FormFillingClient({
  authManager,
  onError: (err) => console.error(err.code, err.message),
});

async function openFormFilling() {
  const root = document.getElementById("suki-form-container");
  if (!root) return;

  await formFillingClient.start({
    rootElement: root,
    correlation_id: "YOUR_ENCOUNTER_ID",
    forms: [ // New in v3.3.1
      { form_template_id: "YOUR_TEMPLATE_ID" },
      {
        id: "partner-vitals-1",
        name: "Custom vitals",
        schema: {
          items: [
            { id: "heart_rate", type: "int", question: "Heart rate?", unit: "bpm" },
          ],
        },
      },
    ],
    onReady: () => console.log("Form UI ready"),
    onSubmit: (result) => {
      for (const row of result.structured_data.generated_values ?? []) {
        console.log(row.partner_form_id, row.form_template_id, row.data); // New in v3.3.1
      }
    },
    onCancel: () => {
      console.log("Cancelled");
    },
  });
}

document.addEventListener("DOMContentLoaded", () => {
  document
    .getElementById("fill-forms-btn")
    ?.addEventListener("click", () => void openFormFilling());
});

Your integration is working when the Form filling UI appears, the microphone is active, and onSubmit returns structured_data.

Best practices

• Reuse one Form filling client. Build a single FormFillingClient for the page or shell and call it again for each session. Creating a new client on every click often resets the hosted UI and feels flaky.

• Reuse one auth manager. Create SukiAuthManager once and pass that same instance into the client, the same pattern as in the steps above.

• Pass templates, your schema, or both in forms. Use form_template_id for Suki Medical form templates and schema for your own forms. Keep template IDs unique, and keep dynamic id values unique.

• Handle when structured results arrive. You must supply onSubmit so the SDK can deliver structured_data. For dynamic forms, map by partner_form_id (and/or name), not list index.

• Pass correlation_id. Use your encounter ID so callbacks and Partner webhooks match the correct record.

• Register a partner webhook for production saves on your server, not browser onSubmit alone.

• Open Form filling only when the host is ready. The DOM node you use as rootElement should exist and have real height before you open. Otherwise the Form filling area can look blank.

• Handle errors with onError. start() does not throw errors. When you create the client, pass onError (or listen for form-filling:error) so you can see what went wrong.

• Open again to start another session. A new start() call replaces the active session. You usually do not need a separate stop() step first.

Next steps

Configuration - forms, correlation_id, and callbacks.

Dynamic Form filling - XOR rules, schema shapes, and mixed sessions.

React integration - Integrate Form filling in a React application using the Suki Web SDK.