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 prompt below to point your agent at the Form filling skill and Documentation MCP. For every task skill, refer to AI coding tools.

Fetch the Form filling skill and connect the documentation MCP for Form filling SDK work.

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 multiple Medical form templates, such as Vitals, Neuro, and Skin. Each template has a unique type, such as VITALS_ASSESSMENT or NEURO_ASSESSMENT. For a complete list, refer to Form filling templates. When you start a Form filling session, pass the required IDs in the form_template_ids parameter. form_template_ids is an array of template_id values. Each template_id is a unique 36-character UUID assigned to your partner account.

Template IDs are different for staging and production environments.
Unsupported template IDs are ignored when you call start().

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 associate results with the correct patient record. Pass correlation_id when you call start() or render <FormFilling>, together with form_template_ids. Suki returns the same correlation_id in SDK callbacks and partner webhooks when results are available.

Strongly recommended for production:If you do not provide correlation_id, the hosted UI creates its own ID for the session. That ID does not match your encounter ID, so you must map sessions to patient encounters yourself.

Register a Partner webhook and use correlation_id together with the Form filling session ID to associate webhook events with the correct encounter. For more information, refer to Configuration and the Webhook handler example.

Recommended integration pattern

Create SukiAuthManager and FormFillingClient once per page, then open Form filling only when the clinician starts a session.

Suki Auth Manager

Create SukiAuthManager once after the partner token is available.

Form Filling Client

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

Form Filling Provider (React)

Wrap your components with FormFillingProvider.

Start Form Filling

Mount <FormFilling> or call client.start() only when the clinician starts a Form filling session.

Do not create a new FormFillingClient on every React render. Reuse a single instance by creating it with useMemo or at module scope.

Create your first Form filling session

Install the Packages

Install the Form filling package for your framework, plus @suki-sdk/core for authentication.

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

Add the Page Container

Give Form filling a container with real height before the hosted UI opens. JavaScript uses a DOM node you pass as rootElement. React mounts into .suki-form-filling.

JavaScript
React

HTML

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

CSS

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

Run Your First Session

Create SukiAuthManager and FormFillingClient, then open Form filling when the clinician is ready. Pass form_template_ids and your encounter ID as correlation_id.

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.

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

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

Replace YOUR_TEMPLATE_ID with template_id UUIDs from your Suki support team.

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

Available tutorials

Form filling

Build a Form Filling Session with EHR Handoff

Open a Form filling session and map structured_data to your EHR using correlation_id.

20 minIntermediate

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)

Start Form Filling

Create your first Form filling session

Verify your integration

Available tutorials

Build a Form Filling Session with EHR Handoff

Next steps

​Prerequisites

​Medical form templates

​Your encounter ID (correlation_id)

​Recommended integration pattern

Suki Auth Manager

Form Filling Client

Form Filling Provider (React)

Start Form Filling

​Create your first Form filling session

​Verify your integration

​Available tutorials

​Build a Form Filling Session with EHR Handoff

​Next steps

Prerequisites

Medical form templates

Your encounter ID (`correlation_id`)

Recommended integration pattern

Create your first Form filling session

Verify your integration

Available tutorials

Build a Form Filling Session with EHR Handoff

Next steps