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

> Overview of the Suki Form filling SDK and how it works

The Suki Form filling SDK is a JavaScript and React library that lets clinicians fill medical forms using their voice. Suki captures what they say in the hosted UI and, after processing, returns structured JSON that your app can use to update the EHR.

When the clinician starts a <Tooltip tip="A time-bound visit session for capturing conversation and generating structured medical form output." cta="View in Glossary" href="/Glossary/f">Form filling Session</Tooltip>:

* The SDK opens Suki's hosted UI in your web page
* The clinician selects forms (when you pass more than one template), speaks, and submits
* After processing, Suki returns structured JSON through **`onSubmit`** and your <Tooltip tip="A mechanism that allows Suki to send real-time event notifications to your application's server." cta="View in Glossary" href="/Glossary/w">partner webhook</Tooltip>

<Note>
  - The SDK handles sign-in, the hosted UI, and result callbacks for you.
  - If you need a custom UI or server-side audio capture without the hosted iframe, use the [Form filling API](/form-filling-api-reference/overview).
</Note>

## Supported packages

<CardGroup cols={2}>
  <Card title="React" icon="react" href="/form-filling-sdk/react-integration/react" cta="Learn more">
    Use **`@suki-sdk/form-filling-react`** for React web applications.

    Install the Form filling SDK for React:

    <div className="install-btns-v2">
      <button type="button" className="install-btn-v2" data-cmd="npm install @suki-sdk/form-filling-react @suki-sdk/core">
        <span className="install-btn-v2-label">Install for React</span>

        <span className="install-btn-v2-copy">
          <svg width="15" height="15" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2" strokeLinecap="round" strokeLinejoin="round">
            <rect x="9" y="9" width="13" height="13" rx="2" ry="2" />

            <path d="M5 15H4a2 2 0 0 1-2-2V4a2 2 0 0 1 2-2h9a2 2 0 0 1 2 2v1" />
          </svg>
        </span>

        <span className="install-btn-v2-check"><svg width="15" height="15" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2.5" strokeLinecap="round" strokeLinejoin="round"><polyline points="20 6 9 17 4 12" /></svg> Command Copied!</span>
      </button>
    </div>
  </Card>

  <Card title="Vanilla JavaScript" icon="js" href="/form-filling-sdk/javaScript-integration/javaScript" cta="Learn more">
    Use **`@suki-sdk/form-filling`** for vanilla JavaScript applications.

    Install the Form filling SDK for JavaScript:

    <div className="install-btns-v2">
      <button type="button" className="install-btn-v2" data-cmd="npm install @suki-sdk/form-filling @suki-sdk/core">
        <span className="install-btn-v2-label">Install for JavaScript</span>

        <span className="install-btn-v2-copy">
          <svg width="15" height="15" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2" strokeLinecap="round" strokeLinejoin="round">
            <rect x="9" y="9" width="13" height="13" rx="2" ry="2" />

            <path d="M5 15H4a2 2 0 0 1-2-2V4a2 2 0 0 1 2-2h9a2 2 0 0 1 2 2v1" />
          </svg>
        </span>

        <span className="install-btn-v2-check"><svg width="15" height="15" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2.5" strokeLinecap="round" strokeLinejoin="round"><polyline points="20 6 9 17 4 12" /></svg> Command Copied!</span>
      </button>
    </div>
  </Card>
</CardGroup>

## What you need to start a session

Work with Suki's [Support team](mailto:support@suki.ai) to get 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** enabled for your partner account. When the clinician opens Form filling, pass those **template IDs** and your **encounter ID** so structured results map to the correct record in your app and on your server.

## Single-form and Multi-form sessions

How Form filling behaves depends on how many Medical form templates you include when you start a session.

<CardGroup cols={2}>
  <Card title="Single Form" icon="file-lines" href="/form-filling-sdk/guides/integration-patterns#single-form-session" arrow={true}>
    Use one template. The clinician goes straight to recording. Suki shows the form name and a recording banner.
  </Card>

  <Card title="Multi-Form" icon="files" href="/form-filling-sdk/guides/integration-patterns#multi-form-session" arrow={true}>
    Use more than one template. The clinician picks which forms to fill on a selection screen first. All forms start selected, and at least one must stay selected.
  </Card>
</CardGroup>

<Tip>
  Refer to [Session workflow](/form-filling-sdk/guides/integration-patterns) for recording controls, cancel behavior, and how results are delivered.
</Tip>

## Common integration patterns and use cases

The Form filling SDK provides a hosted UI for selecting Medical form templates, recording by voice, and returning structured form results. Your application owns template IDs, encounter correlation, and how structured fields map into your EHR.

The following examples show common ways to integrate the Form filling SDK into your web application.

