Skip to main content

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.

This guide covers: Form Filling Partner APIs.
  • Stream visit audio on the shared Partner WebSocket GET /ws/stream. Refer to Ambient audio streaming for handshake, PCM format, message order, and EVENT controls.
This guide walks you through how to build a standalone form-filling workflow with the Form Filling Partner 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.

​
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.
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>' \
  --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>' \
  --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 Ambient audio streaming 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:
  1. Close the WebSocket connection used for audio.
  2. 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>'

​
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>'
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>'
Example response shape: 
{
  "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 and Asynchronous notifications.

​
Common integration patterns

​
Pattern 1: Standard form-filling flow

A typical form-filling workflow follows these steps:
1

Create the session

Call Create form filling session and save ambient_session_id.
2

Seed context

Call Seed form filling session context with form_template_id values when needed.
3

Stream audio

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

End the session

Call End form filling session.
5

Retrieve structured data

Poll status, then call structured data.

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

FeatureDescription
Form fillingConverts visit conversation into structured medical form output for Suki templates you bind in session context
Ambient clinical documentationConverts speech to text and generates structured clinical notes, LOINC-based sections, and related ambient outputs
Call Suki medical form templates. Use template_id from each template in form_filling.values when you seed or update context.
Last modified on May 22, 2026