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

> Learn about Form filling capabilities, common use cases, and how to integrate with Form filling Partner APIs

<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">
    Form filling converts visit conversation into structured medical form output using Suki templates. Use Form filling Partner APIs for full control over session lifecycle, audio streaming, and structured data retrieval in your own UI and workflows.
  </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>
  **Form filling is supported by:** Form Filling APIs
</Info>

<Note>
  * For **standalone** Form filling with your own UI and server logic, use the [Form Filling APIs](/form-filling-api-reference/overview) and follow [Basic usage](/documentation/form-filling-basic-usage).
  * Stream visit audio on the shared Partner WebSocket **`GET /ws/stream`**. Use your **Form filling** **`ambient_session_id`**, not an Ambient clinical note session ID. Refer to [Ambient audio streaming](/documentation/ambient-audio-streaming).
</Note>

Form filling lets providers complete structured medical forms using natural conversation during a visit. You can use it for nursing workflows, intake and assessments, medication reviews, and other template-based capture without manual re-entry in your application.

The Form filling workflow focuses on structured output for Suki medical form templates. Unlike ambient documentation workflows, it does not generate a full clinical note or LOINC-based note sections. This makes it a good fit when you need template-driven forms that integrate directly into your own workflows and user experience.

You can use Form filling in both in-person and virtual care scenarios. Create a session, stream audio through the Partner WebSocket, and retrieve structured form data when processing completes. The APIs give you control over session lifecycle, context, audio capture, and downstream save logic.

## Common use cases

<CardGroup cols={2}>
  <Card title="Support in-person clinical form capture" icon="user">
    Capture visit conversation during in-person encounters and retrieve structured form output for nursing and clinical workflows.
  </Card>

  <Card title="Support telehealth form workflows" icon="video">
    Capture conversation during virtual visits and return structured form data for telehealth or remote care workflows.
  </Card>

  <Card title="Run template-driven sessions" icon="list">
    List templates, bind **`form_template_id`** values in session context, and retrieve **generated\_values** after processing.
  </Card>

  <Card title="Build custom Form Filling pipelines" icon="code">
    Own session lifecycle, audio streaming, structured data retrieval, and EHR handoff end to end with Partner APIs.
  </Card>
</CardGroup>

## Key features

<CardGroup cols={2}>
  <Card title="Voice-driven form capture" icon="microphone">
    Stream visit audio so Suki can populate structured form fields from conversation.
  </Card>

  <Card title="Session lifecycle" icon="waveform">
    Create sessions, seed or update context, end visits, and track status until completion.
  </Card>

  <Card title="Medical form templates" icon="list">
    Use Suki-defined templates with field definitions in each template **schema**.
  </Card>

  <Card title="Structured retrieval" icon="table">
    Retrieve **generated\_values** and **non\_generated\_values** when processing finishes.
  </Card>

  <Card title="Webhooks and polling" icon="bell">
    Poll session status and structured data, or use partner webhooks when configured for your account.
  </Card>
</CardGroup>

## How it works

If you use the **Form filling Partner APIs**, the workflow has these steps:

1. **Create a session** -
   Create a Form filling session and receive an **`ambient_session_id`**.

2. **Seed or update context** -
   Provide **`form_template_id`** values for the templates in scope for the visit.

3. **Stream audio** -
   Connect to **`/ws/stream`** and stream visit audio with that session ID.

4. **End the session** -
   End the session when visit capture is complete.

5. **Retrieve structured data** -
   Poll status and retrieve structured form output when processing finishes.

<Note>
  The Form filling **`ambient_session_id`** is not the same value as an [Ambient clinical note session](/api-reference/ambient-sessions/create). Use only the ID returned from [Create Form Filling session](/form-filling-api-reference/form-filling-sessions/create).
</Note>

### Workflow

```mermaid actions={false} theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
flowchart TD
    A[Create session] --> B[Get ambient_session_id]
    B --> C[Seed or update context]
    C --> D[Stream audio]
    D --> E[End session]
    E --> F[Poll status or webhook]
    F --> G[Get 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
    style G fill:#FFF394,stroke:#333,color:#000
```

## Next steps

<Icon icon="file-lines" iconType="solid" /> Refer to the [Basic usage](/documentation/form-filling-basic-usage) guide to get started with Form filling using our Partner APIs.