FormFillingClient

is the main entry point for the Form filling SDK. It loads Suki’s hosted Form filling interface in a inside your application. Create the client once, provide your partner authentication, form_template_ids, and any callbacks, then use the same client to start Form filling sessions. The SDK manages the iframe connection, validates template IDs, and delivers session callbacks and events for you. In React, wrap your app with FormFillingProvider and render FormFilling when the clinician should see the interface. You do not pass a container element yourself; the component handles that.

Import

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

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

Create an instance

Create SukiAuthManager first, then pass it to FormFillingClient. Sign-in must succeed before the Form filling interface can open.

JavaScript

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

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

In React, create FormFillingClient inside useMemo or at module scope so you do not build a new client on every render.

Constructor options

These are the settings you pass to new FormFillingClient({ ... }) in JavaScript.

Hide Constructor fields

SukiAuthManager

required

Sign-in helper from @suki-sdk/core. Create once per page and reuse for every session. Refer to Authentication.

function

Optional. Called when the SDK reports a configuration or runtime error. The same error is also available on form-filling:error. Refer to Error handling.

Start options

Call await client.start({ ... }) when the clinician starts a Form filling session. The SDK validates your form_template_ids, loads the Form filling interface, authenticates the session, and prepares it for use. The start() method resolves when the session has been initialized. When the interface is fully loaded and ready for interaction, the onReady callback is called. start() does not throw errors. Instead, handle errors with the onError callback or the form-filling:error event. If you call start() again, the SDK automatically closes the current session and starts a new one. You do not need to call stop() first.

Always implement onSubmit. It runs when structured JSON is ready after processing completes, not when the clinician taps submit.

start() options

Hide start() fields

HTMLElement

required

Container for the Form filling iframe. JavaScript only. Give this element explicit height before start(). In React, FormFilling passes its own container automatically.

string[]

required

One or more template_id UUIDs from your Suki support team. The SDK validates each ID before the iframe opens. Unsupported IDs are dropped. If no valid IDs remain, the SDK returns SUKI_FF_001. Refer to Form filling templates.

string

Optional. Your encounter or appointment ID. Echoed on callbacks, events, and webhook payloads. Strongly recommended so results map to the correct patient record. If you omit it, the hosted UI generates a UUID when it creates the session.

function

required

Called when structured results are ready after processing. Receives a FormFillingResult. For a foreground session, the iframe is removed after this runs.

function

Optional. Called when the Form filling interface is loaded and interactive. Same moment as form-filling:ready.

function

Optional. Called when the clinician cancels during form selection or recording without submitting. Same moment as form-filling:cancelled.

Refer to Configuration for container sizing and correlation_id details.

Methods and getters

In JavaScript, you can use the following methods and getters to manage the Form filling session.

Hide Methods and getters

method

Ends the active session and removes the iframe. Keeps the client, auth state, and template cache so you can call start() again. React calls this when FormFilling unmounts.

method

Removes the iframe, tears down internal wiring, and clears the template cache. Does not destroy SukiAuthManager.

method

Subscribe to form-filling:* events. Returns an unsubscribe function. Refer to Events.

boolean

true after the Form filling interface reports that it is loaded and interactive.

boolean

true while the Form filling iframe is displayed in your container.

React bindings and components

In React, you can use the following components and provider to manage the Form filling session.

FormFillingProvider

Wrap components that render FormFilling or call useFormFilling(). Pass the same FormFillingClient instance you created in useMemo.

React

<FormFillingProvider client={client}>
  {/* children */}
</FormFillingProvider>

The provider listens for form-filling:error and exposes the latest error through useFormFilling().

FormFilling

Render FormFilling when the clinician should see the Form filling interface. Mounting starts a session; unmounting calls client.stop(). Props match start() options, except you do not pass rootElement.

Hide FormFilling props

string[]

required

Same as start(). Template IDs from Suki support.

string

Same as start(). Your encounter ID.

function

required

Same as start(). Required handler for structured results.

function

Same as start().

function

Same as start().

function

React only. Called for form-filling:background-submitted when results arrive for a session that is no longer the foreground session while the iframe is still open. Same payload shape as onSubmit.

useFormFilling()

Call inside FormFillingProvider to read the client, session state, or the latest error from sibling components.

Hide useFormFilling() return values

FormFillingClient

The same client instance you passed to FormFillingProvider.

boolean

true after form-filling:ready. Returns to false after submit, cancel, close, or error.

SukiFormFillingError | null

The latest SDK error from form-filling:error, if any. The provider does not clear this when a later session becomes ready, so prefer isSessionActive over returning early on error alone.

Code examples

The following example shows how to create a Form filling client, start a session, and handle the session events in JavaScript.

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",
  loginOnInitialize: true,
  autoRegister: false, // optional (default true); when true, providerName and providerOrgId are often required
});

const client = new FormFillingClient({ authManager });

document.getElementById("start-forms").addEventListener("click", async () => {
  await client.start({
    rootElement: document.getElementById("suki-form-container"),
    form_template_ids: ["YOUR_TEMPLATE_ID"],
    correlation_id: "c3d4e5f6-a7b8-9012-cdef-123456789012",
    onReady: () => console.log("Form filling ready"),
    onSubmit: (result) => {
      console.log(result.ambient_session_id, result.structured_data);
    },
    onCancel: () => console.log("Cancelled"),
  });
});

Refer to JavaScript integration for a full step-by-step guide.

Next steps

Refer to Events for client.on() payloads and lifecycle Refer to Callbacks for onSubmit and FormFillingResult Refer to Configuration for auth, container sizing, and correlation_id

Get Started

Integration Guides

Concepts & Feature Guides

API Reference

Resources

FormFillingClient

Import

Create an instance

Constructor options

Start options

start() options

Methods and getters

React bindings and components

FormFillingProvider

FormFilling

useFormFilling()

Code examples

Next steps

​Import

​Create an instance

​Constructor options

​Start options

​start() options

​Methods and getters

​React bindings and components

​FormFillingProvider

​FormFilling

​useFormFilling()

​Code examples

​Next steps

Import

Create an instance

Constructor options

Start options

start() options

Methods and getters

React bindings and components

FormFillingProvider

FormFilling

useFormFilling()

Code examples

Next steps