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

> Learn how to create a Form filling session, seed context, stream audio, end the session, and retrieve structured form data using Form filling APIs

<Info>
  **This guide covers:** [Form filling APIs](/form-filling-api-reference/overview).

  * Stream visit audio on the shared Partner WebSocket **`GET /ws/stream`**. 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 handshake, message order, **`EVENT`** controls, and PCM format.
</Info>

This guide walks you through how to build a standalone Form filling workflow with the Form filling APIs. In this workflow, you:

* Create a Form filling session
* Seed session context with template metadata
* Stream visit audio over WebSocket
* End the session when capture is complete
* Retrieve structured form output when processing finishes

Before you start, register the provider and get an **`sdp_suki_token`**. Refer to [Partner authentication](/documentation/how-to/partner-authentication) and [Form filling authentication](/form-filling-api-reference/authentication).

## From filling API workflow overview

The Form filling API workflow uses Form filling REST APIs and the shared partner WebSocket.

1. Create a session with the REST API.
2. Seed context with **`form_template_id`** values when needed.
3. Stream audio to the session over **`/ws/stream`**.
4. End the session with the REST API.
5. Poll status and retrieve structured data.

<Note>
  Both Form filling and [Ambient clinical note sessions](/api-reference/ambient-sessions/create) use the parameter name **`ambient_session_id`** in the API reference. Those identifiers refer to **different** sessions. Use only the ID returned from Form filling [Create Form filling session](/form-filling-api-reference/form-filling-sessions/create) for Form filling REST calls and for **`/ws/stream`**.
</Note>

## Create a Form filling session

Create a Form filling session before you seed context or open the WebSocket. The response includes an **`ambient_session_id`** that you use for the rest of the workflow.

Call <Badge color="blue" size="sm">POST</Badge> [Create Form filling session](/form-filling-api-reference/form-filling-sessions/create):

```bash theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
curl --request POST \
  --url https://sdp.suki-stage.com/api/v1/form-filling/session/create \
  --header 'Content-Type: application/json' \
  --header 'sdp_suki_token: <sdp_suki_token>' \
  --header 'sdp_provider_id: <sdp_provider_id>' \
  --data '{}'
```

Example response:

```json theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
{
  "ambient_session_id": "123dfg-456dfg-789dfg-012dfg"
}
```

The API returns **`201 Created`** when the session is created successfully.

### Request details

* Include **`sdp_suki_token`** in every REST request and during the WebSocket handshake.
* The request body is optional. You may send **`correlation_id`** when your integration needs it.
* Save **`ambient_session_id`** for context, **`/ws/stream`**, end session, status, and structured-data calls.

## Seed session context

After you create the session, you can provide form template metadata for the visit. Context helps Suki generate structured output for the templates you select.

Call <Badge color="blue" size="sm">POST</Badge> [Seed Form filling session context](/form-filling-api-reference/form-filling-sessions/context):

```bash theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
curl --request POST \
  --url https://sdp.suki-stage.com/api/v1/form-filling/session/<ambient_session_id>/context \
  --header 'Content-Type: application/json' \
  --header 'sdp_suki_token: <sdp_suki_token>' \
  --header 'sdp_provider_id: <sdp_provider_id>' \
  --data '{
    "form_filling": {
      "values": [
        {
          "form_template_id": "019d4cdc-9319-7d81-ae2e-fd6de7f1b4f0"
        }
      ]
    }
  }'
```

### Request details

* The body is optional. If you omit it, you can continue to audio capture without seeding context.
* If you include **`form_filling`**, provide valid **`values`** with a required **`form_template_id`** (UUID) for each template.
* Refer to [Suki Medical form templates](/form-filling-api-reference/info/suki-medical-form-templates) to list templates for your integration.
* To update context later, use <Badge color="blue" size="sm">PATCH</Badge> [Update Form filling session context](/form-filling-api-reference/form-filling-sessions/update-context).

## Stream visit audio

Form filling uses the Partner WebSocket <Badge color="green" size="sm">GET</Badge> **`/ws/stream`**, not a separate Form filling streaming path.

Authenticate during the WebSocket handshake with:

* **`sdp_suki_token`**
* Your Form filling **`ambient_session_id`**

