Form Filling SDK JavaScript Integration

Integrate the Form filling SDK in a JavaScript application using FormFillingClient

This guide walks you through integrating the Form filling SDK in a JavaScript application. You create SukiAuthManager and FormFillingClient once, then call client.start() when the clinician opens Form filling.

Prerequisites

Before you start:

• Install @suki-sdk/form-filling and @suki-sdk/core (Form filling SDK v0.1.0-beta.3 or later for dynamic forms).
• 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 Medical form templates (ask Suki support for the template IDs), your own form schema, or both. See Dynamic Form filling.
• Have an encounter ID ready to pass as correlation_id.
• Run the app over HTTPS, with microphone access, and a container with height for the Form filling UI.

For webhooks and CSP, see Prerequisites.

Integration pattern

Create auth and the client once per page. Open Form filling only when the clinician taps your button.

Suki Auth Manager

One SukiAuthManager after the partner token is available.

Form Filling Client

One FormFillingClient. Reuse it for every start() call on that page.

Install the packages

pnpm

pnpm add @suki-sdk/form-filling @suki-sdk/core

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

Create one SukiAuthManager to sign in to Suki. Use the following example code:

JavaScript

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

const authManager = new SukiAuthManager({
  partnerId: "YOUR_PARTNER_ID", // Required
  partnerToken: "YOUR_PARTNER_TOKEN", // Required
  environment: "staging", // Optional
  loginOnInitialize: true, // Optional
  autoRegister: false, // optional (default true); when true, provider fields below are often required
  providerId: "YOUR_PROVIDER_ID", // Optional
  providerName: "Dr. Jane Smith", // Optional
});

Refer to Authentication for provider fields and other sign-in options.

Step 3: Create Form filling client

Create one FormFillingClient and pass the auth manager. Optionally wire onError for configuration and runtime errors.

JavaScript

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

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

Step 4: Start a session on user action

When the clinician taps your button, call await client.start({ ... }) from a click handler after the DOM is ready.

Pass these options to start():

• rootElement: Required The container from Step 1.
• forms or form_template_ids: Required At least one form after resolve. Prefer forms for Suki template IDs, your own schema, or both. form_template_ids is deprecated, but still works when forms is omitted.
• correlation_id: Optional Your encounter or appointment ID. Strongly recommended so results map to the correct record.
• onSubmit: Required Called when structured JSON is ready after processing, not when the clinician taps submit. Receives a FormFillingResult.
• onReady, onCancel: Optional.

JavaScript

document.getElementById("fill-forms-btn").addEventListener("click", async () => {
  const root = document.getElementById("suki-form-container");
  if (!root) return;

  await client.start({
    rootElement: root,
    forms: [ // New in v0.1.0-beta.3
      { 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" },
          ],
        },
      },
    ],
    correlation_id: "YOUR_ENCOUNTER_ID",
    onReady: () => console.log("Form UI ready"),
    onSubmit: (result) => {
      console.log("Session:", result.ambient_session_id);
      console.log("Correlation:", result.correlation_id);
      console.log("Forms:", result.structured_data.generated_values);
    },
    onCancel: () => console.log("Cancelled"),
  });
});

Callbacks and events

Your app needs to know when Form filling is ready, when structured results arrive, and when the clinician cancels. You can handle that in two ways.

Option 1: Pass callbacks on start()

Use this for logic tied to one session. Pass functions on the same object as rootElement and forms:

Callback	When it runs
onReady	The hosted UI loaded and is ready for the clinician
onSubmit	Structured JSON is ready after processing (map this to your EHR or show results in your app)
onCancel	The clinician left without submitting

Option 2: Listen with client.on()

Use this for handlers that stay active across many sessions, such as logging, analytics, or a shared error handler. Register once when you create the client:

JavaScript

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

Common events include form-filling:session-started, form-filling:background-submitted (results for a superseded session), and form-filling:error. Refer to Callbacks for FormFillingResult shape and Events for every event and payload.

Starting another session

When the clinician opens Form filling again, call start() a second time. The SDK closes the previous session and opens a new one. You do not need stop() first.

Complete code example

Below is a full page example: sign-in, client setup, and a button that opens Form filling.

JavaScript

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

const authManager = new SukiAuthManager({
  partnerId: "YOUR_PARTNER_ID", // Required
  partnerToken: "YOUR_PARTNER_TOKEN", // Required
  environment: "staging", // Optional
  loginOnInitialize: true, // Optional
  autoRegister: false, // optional (default true); when true, providerName and providerOrgId are often required
});

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

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

  await client.start({
    rootElement: root, // Required
    forms: [ // New in v0.1.0-beta.3
      { 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" },
          ],
        },
      },
    ], // Prefer forms; or pass form_template_ids when forms is omitted
    correlation_id: "YOUR_ENCOUNTER_ID", // Optional
    onReady: () => console.log("Form UI ready"), // Optional
    onSubmit: (result) => { // Required
      for (const form of result.structured_data.generated_values) {
        console.log(form.partner_form_id, form.form_template_id, form.data); // New in v0.1.0-beta.3
      }
    },
    onCancel: () => console.log("Cancelled"), // Optional
  });
}

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

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

Best practices

• Reuse one client and one auth manager for the page. Do not create a new FormFillingClient on every click.

• Pass onSubmit. It is required. Map structured_data.generated_values to your EHR or backend.

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

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

• Give the container height before start(). Zero height is the most common cause of a blank UI.

• Use template IDs from Suki support. The SDK validates IDs at start() and drops unsupported values.

Troubleshooting

Blank UI After start()

Set height on #suki-form-container before start(). Add CSP frame-src for https://sdk.suki.ai (production) or https://sdk.suki-stage.com (staging). Refer to Configuration and Prerequisites.

SUKI_FF_001 Immediately

No forms after resolve, invalid XOR entries, duplicate IDs, or no matching static IDs with no valid dynamic entries. Prefer forms. Refer to Error handling and Dynamic Form filling.

SUKI_FF_002 Handshake Timeout

The iframe did not complete the ready handshake within 10 seconds. Check network, ad blockers, and CSP. Confirm the page uses HTTPS.

SUKI_FF_003 Fetch Templates Failed

Auth failed or the wrong environment (staging vs production) while loading the template list. Retry and confirm partnerId, partnerToken, and environment.

SUKI_FF_004 Iframe Runtime Error

Microphone permission denied, session start/submit failed, or form generation failed. Read err.message, show a retry option, and confirm network access.

UI Never Opens

Sign-in failed before the hosted UI loads. Verify partnerId and partnerToken for your environment. Refer to Authentication.

No onSubmit Callback

The clinician closed the processing screen early, or the tab closed before processing finished. Register a partner webhook for server-side delivery.

onSubmit Never Maps to Your Encounter

Pass your encounter ID as correlation_id at session start so callbacks and webhooks match the correct record.

Log Errors During Development

Wire onError or client.on("form-filling:error", ...) so errors are visible in the console:

JavaScript

client.on("form-filling:error", (err) => {
  console.error(err.code, err.reason, err.message);
});

Refer to Error handling for the full error code table.

Next steps

Session workflow - Single-form vs multi-form behavior.

Configuration - All start() options.

React integration - If you use React.