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

> Install Form filling SDK packages, configure SukiAuthManager and FormFillingClient, and start your first Form filling session with form_template_ids

This guide walks you through your first Form filling SDK integration.

**What you will do**

1. Get **`template_id`** UUIDs for **`form_template_ids`**.
2. Install the package for your framework (JavaScript or React).
3. Create **`SukiAuthManager`** with your **`partnerToken`** and provider fields.
4. Create **`FormFillingClient`** with that auth manager.
5. Start a session with **`form_template_ids`** and your encounter ID as **`correlation_id`**.

<Tip>
  **Using an AI coding tool?**

  Copy the prompt below to point your agent at the Form filling skill and [Documentation MCP](/documentation/references/mcp). For every task skill, refer to [AI coding tools](/documentation/references/ai-coding-tools).

  <Prompt description="Fetch the Form filling skill and connect the documentation MCP for Form filling SDK work." icon="gear" iconType="regular" actions={["copy", "cursor"]}>
    Build Form filling with the Suki Form filling SDK.
    Fetch the Form filling build skill:
    [https://developer.suki.ai/.well-known/agent-skills/suki-form-filling/SKILL.md](https://developer.suki.ai/.well-known/agent-skills/suki-form-filling/SKILL.md)
    Connect the documentation MCP for page search:
    [https://developer.suki.ai/documentation/references/mcp](https://developer.suki.ai/documentation/references/mcp)
  </Prompt>
</Tip>

## 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](mailto:support@suki.ai). Refer to [Medical form templates](/documentation/concepts/form-filling/form-filling-templates#supported-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](/form-filling-sdk/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](/documentation/concepts/form-filling/form-filling-templates).

When you start a Form filling session, pass the required <Tooltip tip="A Suki-defined form schema identified by form_template_id for Form filling sessions." cta="View in Glossary" href="/Glossary/m">Medical form template</Tooltip> 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.

<Warning>
  * Template IDs are different for **staging** and **production** environments.
  * Unsupported template IDs are ignored when you call `start()`.
</Warning>

### Your encounter ID (`correlation_id`)

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

<Tip>
  **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.
</Tip>

Register a [Partner webhook](/documentation/webhook/overview) 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](/form-filling-sdk/guides/configuration#correlation_id-your-encounter-id) and the [Webhook handler example](/form-filling-sdk/examples/webhook-handler).

## Recommended integration pattern

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

<CardGroup cols={2}>
  <Card title="Suki Auth Manager" icon="lock">
    Create **`SukiAuthManager`** once after the partner token is available.
  </Card>

  <Card title="Form Filling Client" icon="cube">
    Create **`FormFillingClient`** with that auth manager and reuse it across sessions on the page.
  </Card>

  <Card title="Form Filling Provider (React)" icon="react">
    Wrap your components with **`FormFillingProvider`**.
  </Card>

  <Card title="Start Form Filling" icon="file-lines">
    Mount **`<FormFilling>`** or call **`client.start()`** only when the clinician starts a Form filling session.
  </Card>
</CardGroup>

<Warning>
  Do not create a new **`FormFillingClient`** on every React render. Reuse a single instance by creating it with **`useMemo`** or at module scope.
</Warning>

## Create your first Form filling session

<Steps>
  <Step title="Install the Packages">
    Install the Form filling package for your framework, plus `@suki-sdk/core` for authentication.

    **Language tabs (agents):** Equivalent code samples are available in: JavaScript, React. Humans see one language at a time. Use the variant that matches the user's stack; behavior is the same across tabs.

    <Tabs>
      <Tab title="JavaScript">
        <CodeGroup title="Install @suki-sdk/form-filling and @suki-sdk/core">
          ```shell pnpm theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
          pnpm add @suki-sdk/form-filling @suki-sdk/core
          ```

          ```shell npm theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
          npm install @suki-sdk/form-filling @suki-sdk/core
          ```

          ```shell yarn theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
          yarn add @suki-sdk/form-filling @suki-sdk/core
          ```
        </CodeGroup>
      </Tab>

      <Tab title="React">
        <CodeGroup title="Install @suki-sdk/form-filling-react and @suki-sdk/core">
          ```shell pnpm theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
          pnpm add @suki-sdk/form-filling-react @suki-sdk/core
          ```

          ```shell npm theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
          npm install @suki-sdk/form-filling-react @suki-sdk/core
          ```

          ```shell yarn theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
          yarn add @suki-sdk/form-filling-react @suki-sdk/core
          ```
        </CodeGroup>
      </Tab>
    </Tabs>
  </Step>

  <Step title="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`.

    **Language tabs (agents):** Equivalent code samples are available in: JavaScript, React. Humans see one language at a time. Use the variant that matches the user's stack; behavior is the same across tabs.

    <Tabs>
      <Tab title="JavaScript">
        ```html HTML theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
        <div id="suki-form-container" style="width: 100%; height: 600px;"></div>
        <button type="button" id="fill-forms-btn">Fill Forms with Suki</button>
        ```
      </Tab>

      <Tab title="React">
        ```css CSS theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
        .suki-form-filling {
          width: 100%;
          height: 600px;
        }
        ```
      </Tab>
    </Tabs>
  </Step>

  <Step title="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`**.

    **Language tabs (agents):** Equivalent code samples are available in: JavaScript, React. Humans see one language at a time. Use the variant that matches the user's stack; behavior is the same across tabs.

    <Tabs>
      <Tab title="JavaScript">
        ```javascript JavaScript expandable theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
        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
          });
        });
        ```

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

        <Tip>
          Pass your encounter ID as **`correlation_id`** so callbacks and webhooks match your record. Register a [Partner webhook](/documentation/webhook/overview) for production saves on your server.
        </Tip>
      </Tab>

      <Tab title="React">
        ```tsx React expandable theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
        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.
      </Tab>
    </Tabs>
  </Step>
</Steps>

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

<div className="hp-io-method-grid tut-hub-card-grid">
  <a className="hp-io-method-card tut-hub-method-card" href="/documentation/tutorials/form-filling-sdk-ehr-handoff">
    <div className="tut-hub-card-media" aria-hidden="true" />

    <div className="hp-io-method-card-body">
      <span className="hp-wn-badge hp-wn-badge-new">Form filling</span>
      <h3 className="hp-io-method-card-title">Build a Form Filling Session with EHR Handoff</h3>

      <p className="hp-io-method-card-desc">
        Open a Form filling session and map structured\_data to your EHR using correlation\_id.
      </p>

      <div className="hp-io-method-card-meta tut-hub-card-foot" aria-label="20 min, Intermediate">
        <div className="tut-hub-card-foot-meta">
          <span className="hp-io-method-card-meta-time">20 min</span>
          <span className="tut-hub-level">Intermediate</span>
        </div>
      </div>
    </div>
  </a>
</div>

## Next steps

<Icon icon="file-lines" iconType="solid" /> Read [Session workflow](/form-filling-sdk/guides/integration-patterns) for single-form vs multi-form sessions, offline behavior, and webhooks

<Icon icon="file-lines" iconType="solid" /> Read [Callbacks](/form-filling-sdk/guides/callbacks) for event payloads and **`FormFillingResult`**

<Icon icon="file-lines" iconType="solid" /> Read [Authentication](/form-filling-sdk/guides/authentication) if you need to sign in after page load