For browser versus non-browser handshake headers, PCM format, chunking, and **`EVENT`** messages, refer to [Stream ambient audio over WebSocket](/documentation/how-to/audio-streaming/ambient-audio-streaming), [WebSocket streaming wire format](/documentation/how-to/audio-streaming/websocket-streaming-wire-format), and the [Audio streaming API reference](/api-reference/ambient-sessions/audio-stream).

Close the WebSocket when audio capture is complete, then call end session.

## End the Form filling session

When visit capture is complete:

1. Close the WebSocket connection used for audio.
2. End the session with the REST API.

Call <Badge color="blue" size="sm">POST</Badge> [End Form filling session](/form-filling-api-reference/form-filling-sessions/end):

```bash theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
curl --request POST \
  --url https://sdp.suki-stage.com/api/v1/form-filling/session/<ambient_session_id>/end \
  --header 'sdp_suki_token: <sdp_suki_token>' \
  --header 'sdp_provider_id: <sdp_provider_id>'
```

## Retrieve structured form output

After you end the session, poll until processing reaches a terminal status, then retrieve structured data.

### Poll session status

Call <Badge color="green" size="sm">GET</Badge> [Form filling session status](/form-filling-api-reference/form-filling-sessions/status):

```bash theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
curl --request GET \
  --url https://sdp.suki-stage.com/api/v1/form-filling/session/<ambient_session_id>/status \
  --header 'sdp_suki_token: <sdp_suki_token>' \
  --header 'sdp_provider_id: <sdp_provider_id>'
```

Poll until the status is terminal (for example **`completed`** or **`failed`**). Refer to the status API reference for all status values.

### Get structured data

Call <Badge color="green" size="sm">GET</Badge> [Form filling structured data](/form-filling-api-reference/form-filling-sessions/structured-data):

```bash theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
curl --request GET \
  --url https://sdp.suki-stage.com/api/v1/form-filling/session/<ambient_session_id>/structured-data \
  --header 'sdp_suki_token: <sdp_suki_token>' \
  --header 'sdp_provider_id: <sdp_provider_id>'
```

After you bind templates, stream audio, and end the session, call this endpoint when processing is done. Filled forms appear in **`generated_values`**. Templates with no output appear in **`non_generated_values`**.

### Example response

The Form filling structured data API returns the following response for a completed Form filling session with filled templates:

```json theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
{
  "structured_data": {
    "generated_values": [
      {
        "id": "019d4cdc-9319-7d81-ae2e-fd6de7f1b4f0",
        "form_template_id": "019d4cdc-9319-7d81-ae2e-fd6de7f1b4f0-template",
        "title": "Adult Vitals",
        "type": "VITALS_ASSESSMENT",
        "status": "MEDICAL_FORM_STATUS_COMPLETED",
        "patient_id": "patient-123",
        "correlation_id": "20965414-929a-4f71-a3e5-b92bec07d086",
        "created_at": "2026-01-01T00:00:00Z",
        "data": {},
        "metadata": {}
      }
    ],
    "non_generated_values": [
      {
        "form_template_id": "019d4cdc-9319-7d81-ae2e-fd6de7f1b4f0"
      }
    ]
  }
}
```

The response contains the following top-level fields under **`structured_data`**:

| Field                      | Description                                                                                                                                                       |
| -------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **`generated_values`**     | Array of completed form instances for this session. Filled forms use **`status`**: **`MEDICAL_FORM_STATUS_COMPLETED`** and include a populated **`data`** object. |
| **`non_generated_values`** | Array of templates that did not receive generated output. Entries are often sparse and may include only **`form_template_id`**.                                   |

Each item in **`generated_values`** has the following fields:

| Field                  | Description                                                        |
| ---------------------- | ------------------------------------------------------------------ |
| **`id`**               | Unique ID for this medical form instance                           |
| **`form_template_id`** | Template ID you bound on the session                               |
| **`title`**            | Display title for the form (often the template name)               |
| **`type`**             | Template type code (for example **`VITALS_ASSESSMENT`**)           |
| **`status`**           | Lifecycle status (for example **`MEDICAL_FORM_STATUS_COMPLETED`**) |
| **`patient_id`**       | Patient identifier for the form instance, when present             |
| **`correlation_id`**   | Your encounter or correlation key, when you supplied one           |
| **`created_at`**       | When the form instance was created                                 |
| **`data`**             | Free-form object of filled field values for that template          |
| **`metadata`**         | Free-form object for optional extras                               |

