Form Filling SDK Configuration

Configure FormFillingClient with forms, correlation_id, and session callbacks

Configuring the session in the Form filling SDK lets you manage how the session is opened and how the results are processed. Configuration varies depending on whether you use JavaScript or React.

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 in your app.

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

2. Define Session Options

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

   Required

   • forms or form_template_ids: At least one form after resolve. Prefer forms. form_template_ids is deprecated, but still works when forms is omitted. Refer to Dynamic and static medical forms below.
   • 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.

Dynamic and static medical forms

When you open Form filling with client.start() or FormFilling, pass the medical forms the clinician will fill in that Form filling run. Prefer the forms array. Each entry is MedicalFormMetadata: exactly one of form_template_id (a Suki Medical form template) or schema (a partner-defined form). You can mix both in one forms array.

You can also pass Suki template IDs with form_template_ids when you omit forms. That option is deprecated and will be removed in a future major release. For new integrations, pass forms: [{ form_template_id }]. If you pass forms, the SDK uses that list only and ignores form_template_ids.

Mode	Entry shape
Static	{ form_template_id: "YOUR_TEMPLATE_ID" }
Dynamic	{ schema: { ... }, id?, name?, type? }
Mixed	Static and dynamic entries in the same forms array

Rules for each forms entry:

• Include exactly one of form_template_id or schema. Do not send both, and do not send neither.
• schema must be a non-empty plain object. An empty object ({}) is invalid and yields SUKI_FF_001 with invalid-form-entry.
• Keep every form_template_id unique among static entries, and every dynamic id unique among dynamic entries.
• If you omit dynamic id, the SDK generates a UUID so you can still correlate results.
• One form starts recording immediately. More than one form shows the hosted selection UI (catalogue titles for static forms, name or a generated title for dynamic forms).

If you pass forms (including an empty array), that list is the only form Context for the Form filling run. JavaScript start({ forms: [] }) and React FormFilling with forms={[]} both work this way, so form_template_ids is ignored whenever forms is present.

Pass forms when you open Form filling. Use a Suki template, a partner schema, or both in the same array:

JavaScript

await client.start({
  rootElement,
  forms: [ // New in v0.1.0-beta.3
    { form_template_id: "YOUR_TEMPLATE_ID" },
    {
      id: "partner-ros-1",
      name: "Review of systems",
      schema: {
        items: [
          { id: "symptoms", type: "text", question: "Review of systems findings?" },
        ],
      },
    },
  ],
  onSubmit,
});

form_template_ids is an older way to pass only Suki template IDs as strings, for example ["YOUR_TEMPLATE_ID"]. The SDK maps each string to { form_template_id }. It cannot carry partner schema entries. This option is deprecated. Prefer forms. If you also pass forms, the SDK ignores form_template_ids.

For partner schema shapes and XOR examples, refer to Dynamic Form filling.

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 forms 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

authManager · SukiAuthManager · required

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

onError · 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)

rootElement · HTMLElement · required

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

forms · MedicalFormMetadata[]

Preferred list of medical forms for this Form filling run. Each entry is either { form_template_id } or a dynamic entry with required schema and optional id, name, and type. When forms is provided, it is the sole source of Context. Supply at least one valid entry across forms and form_template_ids. Refer to Dynamic and static medical forms and Dynamic Form filling.

form_template_ids · string[]

DEPRECATED List of Suki template IDs as strings. Still works when you omit forms. Prefer forms: [{ form_template_id }]. We will remove this option in a future major release. The SDK maps each ID to { form_template_id }. Unsupported IDs are dropped. If no valid forms remain, the SDK emits SUKI_FF_001.

correlation_id · 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.

onSubmit · function · required

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

onReady · function

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

onCancel · 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

forms · MedicalFormMetadata[]

Same as start(). Preferred static, dynamic, or mixed form list.

form_template_ids · string[]

DEPRECATED Same as start(). Still works when you omit forms. Prefer forms. We will remove this option in a future major release.

correlation_id · string

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

onSubmit · function · required

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

onReady · function

Same as start().

onCancel · function

Same as start().

onBackgroundSubmit · 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

Dynamic Form filling - Partner schemas and mixed sessions.

Configuration examples - JavaScript and React samples.

Form filling client - Reference for methods and React bindings.