Form Filling SDK Quickstart

This guide walks you through your first Form filling SDK integration. What you will do

Get template_id UUIDs for form_template_ids
Install the package for your framework (JavaScript or React)
Create SukiAuthManager with your partnerToken and provider fields
Create FormFillingClient with that auth manager
Start a session with form_template_ids and your encounter ID as correlation_id

Using an AI coding tool?Copy the following prompt to add the Suki developer documentation as a skill and MCP server to your tool. For all AI options, refer to AI-optimized documentation.

Install the Suki developer docs as a skill and MCP server for Form filling SDK integration.

Open in Cursor

Prerequisites

Before you start, ensure you have the following:

Partner credentials from Suki (partnerId and partnerToken)
Medical form template IDs from Suki’s Support team. Refer to Medical form templates for supported assessment types.
A browser on HTTPS with microphone access and a page container that has explicit height for the Form filling UI

Refer to Prerequisites for webhooks and CSP requirements.

Medical form templates

The Form filling SDK supports many Medical form template types, such as Vitals, Neuro, and Skin. Each template type has a unique type value, for example VITALS_ASSESSMENT or NEURO_ASSESSMENT. For a complete list, refer to Form filling templates. When you start a Form filling session, pass the IDs you need in the form_template_ids parameter. This is an array of template_id values that identify the templates you want to use. Each template_id is a unique 36-character UUID assigned to your partner account.

Template IDs are different for staging and production environments.
When you call start(), the SDK validates the IDs. Any unsupported IDs are ignored.

Your encounter ID (correlation_id)

When you start a Form filling session, pass your encounter or appointment ID in the correlation_id parameter. Suki includes this ID in SDK callbacks and partner webhooks so you can match the results to the correct patient record. Provide correlation_id when you call start() or render FormFilling, along with your form_template_ids. The same ID is returned when structured results are available in the browser and when your server receives a webhook notification.

Strongly recommended for production.If you omit correlation_id, the hosted UI creates its own ID for the session. That ID will not match your encounter unless you map sessions another way.

Register a Partner webhook and use your encounter ID with the Form filling session ID in your handler. Refer to Configuration and the Webhook handler example.

Recommended integration pattern

Create SukiAuthManager and FormFillingClient once per page. Open Form filling only when the clinician is ready.

Suki Auth Manager

Create SukiAuthManager once after the partner token is available.

Form Filling Client

Create FormFillingClient with that auth manager. Reuse it across sessions on the page.

Form Filling Provider (React)

Wrap components with FormFillingProvider.

Form Filling UI

Mount <FormFilling> or call client.start() when the clinician opens Form filling.

Do not create a new FormFillingClient on every React render. Use useMemo or module scope.

Install the packages

JavaScript
React

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

npm install @suki-sdk/form-filling @suki-sdk/core

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

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

npm install @suki-sdk/form-filling-react @suki-sdk/core

yarn add @suki-sdk/form-filling-react @suki-sdk/core

Run your first session

For JavaScript, give Form filling a container with real height:

HTML

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

JavaScript
React

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, provider fields below are often required
  providerId: "provider-123", // Optional
  providerName: "Dr. Jane Smith", // Optional
});

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

document.getElementById("fill-forms-btn").addEventListener("click", async () => {
  await client.start({
    rootElement: document.getElementById("suki-form-container"), // Required
    form_template_ids: ["YOUR_TEMPLATE_ID"], // Required
    correlation_id: "YOUR_ENCOUNTER_ID", // Optional
    onReady: () => console.log("Form UI ready"), // Optional
    onSubmit: (result) => { // Required
      console.log("Session:", result.ambient_session_id);
      console.log("Filled:", result.structured_data.generated_values);
    },
    onCancel: () => console.log("Cancelled"), // Optional
  });
});

Your integration works when the Form filling UI appears, the microphone is active, and onSubmit returns structured_data.Replace YOUR_TEMPLATE_ID with template_id UUIDs from your Suki support team.

React

import { useMemo, useState } from "react";
import { SukiAuthManager } from "@suki-sdk/core";
import {
  FormFillingClient,
  FormFillingProvider,
  FormFilling,
} from "@suki-sdk/form-filling-react";

export function EncounterPage({ encounterId }: { encounterId: string }) {
  const client = useMemo(() => {
    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
      providerId: "provider-123", // Optional
    });
    return new FormFillingClient({ authManager }); // authManager required
  }, []);

  const [isFormOpen, setIsFormOpen] = useState(false);

  return (
    <FormFillingProvider client={client}>
      <button type="button" onClick={() => setIsFormOpen(true)} disabled={isFormOpen}>
        Fill Forms with Suki
      </button>

      {isFormOpen && (
        <FormFilling
          form_template_ids={["YOUR_TEMPLATE_ID"]} // Required
          correlation_id={encounterId} // Optional
          onReady={() => console.log("Ready")} // Optional
          onSubmit={(result) => { // Required
            console.log(result.structured_data.generated_values);
            setIsFormOpen(false);
          }}
          onCancel={() => setIsFormOpen(false)} // Optional
        />
      )}
    </FormFillingProvider>
  );
}

Style the container:

CSS

.suki-form-filling {
  width: 100%;
  height: 600px;
}

Replace YOUR_TEMPLATE_ID with template_id UUIDs from your Suki support team.

Pass your encounter ID as correlation_id so callbacks and webhooks match your record. Register a partner webhook for production saves on your server.

Verify your integration

After you complete your first Form filling session, verify that:

The hosted Form filling UI loads in your page container.
The microphone is active during recording. You should see a microphone icon in the UI.
onSubmit returns structured_data.generated_values for the templates you passed in form_template_ids.
correlation_id matches your encounter in SDK callbacks and partner webhooks (when provided).

Next steps

Read Session workflow for single-form vs multi-form sessions, offline behavior, and webhooks Read Callbacks for event payloads and FormFillingResult Read Authentication if you need to sign in after page load

Get Started

Integration Guides

Concepts & Feature Guides

API Reference

Resources

Form Filling SDK Quickstart

Prerequisites

Medical form templates

Your encounter ID (correlation_id)

Recommended integration pattern

Suki Auth Manager

Form Filling Client

Form Filling Provider (React)

Form Filling UI

Install the packages

Run your first session

Verify your integration

Next steps

​Prerequisites

​Medical form templates

​Your encounter ID (correlation_id)

​Recommended integration pattern

Suki Auth Manager

Form Filling Client

Form Filling Provider (React)

Form Filling UI

​Install the packages

​Run your first session

​Verify your integration

​Next steps

Prerequisites

Medical form templates

Your encounter ID (correlation_id)

Recommended integration pattern

Install the packages

Run your first session

Verify your integration

Next steps