> ## Documentation Index
> Fetch the complete documentation index at: https://developer.suki.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Form Filling SDK Configuration

> Configure FormFillingClient, form template IDs, correlation_id, and session callbacks

<div className="quick-summary-wrapper">
  <div className="quick-summary-header">
    <span className="quick-summary-icon" aria-hidden="true" />

    <span className="quick-summary-title">Quick summary</span>
  </div>

  <div className="quick-summary-content">
    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>`.

    <br />

    <br />

    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.
  </div>

  <div className="quick-summary-footer">
    <span className="quick-summary-footer-icon" aria-hidden="true" />

    <span className="quick-summary-footer-text">Last updated:</span>
    <span className="quick-summary-footer-date">July 2026</span>
  </div>
</div>

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.

<Steps>
  <Step title="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](/form-filling-sdk/guides/authentication) for sign-in setup and required fields.
  </Step>

  <Step title="Define Session Options">
    Each time the clinician opens Form filling, pass session options to **`client.start()`** or render **`<FormFilling>`** with the same fields.

    <Badge color="red" size="sm">Required</Badge>

    * **`form_template_ids`**: **`template_id`** UUIDs from your Suki support team. Refer to [Form filling templates](/documentation/concepts/form-filling/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.

    <Badge color="green" size="sm">Optional</Badge>

    * **`correlation_id`**: Your encounter or appointment ID. Strongly recommended. See [Encounter ID (`correlation_id`)](#correlation_id-your-encounter-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.
  </Step>
</Steps>

<Tip>
  For callback behavior and event payloads, refer to [Callbacks](/form-filling-sdk/guides/callbacks) and [Events](/form-filling-sdk/api-reference/events).
</Tip>

## Encounter ID (correlation\_id)

<span id="correlation_id-your-encounter-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  |

<Note>
  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.
</Note>

<Warning>
  **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](/documentation/webhook/overview) 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](/form-filling-sdk/examples/webhook-handler) and [Get structured data](/form-filling-sdk/guides/integration-patterns#get-structured-data) guide for how to handle webhook payloads.
</Warning>

## FormFillingClient constructor

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

<Expandable title="FormFillingClient constructor" defaultOpen={true}>
  <ResponseField name="authManager" type="SukiAuthManager" required>
    Sign-in helper from **`@suki-sdk/core`**. Create once per page and reuse for every session.
  </ResponseField>

  <ResponseField name="onError" type="function">
    **Optional.** Called when the SDK reports a configuration or runtime error. Also available as **`form-filling:error`**.
  </ResponseField>
</Expandable>

## client.start(options)

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

<Expandable title="client.start(options)" defaultOpen={true}>
  <ResponseField name="rootElement" type="HTMLElement" required>
    Container for the Form filling UI. **JavaScript only.** Give this element explicit height before **`start()`**. React passes the container automatically through **`<FormFilling>`**.
  </ResponseField>

  <ResponseField name="form_template_ids" type="string[]" required>
    One or more **`template_id`** UUIDs (36 characters) from your Suki support team. Refer to [Form filling templates](/documentation/concepts/form-filling/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`**.
  </ResponseField>

  <ResponseField name="correlation_id" type="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.
  </ResponseField>

  <ResponseField name="onSubmit" type="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.
  </ResponseField>

  <ResponseField name="onReady" type="function">
    **Optional.** Called when the hosted UI is loaded and ready. Runs after **`start()`** resolves the iframe handshake.
  </ResponseField>

  <ResponseField name="onCancel" type="function">
    **Optional.** Called when the clinician cancels during form selection or recording.
  </ResponseField>
</Expandable>

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

<Expandable title="React: FormFilling props" defaultOpen={true}>
  <ResponseField name="form_template_ids" type="string[]" required>
    Same as **`start()`**. **`template_id`** UUIDs from Suki support.
  </ResponseField>

  <ResponseField name="correlation_id" type="string">
    Same as **`start()`**. Your encounter or appointment ID. Strongly recommended.
  </ResponseField>

  <ResponseField name="onSubmit" type="function" required>
    Same as **`start()`**. Required handler for structured results after processing completes.
  </ResponseField>

  <ResponseField name="onReady" type="function">
    Same as **`start()`**.
  </ResponseField>

  <ResponseField name="onCancel" type="function">
    Same as **`start()`**.
  </ResponseField>

  <ResponseField name="onBackgroundSubmit" type="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.
  </ResponseField>
</Expandable>

## Container sizing

<span id="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 CSS theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
.suki-form-filling {
  width: 100%;
  height: min(80vh, 720px);
  min-height: 400px;
}

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

## Next steps

<Icon icon="file-lines" iconType="solid" /> Refer to [Configuration examples](/form-filling-sdk/guides/examples/configuration-examples) for JavaScript and React samples

<Icon icon="file-lines" iconType="solid" /> Refer to the [Form filling client](/form-filling-sdk/api-reference/form-filling-client) reference for methods and React bindings