<Note>
  **`data`** is where the filled field values live. Different templates use different field names (for example vitals vs skin).
  Check the template schema using the [Suki Medical form templates API](/form-filling-api-reference/info/suki-medical-form-templates) to know which keys to expect.
</Note>

When webhooks are enabled for your partner account, Suki can notify your application when processing completes. Refer to [Webhook](/documentation/webhook/overview) and [Asynchronous notifications](/api-reference/asynchronous/webhook).

## Common integration patterns and use cases

### Pattern 1: Standard Form filling flow

A typical Form filling workflow follows these steps:

<Steps>
  <Step title="Create the Session">
    Call [Create Form filling session](/form-filling-api-reference/form-filling-sessions/create) and save **`ambient_session_id`**.
  </Step>

  <Step title="Seed Context">
    Call [Seed Form filling session context](/form-filling-api-reference/form-filling-sessions/context) with **`form_template_id`** values when needed.
  </Step>

  <Step title="Stream Audio">
    Connect to **`/ws/stream`**, stream audio per [Ambient audio streaming](/documentation/how-to/audio-streaming/ambient-audio-streaming), then close the WebSocket.
  </Step>

  <Step title="End the Session">
    Call [End Form filling session API](/form-filling-api-reference/form-filling-sessions/end).
  </Step>

  <Step title="Retrieve Structured Data">
    Poll [Status API](/form-filling-api-reference/form-filling-sessions/status), then call [Structured data API](/form-filling-api-reference/form-filling-sessions/structured-data).
  </Step>
</Steps>

### Pattern 2: Update context during the visit

If the templates in scope change during the visit, call [Update Form filling session context](/form-filling-api-reference/form-filling-sessions/update-context) before you end the session.

### Pattern 3: Submit feedback on a form instance

After clinicians review generated output, call [Form filling session feedback](/form-filling-api-reference/form-filling-sessions/feedback). Include **`feedback_metadata.form_id`** for the medical form instance you are rating.

## What you can build

<CardGroup cols={2}>
  <Card title="In-Person and Virtual Form Filling Workflows" icon="user">
    Complete template-based forms during room or telehealth visits with structured output in your UI.
  </Card>

  <Card title="Server-Side Capture Pipelines" icon="server">
    Capture audio on a backend service, stream on **`/ws/stream`**, and store structured data for downstream systems.
  </Card>

  <Card title="Nursing and Clinical Assessments" icon="file-lines">
    Bind Suki templates in context and route **generated\_values** into your chart or internal tools.
  </Card>

  <Card title="Webhook-Driven Completion" icon="bell">
    Trigger save or review flows when Suki notifies your backend that processing finished.
  </Card>
</CardGroup>

## Related API references

<CardGroup cols={3}>
  <Card title="Create Form Filling Session" icon="code" href="/form-filling-api-reference/form-filling-sessions/create" arrow={true}>
    Create a Form filling session
  </Card>

  <Card title="Seed Session Context" icon="file-lines" href="/form-filling-api-reference/form-filling-sessions/context" arrow={true}>
    Provide form template metadata
  </Card>

  <Card title="Form Filling Structured Data" icon="table" href="/form-filling-api-reference/form-filling-sessions/structured-data" arrow={true}>
    Retrieve structured form output
  </Card>
</CardGroup>

## Best practices

<Tip>
  * **Close the WebSocket before end session** so processing can start reliably.
  * **Use the Form filling session ID** for **`/ws/stream`**, not an ambient clinical note session ID.
  * **Poll status** until terminal, or configure webhooks for completion events.
  * **Handle non\_generated\_values** in your UI so clinicians know which templates need follow-up.
  * **Store tokens securely** and refresh **`sdp_suki_token`** before expiry.
</Tip>

## FAQs

<Accordion title="What's the Difference Between Form Filling and Ambient Clinical Documentation?">
  | Feature                        | Description                                                                                                        |
  | :----------------------------- | :----------------------------------------------------------------------------------------------------------------- |
  | Form filling                   | Converts visit conversation into structured medical form output for Suki templates you bind in session context     |
  | Ambient clinical documentation | Converts speech to text and generates structured clinical notes, LOINC-based sections, and related ambient outputs |
</Accordion>

<Accordion title="Where Do I Get form_template_id Values?">
  Call [Suki Medical form templates](/form-filling-api-reference/info/suki-medical-form-templates). Use **`template_id`** from each template in **`form_filling.values`** when you seed or update context.
</Accordion>