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

> Learn what Suki Medical form templates are, the supported assessment types, and how Form filling APIs and the Form filling SDK use them in your integration

<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">
    Suki Medical form templates are predefined clinical assessment schemas. You list them with the Form filling Info API, bind form\_template\_id values in session context, stream visit audio, and retrieve structured JSON when processing completes.
  </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>

Suki Medical form templates are standardized clinical assessment forms used in **Form filling** workflows. They are common forms that are used in medical assessments and other structured clinical capture where conversation should map to specific fields instead of a full ambient clinical note.

Each template is a JSON schema that defines field names, field types, and valid options. When a clinician or other staff speaks during a visit,
the Form filling service uses that schema to parse the transcript and return structured assessment data you can review, edit, and save in your EHR or downstream systems.

## How templates work

Each template represents one clinical assessment category (for example vitals, neuro, or skin). When you list templates through the Form filling Info API, Suki returns a stable **`template_id`**, a **`type`** label, and the **`schema`** for that assessment.

Every template you receive from the API includes:

| Property          | What it tells you                                                                                             |
| ----------------- | ------------------------------------------------------------------------------------------------------------- |
| **`template_id`** | 36-character UUID string; pass as **`form_template_id`** in session context or in SDK **`form_template_ids`** |
| **`type`**        | Template type code from the API (for example `VITALS_ASSESSMENT`)                                             |
| **`name`**        | Human-readable template name                                                                                  |
| **`description`** | Short summary of the template purpose                                                                         |
| **`schema`**      | Field definitions, types, and allowed values for structured output                                            |

<Note>
  Templates are **Suki-defined**. Your integration selects which templates are in scope for a session. You **do not** upload custom schemas through the Form filling APIs. In the future, we may support custom templates.
</Note>

<Note>
  * If you use the **Form filling SDK**, Suki's support team provides the `template_id` UUIDs enabled for your account. Pass them in `form_template_ids` when you open a session. Refer to the [Form filling SDK](/form-filling-sdk/introduction).

  * If you use the **Form filling APIs**, call [Suki Medical form templates API](/form-filling-api-reference/info/suki-medical-form-templates) (`GET /api/v1/info/suki-medical-form-templates`) to list `template_id` values and each template `schema` for your account.
</Note>

## Supported Medical form templates

<span id="supported-templates" />

Suki supports the following Medical form templates for Form filling.

<CardGroup cols={3}>
  <Card title="Vitals" icon="heart-pulse">
    **`VITALS_ASSESSMENT`**: Standard vital signs: temperature, heart rate, blood pressure, SpO₂, oxygen delivery, respiratory rate, and pain score with location and comments.
  </Card>

  <Card title="Neuro" icon="brain">
    **`NEURO_ASSESSMENT`**: Neurological status: level of consciousness, orientation, speech, pupils, Glasgow Coma Scale, extremity strength, and sensation.
  </Card>

  <Card title="Skin" icon="hand">
    **`SKIN_ASSESSMENT`**: Skin integrity and wound care: color, temperature, moisture, pressure injuries, incision or surgical sites, dressings, and interventions.
  </Card>

  <Card title="Respiratory" icon="lungs">
    **`RESPIRATORY_ASSESSMENT`**: Respiratory system: breath sounds by lung lobe, work of breathing, cough and sputum, oxygen device and flow rate, SpO₂, and distress signs.
  </Card>

  <Card title="Cardiac" icon="heart">
    **`CARDIAC_ASSESSMENT`**: Cardiovascular status: heart rate and rhythm, auscultation, edema, perfusion, chest pain, peripheral pulses, and vascular access.
  </Card>

  <Card title="GI" icon="stomach">
    **`GASTRO_INTESTINAL_ASSESSMENT`**: Gastrointestinal status: abdomen exam, bowel sounds, diet tolerance, bowel movements, nausea or vomiting, ostomy or tubes, and GI symptoms.
  </Card>

  <Card title="GU" icon="kidneys">
    **`GENITO_URINARY_ASSESSMENT`**: Genitourinary findings: urine output, voiding, dysuria, catheter care, incontinence, bladder distention, and related symptoms.
  </Card>

  <Card title="MSK" icon="person-walking">
    **`MSK_ASSESSMENT`**: Musculoskeletal assessment: range of motion, strength, gait, mobility aids, and joint findings.
  </Card>

  <Card title="Intake and Output" icon="chart-line">
    **`IO_ASSESSMENT`**: Intake and output tracking: fluid intake (oral, IV, tube feeding) and output (urine, drainage, emesis) for fluid balance monitoring.
  </Card>
