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

<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 [Ambient audio streaming](/documentation/ambient-audio-streaming) for handshake, PCM format, message order, and **`EVENT`** controls.
</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/partner-authentication) and [Form Filling authentication](/form-filling-api-reference/authentication).

## How the Form filling workflow works

The Form filling 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 [Ambient audio streaming](/documentation/ambient-audio-streaming) 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>'
```

Example response shape:

```json theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
{
  "generated_values": [],
  "non_generated_values": []
}
```

The response includes:

* **`generated_values`**: Form instances Suki generated for this session
* **`non_generated_values`**: Templates that did not receive generated output

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

### 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/ambient-audio-streaming), then close the WebSocket.
  </Step>

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

  <Step title="Retrieve structured data">
    Poll [status](/form-filling-api-reference/form-filling-sessions/status), then call [structured data](/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>