<CardGroup cols={2}>
  <Card title="Capture a Single Assessment by Voice" icon="stethoscope">
    Start Form filling with one template ID. After the clinician records and submits, map the structured fields from **`onSubmit`** into the patient record.
  </Card>

  <Card title="Capture Multiple Forms in One Session" icon="files">
    Pass multiple template IDs so the clinician can select forms in the hosted UI, then receive structured results for each submitted form.
  </Card>

  <Card title="Update Forms Mid-Session" icon="list-check">
    Change the selected templates during the assessment without ending the session so recording continues with the updated set.
  </Card>

  <Card title="Persist Results to Your EHR" icon="table">
    Handle **`onSubmit`** in the browser and configure a partner webhook so your backend still receives results if the tab closes during processing.
  </Card>

  <Card title="Capture Forms in Person" icon="user">
    Open the hosted Form filling UI from bedside workflows and map returned fields into your charting model without building the full Form filling API yourself.
  </Card>

  <Card title="Capture Forms on Telehealth Screens" icon="video">
    Open the same hosted Form filling UI on virtual visit screens and hand structured results back to your app the same way as in-person sessions.
  </Card>
</CardGroup>

## How the Form filling SDK works

```mermaid actions={false} theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
%%{init: {'theme':'base', 'themeVariables': { 'primaryColor':'#FFE148','primaryTextColor':'#111827','lineColor':'#6B7280','fontSize':'14px','edgeLabelBackground':'#FFFFFF','tertiaryColor':'#F9FAFB','tertiaryTextColor':'#111827','tertiaryBorderColor':'#D1D5DB'}}}%%
graph TB
    subgraph client["Your web application"]
        direction TB
        A["Application code<br/><small>React / JavaScript application</small>"]
        B["Form filling SDK<br/><small>@suki-sdk/form-filling or form-filling-react + core</small>"]
        C["Your layout + callbacks<br/><small>form_template_ids • correlation_id • onSubmit</small>"]
        A --> B
        B --> C
    end
    
    subgraph platform["Suki"]
        direction TB
        D["Authentication<br/><small>SukiAuthManager</small>"]
        E["Form filling iframe<br/><small>Selection, recording, processing UI</small>"]
    end
    
    B -->|Authenticate / tokens| D
    B -->|Hosted Form filling session| E
    E -->|Structured data to your app| C
    
    style client fill:#FFFADE,stroke:#D1D5DB,stroke-width:2px,color:#111827
    style platform fill:#FFF394,stroke:#FFE148,stroke-width:2px,color:#111827
    style A fill:#ffffff,stroke:#9CA3AF,stroke-width:2px,color:#111827
    style B fill:#FFE148,stroke:#111827,stroke-width:3px,color:#111827
    style C fill:#ffffff,stroke:#9CA3AF,stroke-width:2px,color:#111827
    style D fill:#ffffff,stroke:#9CA3AF,stroke-width:2px,color:#111827
    style E fill:#ffffff,stroke:#9CA3AF,stroke-width:2px,color:#111827
```

<Steps>
  <Step title="Your Web Application" icon="user">
    * You choose when Form filling opens and where it appears on the page.
    * Your code starts a session and listens for **`onSubmit`** and other callbacks.
    * Your app maps the structured JSON to your EHR or downstream systems.
  </Step>

  <Step title="Suki Services" icon="server">
    * **Sign-in:** **`SukiAuthManager`** authenticates with your partner credentials and supplies tokens to the hosted UI.
    * **Hosted Form filling:** Form selection, recording, and processing run in a <Tooltip tip="Suki-controlled UI loaded inside your web page for Form filling or Dictation." cta="View in Glossary" href="/Glossary/h">hosted iframe</Tooltip> at `https://sdk.suki.ai/form-filling` (production) or `https://sdk.suki-stage.com/form-filling` (staging).
  </Step>

  <Step title="Typical Session" icon="arrow-right">
    1. Create **`SukiAuthManager`** and <Tooltip tip="Main class in the Form filling SDK that opens Form filling sessions in your page." cta="View in Glossary" href="/Glossary/f">**`FormFillingClient`**</Tooltip> with partner credentials.
    2. Call **`client.start()`** or render **`<FormFilling>`** with **`form_template_ids`** and optional **`correlation_id`**.
    3. The clinician selects forms (multi-form only), speaks, and submits in the hosted UI.
    4. After processing, structured JSON arrives through **`onSubmit`** in the browser and through your [Partner webhook](/documentation/webhook/overview) on your server.
  </Step>
</Steps>

<Note>
  Refer to [Session workflow](/form-filling-sdk/guides/integration-patterns) for single-form, multi-form, offline, and webhook details.
</Note>

## Next steps

<Icon icon="file-lines" iconType="solid" /> Refer to [Installation](/form-filling-sdk/installation) to add packages to your project

<Icon icon="file-lines" iconType="solid" /> Refer to [Prerequisites](/form-filling-sdk/prerequisites) for browser, webhook, and template requirements

<Icon icon="file-lines" iconType="solid" /> Refer to the [Quickstart](/form-filling-sdk/quickstart) for JavaScript and React examples through your first session