</CardGroup>

Use the [Suki Medical form templates API](/form-filling-api-reference/info/suki-medical-form-templates) to get each **`template_id`** and the full **`schema`**, including field names and allowed values.

## Common integration patterns and use cases

Use templates as contracts between the assessment types enabled for your account, the session context you send, and the structured fields your application expects back.

<CardGroup cols={2}>
  <Card title="Discover Available Templates" icon="list">
    Call [Suki Medical form templates](/form-filling-api-reference/info/suki-medical-form-templates) to discover **`template_id`** values and review each **`schema`** before you build your UI.
  </Card>

  <Card title="Bind Templates to a Session" icon="link">
    Seed or update session context with one or more **`form_template_id`** values so Suki knows which assessments are in scope for the visit.
  </Card>

  <Card title="Capture Conversation as Structure" icon="microphone">
    Stream visit audio on **`/ws/stream`**. Suki maps spoken assessment details into schema fields for the templates you selected.
  </Card>

  <Card title="Retrieve and Hand Off Output" icon="table">
    Poll [structured data](/form-filling-api-reference/form-filling-sessions/structured-data) and use **`generated_values`** in your review UI, validation rules, or EHR save path.
  </Card>
</CardGroup>

Typical clinical uses include:

* Nursing head-to-toe and focused system assessments
* Intake and reassessment workflows where structured fields matter more than narrative notes
* Telehealth or in-person visits where clinicians speak findings and your app stores structured results

## How Form filling products use templates

Templates connect to the Form filling session lifecycle the same way across products: you declare which templates apply, capture visit conversation, then read structured output when processing finishes. The steps differ by whether you use Form filling APIs or the Form filling SDK.

Click the tabs below to see the implementation details for your integration path.

