Form Filling Basic Usage

This guide covers: Form filling APIs.

Stream visit audio on the shared Partner WebSocket GET /ws/stream. Refer to Stream ambient audio over WebSocket and WebSocket streaming wire format for handshake, message order, EVENT controls, and PCM format.

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 and Form filling authentication.

From filling API workflow overview

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

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

Both Form filling and Ambient clinical note sessions 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 for Form filling REST calls and for /ws/stream.

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 POST Create Form filling session:

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:

{
  "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 POST Seed Form filling session context:

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 to list templates for your integration.
To update context later, use PATCH Update Form filling session context.

Stream visit audio

Form filling uses the Partner WebSocket GET /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, WebSocket streaming wire format, and the Audio streaming API reference. Close the WebSocket when audio capture is complete, then call end session.

End the Form filling session

When visit capture is complete:

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

Call POST End Form filling session:

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 GET Form filling session status:

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 GET Form filling structured data:

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:

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

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 to know which keys to expect.

When webhooks are enabled for your partner account, Suki can notify your application when processing completes. Refer to Webhook and Asynchronous notifications.

Common integration patterns and use cases

Pattern 1: Standard Form filling flow

A typical Form filling workflow follows these steps:

Create the Session

Call Create Form filling session and save ambient_session_id.

Seed Context

Call Seed Form filling session context with form_template_id values when needed.

Stream Audio

Connect to /ws/stream, stream audio per Ambient audio streaming, then close the WebSocket.

End the Session

Call End Form filling session API.

Retrieve Structured Data

Poll Status API, then call Structured data API.

Pattern 2: Update context during the visit

If the templates in scope change during the visit, call Update Form filling session context before you end the session.

Pattern 3: Submit feedback on a form instance

After clinicians review generated output, call Form filling session feedback. Include feedback_metadata.form_id for the medical form instance you are rating.

What you can build

In-Person and Virtual Form Filling Workflows

Complete template-based forms during room or telehealth visits with structured output in your UI.

Server-Side Capture Pipelines

Capture audio on a backend service, stream on /ws/stream, and store structured data for downstream systems.

Nursing and Clinical Assessments

Bind Suki templates in context and route generated_values into your chart or internal tools.

Webhook-Driven Completion

Trigger save or review flows when Suki notifies your backend that processing finished.

Create Form Filling Session

Create a Form filling session

Seed Session Context

Provide form template metadata

Form Filling Structured Data

Retrieve structured form output

Best practices

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.

FAQs

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

Where Do I Get form_template_id Values?

Call Suki Medical form templates. Use template_id from each template in form_filling.values when you seed or update context.

Get Started

Concepts & Feature Guides

Tutorials

Resources

FAQs & Support

Form Filling Basic Usage

From filling API workflow overview

Create a Form filling session

Request details

Seed session context

Request details

Stream visit audio

End the Form filling session

Retrieve structured form output

Poll session status

Get structured data

Example response

Common integration patterns and use cases

Pattern 1: Standard Form filling flow

Pattern 2: Update context during the visit

Pattern 3: Submit feedback on a form instance

What you can build

In-Person and Virtual Form Filling Workflows

Server-Side Capture Pipelines

Nursing and Clinical Assessments

Webhook-Driven Completion

Create Form Filling Session

Seed Session Context

Form Filling Structured Data

Best practices

FAQs

​From filling API workflow overview

​Create a Form filling session

​Request details

​Seed session context

​Request details

​Stream visit audio

​End the Form filling session

​Retrieve structured form output

​Poll session status

​Get structured data

​Example response

​Common integration patterns and use cases

​Pattern 1: Standard Form filling flow

​Pattern 2: Update context during the visit

​Pattern 3: Submit feedback on a form instance

​What you can build

In-Person and Virtual Form Filling Workflows

Server-Side Capture Pipelines

Nursing and Clinical Assessments

Webhook-Driven Completion

​Related API references

Create Form Filling Session

Seed Session Context

Form Filling Structured Data

​Best practices

​FAQs

From filling API workflow overview

Create a Form filling session

Request details

Seed session context

Request details

Stream visit audio

End the Form filling session

Retrieve structured form output

Poll session status

Get structured data

Example response

Common integration patterns and use cases

Pattern 1: Standard Form filling flow

Pattern 2: Update context during the visit

Pattern 3: Submit feedback on a form instance

What you can build

Related API references

Best practices

FAQs