Form Filling SDK Configuration

Quick summary

You configure Form filling in two parts. Set up sign-in with SukiAuthManager and create FormFillingClient once per page. Each time the clinician opens Form filling, pass session options such as form_template_ids, correlation_id, and onSubmit when you call start() or render <FormFilling>.

Give the container a fixed height before the hosted UI opens. Pass valid template IDs you get from Suki’s support team, and use correlation_id so results map to the correct encounter in your app and on your server.

Last updated:July 2026

You configure Form filling in two parts:

Set up sign-in once per page
Pass session options each time the clinician opens Form filling in your app

In JavaScript, pass session options to client.start(). In React, pass the same fields as props on <FormFilling>. Sign-in must succeed before the hosted UI opens.

Authenticate with Suki for Partners

Create SukiAuthManager from @suki-sdk/core with your partnerId, partnerToken, and environment (staging or production). Optionally pass provider fields such as providerId and providerName. Set autoRegister: false unless you use provider auto-registration (autoRegister defaults to true).Pass that manager to new FormFillingClient({ authManager }). Create both once per page and reuse them for every session.Refer to Authentication for sign-in setup and required fields.

Define Session Options

Each time the clinician opens Form filling, pass session options to client.start() or render <FormFilling> with the same fields.Required

form_template_ids: template_id UUIDs from your Suki support team. Refer to Form filling templates for supported types.
onSubmit: Handler that receives structured JSON after processing completes, not when the clinician taps submit.
rootElement: Container for the hosted UI. JavaScript only. React supplies the container automatically.

Optional

correlation_id: Your encounter or appointment ID. Strongly recommended. See Encounter ID (correlation_id) below.
onReady: Runs when the hosted UI loaded and is ready for the clinician.
onCancel: Runs when the clinician cancels without submitting.
onBackgroundSubmit (React): Runs for form-filling:background-submitted when results arrive for a superseded session while the iframe is still open.

For callback behavior and event payloads, refer to Callbacks and Events.

Encounter ID (correlation_id)

In the SDK, your encounter or appointment identifier is correlation_id. Pass it when you start a session so structured results map to the correct patient record in your app and on your server.

Use	How `correlation_id` helps
Start a session	Pass it with `form_template_ids` on `client.start()` or `<FormFilling>`
Callbacks	Echoed on `onSubmit` and session events so you map `structured_data` to the right record
Webhooks	Included in partner notification payloads so your server saves results to the correct encounter

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.

Use a webhook in production, not only onSubmit.onSubmit runs in the browser when structured results are ready. If the clinician closes the tab or navigates away before processing finishes, your app does not receive that callback.Register a Partner webhook on your server so Suki delivers results even when the browser is gone. Match each payload to the correct encounter using correlation_id (your ID from session start). Use ambient_session_id when you need to tie the payload to a specific Form filling session.Refer to the Webhook handler example and Get structured data guide for how to handle webhook payloads.

FormFillingClient constructor

These are the settings you pass when you create the client once per page in JavaScript.

Hide FormFillingClient constructor

SukiAuthManager

required

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

function

Optional. Called when the SDK reports a configuration or runtime error. Also available as form-filling:error.

client.start(options)

These are the settings you pass each time you open Form filling in JavaScript.

Hide client.start(options)

HTMLElement

required

Container for the Form filling UI. JavaScript only. Give this element explicit height before start(). React passes the container automatically through <FormFilling>.

string[]

required

One or more template_id UUIDs (36 characters) from your Suki support team. Refer to Form filling templates for supported template types. The SDK validates each ID before the iframe opens. Unsupported IDs are dropped. If no valid IDs remain, the SDK emits SUKI_FF_001.

string

Optional. Your encounter or appointment ID from your system. Echoed on callbacks and webhook payloads. Strongly recommended so structured data maps to the correct record. When omitted, the hosted UI supplies a UUID when it creates the session.

function

required

Called when structured results are ready (after processing), not when the clinician taps submit. Receives a FormFillingResult with structured_data. The iframe is removed after this runs for a foreground session.

function

Optional. Called when the hosted UI is loaded and ready. Runs after start() resolves the iframe handshake.

function

Optional. Called when the clinician cancels during form selection or recording.

React: FormFilling props

In React, pass the same session options as client.start() as props on <FormFilling>. You do not pass rootElement. The component renders the hosted UI in .suki-form-filling for you.

Hide React: FormFilling props

string[]

required

Same as start(). template_id UUIDs from Suki support.

string

Same as start(). Your encounter or appointment ID. Strongly recommended.

function

required

Same as start(). Required handler for structured results after processing completes.

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

Container sizing

The hosted Form filling UI fills its container. Without explicit height, the iframe looks blank. In JavaScript, set height on #suki-form-container (or your rootElement) before start(). In React, set height on .suki-form-filling.

CSS

.suki-form-filling {
  width: 100%;
  height: min(80vh, 720px);
  min-height: 400px;
}

#suki-form-container {
  width: 100%;
  height: 600px;
}

Next steps

Refer to Configuration examples for JavaScript and React samples Refer to the Form filling client reference for methods and React bindings

Get Started

Integration Guides

Concepts & Feature Guides

API Reference

Resources

Form Filling SDK Configuration

Encounter ID (correlation_id)

FormFillingClient constructor

client.start(options)

React: FormFilling props

Container sizing

Next steps

​Encounter ID (correlation_id)

​FormFillingClient constructor

​client.start(options)

​React: FormFilling props

​Container sizing

​Next steps

Encounter ID (correlation_id)

FormFillingClient constructor

client.start(options)

React: FormFilling props

Container sizing

Next steps