<Tabs>
  <Tab title="Form Filling APIs">
    You do not send template schemas on every audio chunk. You declare which templates apply, stream audio once, then read structured output when processing finishes.

    ```mermaid actions={false} theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
    flowchart LR
        A[List templates] --> B[Create session]
        B --> C[Seed context with form_template_id]
        C --> D[Stream audio on /ws/stream]
        D --> E[End session]
        E --> F[Retrieve structured data]

        style A fill:#FFF394,stroke:#333,color:#000
        style B fill:#FFF394,stroke:#333,color:#000
        style C fill:#FFF394,stroke:#333,color:#000
        style D fill:#FFF394,stroke:#333,color:#000
        style E fill:#FFF394,stroke:#333,color:#000
        style F fill:#FFF394,stroke:#333,color:#000
    ```

    <Steps>
      <Step title="List Templates">
        Call <Badge color="green" size="sm">GET</Badge> [Suki Medical form templates](/form-filling-api-reference/info/suki-medical-form-templates). Save the **`template_id`** for each assessment you support in your product.
      </Step>

      <Step title="Create a Form Filling Session">
        Call <Badge color="blue" size="sm">POST</Badge> [Create Form filling session](/form-filling-api-reference/form-filling-sessions/create) and store the returned **`ambient_session_id`**.
      </Step>

      <Step title="Seed Session Context">
        Call <Badge color="blue" size="sm">POST</Badge> [Seed Form filling session context](/form-filling-api-reference/form-filling-sessions/context) with **`form_filling.values[].form_template_id`** set to the UUIDs from step 1. To change templates mid-visit, use [Update Form filling session context](/form-filling-api-reference/form-filling-sessions/update-context).
      </Step>

      <Step title="Stream Visit Audio">
        Connect to **`/ws/stream`** with your Form filling **`ambient_session_id`**. Refer to [Stream ambient audio over WebSocket](/documentation/how-to/audio-streaming/ambient-audio-streaming) and [WebSocket streaming wire format](/documentation/how-to/audio-streaming/websocket-streaming-wire-format) for **`EVENT`** messages and PCM format.
      </Step>

      <Step title="End the Session and Retrieve Output">
        Call [End Form filling session](/form-filling-api-reference/form-filling-sessions/end), poll [status](/form-filling-api-reference/form-filling-sessions/status), then call [structured data](/form-filling-api-reference/form-filling-sessions/structured-data). Review **`generated_values`** for populated templates and **`non_generated_values`** for templates without output.
      </Step>
    </Steps>

    Example context payload with two templates:

    ```json JSON theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
    {
      "form_filling": {
        "values": [
          { "form_template_id": "<vitals_template_uuid>" },
          { "form_template_id": "<neuro_template_uuid>" }
        ]
      }
    }
    ```

    For a full walkthrough with curl examples, refer to [Form filling basic usage](/documentation/how-to/form-filling/form-filling-basic-usage).
  </Tab>

  <Tab title="Form Filling SDK">
    You declare which templates apply when the session starts. The SDK opens Suki's hosted UI, the clinician records in that UI, and your application receives structured output through callbacks and optional webhooks. You do not stream audio or poll structured data yourself.

    ```mermaid actions={false} theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
    flowchart LR
        A[Get template IDs] --> B[Authenticate and create client]
        B --> C[Start session with form_template_ids]
        C --> D[Hosted UI: select, record, submit]
        D --> E[Receive structured data]

        style A fill:#FFF394,stroke:#333,color:#000
        style B fill:#FFF394,stroke:#333,color:#000
        style C fill:#FFF394,stroke:#333,color:#000
        style D fill:#FFF394,stroke:#333,color:#000
        style E fill:#FFF394,stroke:#333,color:#000
    ```

    <Steps>
      <Step title="Get Template IDs">
        Work with Suki's [Support team](mailto:support@suki.ai) to get the **`template_id`** UUIDs enabled for your partner account. Refer to [Supported Form filling Medical form templates](#supported-templates) for assessment types. Staging and production IDs can differ.
      </Step>

      <Step title="Authenticate and Create the Client">
        Create **`SukiAuthManager`** and **`FormFillingClient`** once per page with your partner credentials. Refer to [Form filling SDK authentication](/form-filling-sdk/guides/authentication).
      </Step>

      <Step title="Start a Session with Templates">
        Call **`client.start()`** or render **`<FormFilling>`** with **`form_template_ids`** set to the UUIDs from step 1. Pass your encounter ID as **`correlation_id`** so results map back to the right visit. The SDK validates IDs before the hosted UI opens.
      </Step>

      <Step title="Clinician Completes Form Filling in the Hosted UI">
        With one template ID, recording starts immediately. With two or more, the clinician confirms which forms to fill, then records and submits. Refer to [Session workflow](/form-filling-sdk/guides/integration-patterns) for single-form and multi-form behavior.
      </Step>

      <Step title="Receive Structured Output">
        Handle **`onSubmit`** for in-browser results. For production, also register a [partner webhook](/documentation/webhook/overview) so your server receives the same structured data if the tab closes during processing. Map each item in **`generated_values`** using **`form_template_id`** and **`type`**.
      </Step>
    </Steps>

    Example session options with two templates:

    ```jsx React theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
    <FormFilling
      form_template_ids={["<vitals_template_uuid>", "<neuro_template_uuid>"]}
      correlation_id={encounterId}
      onSubmit={(result) => {
        result.structured_data.generated_values.forEach((form) => {
          console.log(form.form_template_id, form.data);
        });
      }}
    />
    ```

    For a full walkthrough, refer to the [Form filling SDK Quickstart](/form-filling-sdk/quickstart).
  </Tab>
</Tabs>

## Next steps

<Icon icon="file-lines" iconType="solid" /> Refer to the [Form filling SDK](/form-filling-sdk/introduction) to embed Form filling in the browser with **`form_template_ids`** and Suki's hosted UI.

<Icon icon="file-lines" iconType="solid" /> Refer to the [Form filling basic usage](/documentation/how-to/form-filling/form-filling-basic-usage) guide to create a session, seed template context, stream audio, and retrieve structured data.

<Icon icon="file-lines" iconType="solid" /> Refer to [Suki Medical form templates](/form-filling-api-reference/info/suki-medical-form-templates) to list template IDs and schema definitions for your account.

<Icon icon="file-lines" iconType="solid" /> Refer to the [Form filling](/documentation/concepts/form-filling/form-filling) guide for capabilities, use cases, and how Form filling fits next to ambient clinical note workflows.