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 walks you through the steps to use the Form Filling APIs to authenticate, create a session, provide context, stream audio through the shared Partner WebSocket (GET /ws/stream), end the session, and retrieve structured form output. The WebSocket endpoint and message format are the same as Ambient audio streaming. Use the form-filling session ID when establishing the WebSocket connection. What you will do
  1. Authenticate to get a Suki token (and register the user if needed).
  2. Create a form-filling session and optionally seed context for template metadata.
  3. Stream audio over /ws/stream using your form-filling ambient_session_id, then end the session when the visit is done (details in the note after Step 3).
  4. Retrieve structured form output by polling status and structured-data, or rely on a webhook when processing finishes.
Using an AI coding tool?Copy the following prompt to add the Suki developer documentation as a skill and MCP server to your tool for better AI-assisted coding during the integration process.
Install the Suki developer docs as skill to get context on Suki’s developer tools, APIs, and SDKs.npx skills add https://developer.suki.aiThen add the Suki developer docs MCP server for access to documentation search. Follow the MCP instructions at https://developer.suki.ai/documentation/mcp.
Open in Cursor

​
Access and credentials

You need partner credentials to use the Suki Form Filling API. Contact our Partnership team to get your credentials. They will guide you through the Onboarding process and provide what you need to get started.

​
Prerequisites

To use the Suki Form Filling APIs, you must have the following:
  • An OAuth-compliant authentication system
  • JWT tokens with consistent user identifiers
  • A publicly accessible endpoint (or Okta authorization server) for token validation
Refer to the Partner onboarding and Partner authentication guides for more details.

​
Environments to use for development and testing

  • This guide uses https://sdp.suki-stage.com and wss://sdp.suki-stage.com for API and WebSocket examples (staging). Your partnership team will confirm which environment, base URL, and credentials apply for your integration.

​
Step 1: Authenticate and get token

To begin, you must authenticate to get your access token. Send a POST request to the /api/v1/auth/login endpoint with the following parameters in the request body:
  1. partner_id: Your unique , which we provide to you securely offline.
  2. partner_token: The user’s OAuth 2.0 ID token () from your identity provider.
  3. provider_id (Optional): Unique identifier for the . Required for Bearer type partners only.
Suki verifies the partner_token using your publicly exposed JWKS endpoint (or your Okta authorization server URL if you use Okta). On a successful request, the API returns a (suki_token) that you must include as the sdp_suki_token header for all subsequent API calls.
Handling an unregistered user:
  • If the user is not yet registered in our system, the /login request will fail.
  • In this case, you must first call the /api/v1/auth/register endpoint to create the user, then call /login again.
  • You only need to call the register endpoint once for each new user.
  • Refer to the Register API reference for the full specification.
curl -X POST https://sdp.suki-stage.com/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "partner_id": "your-partner-id",
    "partner_token": "your-jwt-token",
    "provider_id": "provider-123"
  }'
Save the suki_token from the response. This token is valid for 1 hour. When it is about to expire, you can get a new one by making the same POST request to /login with a valid partner_token.

​
Step 2: Create form-filling session

To start a form-filling session, send a POST request to the /api/v1/form-filling/session/create endpoint with the following parameters in the request body:
In the API reference, both the Form Filling session ID and the Suki Ambient API session ID are named ambient_session_id. Those identifiers refer to different sessions. Use only the ambient_session_id returned from form-filling /session/create for form-filling REST calls and for /ws/stream.
  1. ambient_session_id (Optional): Associate this form-filling session with an existing Ambient API session when applicable.
  2. correlation_id (Optional): Client-supplied identifier for tracing or correlating requests.
The request body itself is optional (you can send an empty JSON object). The response always includes the ambient_session_id for this form-filling session. Use that value for context, streaming, end, status, and structured-data calls. 
curl -X POST https://sdp.suki-stage.com/api/v1/form-filling/session/create \
  -H "sdp_suki_token: YOUR_SUKI_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}'
Save the ambient_session_id from the response. You need it for context, /ws/stream, end, status, and structured-data calls.

​
Step 3: Seed context

After creating the session, you can send a POST request to the /api/v1/form-filling/session//context endpoint to provide form template metadata.
The request body is optional. If you omit it, skip this step and continue to audio capture (see the note after this step). If you include form_filling, you must send valid values: an array of objects, each with a required form_template_id (UUID for the template). Providing context improves the quality of structured form output for the templates you select.
Include the following in the request body when you supply context:
  • form_filling (Optional): An object with values, an array of form_template_id entries that identify which medical form templates apply to this session.
Refer to the Context API reference for the full request structure. To list templates your integration can offer, use Suki medical form templates.
Audio capture: The Form Filling APIs do not add a separate streaming endpoint. Use the Partner Ambient GET /ws/stream WebSocket on the same host as REST (for example wss://sdp.suki-stage.com/ws/stream in staging). Authenticate with your form-filling ambient_session_id and sdp_suki_token. Follow Audio streaming API reference and Ambient audio streaming for handshake, PCM format, message order, EVENT controls, timeouts, and the sequence close WebSocket → end session (REST) → poll status and structured-data. Treat REST as the source of truth for final structured output.

​
Step 4: End session

To complete the session and begin processing, send a POST request to the /api/v1/form-filling/session//end endpoint. This signals that no more audio will be sent for this session. 
curl -X POST "https://sdp.suki-stage.com/api/v1/form-filling/session/YOUR_SESSION_ID/end" \
  -H "sdp_suki_token: YOUR_SUKI_TOKEN"

​
Step 5: Poll status and retrieve structured data

When structured output is ready, Suki can notify your application. The recommended way to know when processing has finished is to use a webhook on the same partner callback you use for Ambient. Suki sends events such as session_summary_generated to the endpoint configured during onboarding. Payloads include _links you can follow to retrieve results. For verification, payload shapes, and examples, see Asynchronous notifications (webhook) and Notification webhook for partners. Retrieving structured output manually: Alternatively, poll the Form Filling REST endpoints:
  1. GET /api/v1/form-filling/session//status: Check the processing status of a session.
  2. GET /api/v1/form-filling/session//structured-data: Retrieve generated_values and non_generated_values for the session.
# Check status
curl -X GET "https://sdp.suki-stage.com/api/v1/form-filling/session/YOUR_SESSION_ID/status" \
  -H "sdp_suki_token: YOUR_SUKI_TOKEN"

# Get structured data
curl -X GET "https://sdp.suki-stage.com/api/v1/form-filling/session/YOUR_SESSION_ID/structured-data" \
  -H "sdp_suki_token: YOUR_SUKI_TOKEN"
For complete technical specifications, please refer to the relevant API Reference pages.

​
Next steps

After completing your first session, explore these resources to deepen your integration: Form Filling API Overview - Overview of the Form Filling APIs. Form Filling API Reference - Reference documentation for the Form Filling APIs. Audio streaming API - WebSocket connection details and message formats for streaming audio for form-filling sessions. Webhook - Configure webhooks to receive notifications when processing completes.
Last modified on May 22, 2026