> ## 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 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">June 2026</span>
  </div>
</div>

<Info>
  **This guide covers:** Suki-defined templates used for Form filling workflows.
</Info>

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`** | UUID you pass as **`form_template_id`** in session context         |
| **`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>

## Supported templates

Suki supports the following medical form templates for Form filling. Each one focuses on a specific clinical assessment area, such as vitals, neuro, or skin.

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

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

## Use cases

<CardGroup cols={2}>
  <Card title="List 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 APIs use templates

Templates connect to the standard Form filling session lifecycle. 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 [Ambient audio streaming](/documentation/ambient-audio-streaming) for handshake, PCM format, and **`EVENT`** messages.
  </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/form-filling-basic-usage).

## Next steps

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