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

> Get started with the Form filling SDK by installing packages, creating the auth manager and client, and opening a Form filling session

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 following prompt to add the Suki developer documentation as a skill and [MCP server](/documentation/references/mcp) to your tool. For all AI options, refer to [AI-optimized documentation](/documentation/references/ai-optimized-documentation).

  <Prompt description="Install the Suki developer docs as a skill and MCP server for Form filling SDK integration." icon="gear" iconType="regular" actions={["copy", "cursor"]}>
    Install the Suki developer docs as skill to get context on Suki's developer tools, APIs, and SDKs.

    npx skills add [https://developer.suki.ai](https://developer.suki.ai)

    Then add the Suki developer docs MCP server. Follow the MCP instructions at [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 many Medical form template types, such as **Vitals**, **Neuro**, and **Skin**. Each template type has a unique `type` value, for example `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 <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 you need in the `form_template_ids` parameter. This is an array of `template_id` values that identify the templates you want to use. Each `template_id` is a **unique 36-character UUID** assigned to your partner account.

<Warning>
  * Template IDs are different for **staging** and **production** environments.
  * When you call `start()`, the SDK validates the IDs. Any unsupported IDs are ignored.
</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 match the results to the correct patient record.

Provide `correlation_id` when you call `start()` or render `FormFilling`, along with your `form_template_ids`. The same ID is returned when structured results are available in the browser and when your server receives a webhook notification.

<Tip>
  **Strongly recommended for production.**

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

Register a [Partner webhook](/documentation/webhook/overview) and use your encounter ID with the Form filling session ID in your handler. 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. Open Form filling only when the clinician is ready.

<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. Reuse it across sessions on the page.
  </Card>

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

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

<Warning>
  Do not create a new **`FormFillingClient`** on every React render. Use **`useMemo`** or module scope.
</Warning>

## Install the packages

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

## Run your first session

For JavaScript, give Form filling a container with real height:

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

<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>
  </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>
      );
    }
    ```

    Style the container:

    ```css CSS theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
    .suki-form-filling {
      width: 100%;
      height: 600px;
    }
    ```

    Replace **`YOUR_TEMPLATE_ID`** with **`template_id`** UUIDs from your Suki support team.
  </Tab>
</Tabs>

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

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

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