Form Filling API Quickstart

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

Authenticate to get an sdp_suki_token (and register the user if needed).
Create a Form filling session and optionally seed context for template metadata.
Stream audio over /ws/stream using your Form filling ambient_session_id, then end the session when the visit is done.
Retrieve structured form output by polling status and structured-data, or rely on a webhook when processing finishes.

Prefer one paste-ready file? Use the Complete staging script in the preferred language below, then follow the numbered steps for the same flow with full explanations.

Using an AI coding tool?Copy the prompt below to point your agent at the Form filling skill and Documentation MCP. For every task skill, refer to AI coding tools.

Fetch the Form filling skill and connect the 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.

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).

Important:

The production environment is https://sdp.suki.ai and wss://sdp.suki.ai.
The staging environment is https://sdp.suki-stage.com and wss://sdp.suki-stage.com.
Your partnership team will confirm which environment, base URL, and credentials apply for your integration.

Complete staging script

Replace credential placeholders. For optional context, set FORM_TEMPLATE_ID to a real template UUID from Suki Medical form templates. Put a 16 kHz mono LINEAR16 WAV (or raw PCM) at audio.wav. The numbered steps after this section explain each call in detail.

Python: pip install requests websocket-client then python form_filling_staging.py.
TypeScript (Node): npm install ws then npx tsx form_filling_staging.ts (Node 18+).

# form_filling_staging.py
# Flow: login → create → optional context → stream → end → poll structured-data
# pip install requests websocket-client

import base64
import json
import time
from datetime import datetime, timezone
from typing import Any, Optional

import requests
import websocket

BASE_URL = "https://sdp.suki-stage.com"
WS_URL = "wss://sdp.suki-stage.com/ws/stream"
CHUNK_BYTES = 3200
WAV_HEADER_BYTES = 44

PARTNER_ID = "your-partner-id"
PARTNER_TOKEN = "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..."
PROVIDER_ID = "provider-123"  # Optional; required for Bearer / Single Auth Token partners
SDP_PROVIDER_ID = ""  # Leave empty unless your partnership requires sdp_provider_id
# Example template ID from Form filling context docs — replace with one your tenant can use
FORM_TEMPLATE_ID = "019d4cdc-9319-7d81-ae2e-fd6de7f1b4f0"
SEED_CONTEXT = True
AUDIO_PATH = "audio.wav"


def b64(data: bytes) -> str:
    return base64.b64encode(data).decode("ascii")


def rest_headers(suki_token: str) -> dict[str, str]:
    headers = {
        "sdp_suki_token": suki_token,
        "Content-Type": "application/json",
    }
    if SDP_PROVIDER_ID:
        headers["sdp_provider_id"] = SDP_PROVIDER_ID
    return headers


def expect_status(response: requests.Response, url: str, want: int) -> None:
    if response.status_code == want:
        return
    detail = (response.text or "")[:500]
    try:
        body = response.json()
        if isinstance(body, dict) and body.get("message"):
            detail = str(body["message"])
    except ValueError:
        pass
    raise RuntimeError(f"HTTP {response.status_code} {url}: {detail}")


def login(partner_id: str, partner_token: str, provider_id: Optional[str] = None) -> str:
    url = f"{BASE_URL}/api/v1/auth/login"
    payload: dict[str, Any] = {"partner_id": partner_id, "partner_token": partner_token}
    if provider_id:
        payload["provider_id"] = provider_id
    r = requests.post(url, json=payload, timeout=60)
    expect_status(r, url, 200)
    token = r.json().get("suki_token")
    if not token:
        raise RuntimeError("login response missing suki_token")
    return token


def register_provider(
    partner_id: str,
    partner_token: str,
    provider_name: str,
    provider_org_id: str,
    provider_id: Optional[str] = None,
) -> None:
    url = f"{BASE_URL}/api/v1/auth/register"
    payload: dict[str, Any] = {
        "partner_id": partner_id,
        "partner_token": partner_token,
        "provider_name": provider_name,
        "provider_org_id": provider_org_id,
    }
    if provider_id:
        payload["provider_id"] = provider_id
    r = requests.post(url, json=payload, timeout=60)
    # New link: 201. Already linked: 409. Both are success for this flow.
    if r.status_code not in (201, 409):
        expect_status(r, url, 201)


def login_with_register_fallback(
    partner_id: str,
    partner_token: str,
    provider_id: Optional[str],
    provider_name: str,
    provider_org_id: str,
) -> str:
    try:
        return login(partner_id, partner_token, provider_id)
    except RuntimeError as err:
        if "provider_not_registered" not in str(err):
            raise
        register_provider(
            partner_id, partner_token, provider_name, provider_org_id, provider_id
        )
        return login(partner_id, partner_token, provider_id)


def create_form_filling_session(suki_token: str) -> str:
    url = f"{BASE_URL}/api/v1/form-filling/session/create"
    r = requests.post(url, headers=rest_headers(suki_token), json={}, timeout=60)
    expect_status(r, url, 201)
    sid = r.json().get("ambient_session_id")
    if not sid:
        raise RuntimeError("create response missing ambient_session_id")
    return sid


def seed_context(suki_token: str, ambient_session_id: str, form_template_id: str) -> None:
    url = f"{BASE_URL}/api/v1/form-filling/session/{ambient_session_id}/context"
    payload = {
        "form_filling": {
            "values": [{"form_template_id": form_template_id}],
        },
    }
    r = requests.post(url, headers=rest_headers(suki_token), json=payload, timeout=60)
    expect_status(r, url, 200)


def strip_wav_header(raw: bytes) -> bytes:
    if len(raw) >= 12 and raw[:4] == b"RIFF" and raw[8:12] == b"WAVE":
        return raw[WAV_HEADER_BYTES:]
    return raw


def stream_pcm_file(suki_token: str, ambient_session_id: str, path: str) -> None:
    header = [
        f"sdp_suki_token: {suki_token}",
        f"ambient_session_id: {ambient_session_id}",
    ]
    if SDP_PROVIDER_ID:
        header.append(f"sdp_provider_id: {SDP_PROVIDER_ID}")

    ws = websocket.create_connection(WS_URL, header=header, timeout=60)
    try:
        rfc3339 = datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
        ws.send(json.dumps({"type": "START_TIME", "data": b64(rfc3339.encode("utf-8"))}))

        with open(path, "rb") as f:
            pcm = strip_wav_header(f.read())

        for i in range(0, len(pcm), CHUNK_BYTES):
            ws.send(json.dumps({"type": "AUDIO", "data": b64(pcm[i : i + CHUNK_BYTES])}))

        ws.send(json.dumps({"type": "AUDIO", "data": "RU9G"}))
    finally:
        ws.close()


def end_session(suki_token: str, ambient_session_id: str) -> None:
    url = f"{BASE_URL}/api/v1/form-filling/session/{ambient_session_id}/end"
    r = requests.post(url, headers=rest_headers(suki_token), timeout=60)
    expect_status(r, url, 200)


def get_status(suki_token: str, ambient_session_id: str) -> str:
    url = f"{BASE_URL}/api/v1/form-filling/session/{ambient_session_id}/status"
    r = requests.get(url, headers=rest_headers(suki_token), timeout=60)
    expect_status(r, url, 200)
    return r.json()["status"]


def get_structured_data(suki_token: str, ambient_session_id: str) -> Any:
    url = f"{BASE_URL}/api/v1/form-filling/session/{ambient_session_id}/structured-data"
    r = requests.get(url, headers=rest_headers(suki_token), timeout=60)
    expect_status(r, url, 200)
    return r.json()


def wait_for_structured_data(
    suki_token: str, ambient_session_id: str, poll_sec: float = 2.0
) -> dict[str, Any]:
    while True:
        status = get_status(suki_token, ambient_session_id)
        print("status:", status)
        if status == "completed":
            return {
                "status": status,
                "structured_data": get_structured_data(suki_token, ambient_session_id),
            }
        if status in ("failed", "aborted"):
            return {"status": status, "structured_data": None}
        time.sleep(poll_sec)


if __name__ == "__main__":
    suki_token = login_with_register_fallback(
        PARTNER_ID,
        PARTNER_TOKEN,
        PROVIDER_ID,
        provider_name="Dr. John Smith",
        provider_org_id="org-123",
    )
    print("Authenticated")

    ambient_session_id = create_form_filling_session(suki_token)
    print("ambient_session_id:", ambient_session_id)

    if SEED_CONTEXT:
        seed_context(suki_token, ambient_session_id, FORM_TEMPLATE_ID)
        print("Context seeded")

    stream_pcm_file(suki_token, ambient_session_id, AUDIO_PATH)
    print("Stream finished")

    end_session(suki_token, ambient_session_id)
    print("Session ended")

    result = wait_for_structured_data(suki_token, ambient_session_id)
    print(json.dumps(result, indent=2))

// form_filling_staging.ts
// Flow: login → create → optional context → stream → end → poll structured-data
// Node 18+: npm install ws && npx tsx form_filling_staging.ts

import fs from "node:fs";
import WebSocket from "ws";

const BASE_URL = "https://sdp.suki-stage.com";
const WS_URL = "wss://sdp.suki-stage.com/ws/stream";
const CHUNK_BYTES = 3200;
const WAV_HEADER_BYTES = 44;

const PARTNER_ID = "your-partner-id";
const PARTNER_TOKEN = "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...";
const PROVIDER_ID = "provider-123";
const SDP_PROVIDER_ID = "";
const FORM_TEMPLATE_ID = "019d4cdc-9319-7d81-ae2e-fd6de7f1b4f0";
const SEED_CONTEXT = true;
const AUDIO_PATH = "audio.wav";

function restHeaders(sukiToken: string): Record<string, string> {
  const headers: Record<string, string> = {
    sdp_suki_token: sukiToken,
    "Content-Type": "application/json",
  };
  if (SDP_PROVIDER_ID) headers.sdp_provider_id = SDP_PROVIDER_ID;
  return headers;
}

async function expectStatus(response: Response, url: string, want: number): Promise<void> {
  if (response.status === want) return;
  const raw = await response.text();
  let detail = raw.slice(0, 500);
  try {
    const body = JSON.parse(raw);
    if (body?.message) detail = String(body.message);
  } catch {
    // keep raw
  }
  throw new Error(`HTTP ${response.status} ${url}: ${detail}`);
}

async function login(
  partnerId: string,
  partnerToken: string,
  providerId?: string,
): Promise<string> {
  const url = `${BASE_URL}/api/v1/auth/login`;
  const body: Record<string, string> = {
    partner_id: partnerId,
    partner_token: partnerToken,
  };
  if (providerId) body.provider_id = providerId;
  const response = await fetch(url, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify(body),
  });
  await expectStatus(response, url, 200);
  const data = (await response.json()) as { suki_token?: string };
  if (!data.suki_token) throw new Error("login response missing suki_token");
  return data.suki_token;
}

async function registerProvider(input: {
  partnerId: string;
  partnerToken: string;
  providerName: string;
  providerOrgId: string;
  providerId?: string;
}): Promise<void> {
  const url = `${BASE_URL}/api/v1/auth/register`;
  const body: Record<string, string> = {
    partner_id: input.partnerId,
    partner_token: input.partnerToken,
    provider_name: input.providerName,
    provider_org_id: input.providerOrgId,
  };
  if (input.providerId) body.provider_id = input.providerId;
  const response = await fetch(url, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify(body),
  });
  // New link: 201. Already linked: 409. Both are success for this flow.
  if (response.status !== 201 && response.status !== 409) {
    await expectStatus(response, url, 201);
  }
}

async function loginWithRegisterFallback(
  partnerId: string,
  partnerToken: string,
  providerId: string | undefined,
  providerName: string,
  providerOrgId: string,
): Promise<string> {
  try {
    return await login(partnerId, partnerToken, providerId);
  } catch (err) {
    if (!String(err).includes("provider_not_registered")) throw err;
    await registerProvider({
      partnerId,
      partnerToken,
      providerName,
      providerOrgId,
      providerId,
    });
    return login(partnerId, partnerToken, providerId);
  }
}

async function createFormFillingSession(sukiToken: string): Promise<string> {
  const url = `${BASE_URL}/api/v1/form-filling/session/create`;
  const response = await fetch(url, {
    method: "POST",
    headers: restHeaders(sukiToken),
    body: JSON.stringify({}),
  });
  await expectStatus(response, url, 201);
  const data = (await response.json()) as { ambient_session_id?: string };
  if (!data.ambient_session_id) {
    throw new Error("create response missing ambient_session_id");
  }
  return data.ambient_session_id;
}

async function seedContext(
  sukiToken: string,
  ambientSessionId: string,
  formTemplateId: string,
): Promise<void> {
  const url = `${BASE_URL}/api/v1/form-filling/session/${ambientSessionId}/context`;
  const response = await fetch(url, {
    method: "POST",
    headers: restHeaders(sukiToken),
    body: JSON.stringify({
      form_filling: {
        values: [{ form_template_id: formTemplateId }],
      },
    }),
  });
  await expectStatus(response, url, 200);
}

function stripWavHeader(buf: Buffer): Buffer {
  if (
    buf.length >= 12 &&
    buf.subarray(0, 4).toString("ascii") === "RIFF" &&
    buf.subarray(8, 12).toString("ascii") === "WAVE"
  ) {
    return buf.subarray(WAV_HEADER_BYTES);
  }
  return buf;
}

function streamPcmFile(
  sukiToken: string,
  ambientSessionId: string,
  path: string,
): Promise<void> {
  return new Promise((resolve, reject) => {
    const headers: Record<string, string> = {
      sdp_suki_token: sukiToken,
      ambient_session_id: ambientSessionId,
    };
    if (SDP_PROVIDER_ID) headers.sdp_provider_id = SDP_PROVIDER_ID;

    const ws = new WebSocket(WS_URL, { headers });

    ws.on("open", () => {
      try {
        const rfc3339 = new Date().toISOString().replace(/\.\d{3}Z$/, "Z");
        ws.send(
          JSON.stringify({
            type: "START_TIME",
            data: Buffer.from(rfc3339, "utf8").toString("base64"),
          }),
        );

        const pcm = stripWavHeader(fs.readFileSync(path));
        for (let i = 0; i < pcm.length; i += CHUNK_BYTES) {
          ws.send(
            JSON.stringify({
              type: "AUDIO",
              data: pcm.subarray(i, i + CHUNK_BYTES).toString("base64"),
            }),
          );
        }
        ws.send(JSON.stringify({ type: "AUDIO", data: "RU9G" }));
        ws.close();
      } catch (err) {
        reject(err);
      }
    });

    ws.on("message", (data) => console.log("ws message:", data.toString()));
    ws.on("error", reject);
    ws.on("close", () => resolve());
  });
}

async function endSession(sukiToken: string, ambientSessionId: string): Promise<void> {
  const url = `${BASE_URL}/api/v1/form-filling/session/${ambientSessionId}/end`;
  const response = await fetch(url, {
    method: "POST",
    headers: restHeaders(sukiToken),
  });
  await expectStatus(response, url, 200);
}

async function getStatus(sukiToken: string, ambientSessionId: string): Promise<string> {
  const url = `${BASE_URL}/api/v1/form-filling/session/${ambientSessionId}/status`;
  const response = await fetch(url, { headers: restHeaders(sukiToken) });
  await expectStatus(response, url, 200);
  const data = (await response.json()) as { status: string };
  return data.status;
}

async function getStructuredData(
  sukiToken: string,
  ambientSessionId: string,
): Promise<unknown> {
  const url = `${BASE_URL}/api/v1/form-filling/session/${ambientSessionId}/structured-data`;
  const response = await fetch(url, { headers: restHeaders(sukiToken) });
  await expectStatus(response, url, 200);
  return response.json();
}

async function waitForStructuredData(
  sukiToken: string,
  ambientSessionId: string,
  pollMs = 2000,
): Promise<{ status: string; structured_data: unknown }> {
  for (;;) {
    const status = await getStatus(sukiToken, ambientSessionId);
    console.log("status:", status);
    if (status === "completed") {
      return {
        status,
        structured_data: await getStructuredData(sukiToken, ambientSessionId),
      };
    }
    if (status === "failed" || status === "aborted") {
      return { status, structured_data: null };
    }
    await new Promise((r) => setTimeout(r, pollMs));
  }
}

async function main() {
  const sukiToken = await loginWithRegisterFallback(
    PARTNER_ID,
    PARTNER_TOKEN,
    PROVIDER_ID,
    "Dr. John Smith",
    "org-123",
  );
  console.log("Authenticated");

  const ambientSessionId = await createFormFillingSession(sukiToken);
  console.log("ambient_session_id:", ambientSessionId);

  if (SEED_CONTEXT) {
    await seedContext(sukiToken, ambientSessionId, FORM_TEMPLATE_ID);
    console.log("Context seeded");
  }

  await streamPcmFile(sukiToken, ambientSessionId, AUDIO_PATH);
  console.log("Stream finished");

  await endSession(sukiToken, ambientSessionId);
  console.log("Session ended");

  const result = await waitForStructuredData(sukiToken, ambientSessionId);
  console.log(JSON.stringify(result, null, 2));
}

main().catch((err) => {
  console.error(err);
  process.exit(1);
});

Create your first Form filling session

Authenticate to Get a Suki Token

To begin, you must authenticate to get your access token. Send a POST request to the Login API endpoint with the following parameters in the request body:

partner_id: Your unique , which we provide to you securely offline.
partner_token: The user’s OAuth 2.0 ID token () from your identity provider.
provider_id (Optional): Unique identifier for the . Required for Bearer type partners only.

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 Register API endpoint to create the user, then call /login again.
You only need to call the register endpoint once for each new user.

const BASE_URL = "https://sdp.suki-stage.com";

const response = await fetch(`${BASE_URL}/api/v1/auth/login`, {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    partner_id: "your-partner-id",
    partner_token: "your-jwt-token",
    provider_id: "provider-123", // Omit if not required
  }),
});

const data = await response.json();
if (!response.ok) {
  throw new Error(`Login failed: ${response.status} ${JSON.stringify(data)}`);
}
if (!data.suki_token) throw new Error("login response missing suki_token");
console.log("suki_token:", data.suki_token);

import requests

BASE_URL = "https://sdp.suki-stage.com"

response = requests.post(
    f"{BASE_URL}/api/v1/auth/login",
    json={
        "partner_id": "your-partner-id",
        "partner_token": "your-jwt-token",
        "provider_id": "provider-123",  # Omit if not required
    },
    timeout=60,
)
if response.status_code != 200:
    raise RuntimeError(f"Login failed: {response.status_code} {response.text}")
print("suki_token:", response.json()["suki_token"])

curl --request POST \
  --url https://sdp.suki-stage.com/api/v1/auth/login \
  --header 'Content-Type: application/json' \
  --data '{
    "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.

Create Form Filling Session

Create a seesion by calling the Create Form filling session API endpoint with the following parameters in the request body:

ambient_session_id (Optional): Supply your own Form filling session UUID. If omitted, Suki generates one. Do not pass an Ambient API session ID.
correlation_id (Optional): Client-supplied identifier for tracing or correlating requests.

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.

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.

const BASE_URL = "https://sdp.suki-stage.com";
const sukiToken = "<sdp_suki_token from login>";
const sdpProviderId = ""; // Set only if required

const headers: Record<string, string> = {
  "Content-Type": "application/json",
  sdp_suki_token: sukiToken,
};
if (sdpProviderId) headers.sdp_provider_id = sdpProviderId;

const createResponse = await fetch(`${BASE_URL}/api/v1/form-filling/session/create`, {
  method: "POST",
  headers,
  body: JSON.stringify({}),
});
const created = await createResponse.json();
if (createResponse.status !== 201) {
  throw new Error(`Create failed: ${createResponse.status} ${JSON.stringify(created)}`);
}
console.log("ambient_session_id:", created.ambient_session_id);

import requests

BASE_URL = "https://sdp.suki-stage.com"
suki_token = "<sdp_suki_token from login>"
sdp_provider_id = ""  # Set only if required

headers = {
    "sdp_suki_token": suki_token,
    "Content-Type": "application/json",
}
if sdp_provider_id:
    headers["sdp_provider_id"] = sdp_provider_id

create_response = requests.post(
    f"{BASE_URL}/api/v1/form-filling/session/create",
    headers=headers,
    json={},
    timeout=60,
)
if create_response.status_code != 201:
    raise RuntimeError(
        f"Create failed: {create_response.status_code} {create_response.text}"
    )
print("ambient_session_id:", create_response.json()["ambient_session_id"])

curl --request POST \
  --url https://sdp.suki-stage.com/api/v1/form-filling/session/create \
  --header 'sdp_suki_token: <sdp_suki_token>' \
  --header 'Content-Type: application/json' \
  --data '{}'

Seed Context (Optional)

After creating the session, you can send a POST request to the Seed Context API endpoint to provide form template metadata. Skip this step for the minimum path and add it after your first end-to-end run works.

The request body is optional. If you omit it, skip this step and continue to audio capture. 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 know which templates are available, use Suki Medical form templates API.

const BASE_URL = "https://sdp.suki-stage.com";
const sukiToken = "<sdp_suki_token from login>";
const ambientSessionId = "<form filling ambient_session_id from create>";
const sdpProviderId = "";
const formTemplateId = "019d4cdc-9319-7d81-ae2e-fd6de7f1b4f0"; // Replace with your template UUID

const headers: Record<string, string> = {
  "Content-Type": "application/json",
  sdp_suki_token: sukiToken,
};
if (sdpProviderId) headers.sdp_provider_id = sdpProviderId;

const contextResponse = await fetch(
  `${BASE_URL}/api/v1/form-filling/session/${ambientSessionId}/context`,
  {
    method: "POST",
    headers,
    body: JSON.stringify({
      form_filling: {
        values: [{ form_template_id: formTemplateId }],
      },
    }),
  },
);
if (!contextResponse.ok) {
  throw new Error(`Context failed: ${contextResponse.status} ${await contextResponse.text()}`);
}
console.log("Context seeded");

import requests

BASE_URL = "https://sdp.suki-stage.com"
suki_token = "<sdp_suki_token from login>"
ambient_session_id = "<form filling ambient_session_id from create>"
sdp_provider_id = ""
form_template_id = "019d4cdc-9319-7d81-ae2e-fd6de7f1b4f0"  # Replace with your template UUID

headers = {
    "sdp_suki_token": suki_token,
    "Content-Type": "application/json",
}
if sdp_provider_id:
    headers["sdp_provider_id"] = sdp_provider_id

context_response = requests.post(
    f"{BASE_URL}/api/v1/form-filling/session/{ambient_session_id}/context",
    headers=headers,
    json={"form_filling": {"values": [{"form_template_id": form_template_id}]}},
    timeout=60,
)
if context_response.status_code != 200:
    raise RuntimeError(
        f"Context failed: {context_response.status_code} {context_response.text}"
    )
print("Context seeded")

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

Stream Audio

Stream visit audio on the Partner WebSocket GET /ws/stream 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.The WebSocket message format matches ambient:

START_TIME: Base64 of an RFC 3339 timestamp.
AUDIO: Base64 LINEAR16 PCM chunks (16 kHz, mono; strip a typical 44-byte WAV header).
End marker AUDIO with "data": "RU9G".

Use the complete staging script for a full streaming client. When capture finishes, close the WebSocket, then call end session.

End Session

To complete the session and begin processing, send a POST request to the End Session API endpoint. This signals that you will not send more audio for this session.

const BASE_URL = "https://sdp.suki-stage.com";
const sukiToken = "<sdp_suki_token from login>";
const ambientSessionId = "<form filling ambient_session_id from create>";
const sdpProviderId = "";

const headers: Record<string, string> = { sdp_suki_token: sukiToken };
if (sdpProviderId) headers.sdp_provider_id = sdpProviderId;

const endResponse = await fetch(
  `${BASE_URL}/api/v1/form-filling/session/${ambientSessionId}/end`,
  { method: "POST", headers },
);
if (!endResponse.ok) {
  throw new Error(`End failed: ${endResponse.status} ${await endResponse.text()}`);
}
console.log("Session ended");

import requests

BASE_URL = "https://sdp.suki-stage.com"
suki_token = "<sdp_suki_token from login>"
ambient_session_id = "<form filling ambient_session_id from create>"
sdp_provider_id = ""

headers = {"sdp_suki_token": suki_token}
if sdp_provider_id:
    headers["sdp_provider_id"] = sdp_provider_id

end_response = requests.post(
    f"{BASE_URL}/api/v1/form-filling/session/{ambient_session_id}/end",
    headers=headers,
    timeout=60,
)
if end_response.status_code != 200:
    raise RuntimeError(f"End failed: {end_response.status_code} {end_response.text}")
print("Session ended")

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

Poll Status and Retrieve Structured Data

For the minimum path, poll Check Status API until a terminal state such as completed, then retrieve output with Retrieve Structured Data API.A completed form is one generated_values item with MEDICAL_FORM_STATUS_COMPLETED and a populated data object. Templates without output appear under non_generated_values.After that works, you can also use a webhook so your partner callback receives completion events with _links to follow for results.

Terminal statuses include completed, failed, and aborted.

const BASE_URL = "https://sdp.suki-stage.com";
const sukiToken = "<sdp_suki_token from login>";
const ambientSessionId = "<form filling ambient_session_id from create>";
const sdpProviderId = "";

const headers: Record<string, string> = { sdp_suki_token: sukiToken };
if (sdpProviderId) headers.sdp_provider_id = sdpProviderId;

const structuredResponse = await fetch(
  `${BASE_URL}/api/v1/form-filling/session/${ambientSessionId}/structured-data`,
  { headers },
);
const structured = await structuredResponse.json();
if (!structuredResponse.ok) {
  throw new Error(
    `Structured data failed: ${structuredResponse.status} ${JSON.stringify(structured)}`,
  );
}
console.log(JSON.stringify(structured, null, 2));

import requests

BASE_URL = "https://sdp.suki-stage.com"
suki_token = "<sdp_suki_token from login>"
ambient_session_id = "<form filling ambient_session_id from create>"
sdp_provider_id = ""

headers = {"sdp_suki_token": suki_token}
if sdp_provider_id:
    headers["sdp_provider_id"] = sdp_provider_id

structured_response = requests.get(
    f"{BASE_URL}/api/v1/form-filling/session/{ambient_session_id}/structured-data",
    headers=headers,
    timeout=60,
)
if structured_response.status_code != 200:
    raise RuntimeError(
        f"Structured data failed: {structured_response.status_code} {structured_response.text}"
    )
print(structured_response.json())

curl -X GET "https://sdp.suki-stage.com/api/v1/form-filling/session/YOUR_SESSION_ID/status" \
  -H "sdp_suki_token: YOUR_SUKI_TOKEN"

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, refer to the relevant API Reference pages.

Verify your first Form filling API session

Before you design the full production workflow, confirm that your staging integration can complete this minimum path:

Authenticate successfully and use the returned sdp_suki_token in follow-up requests.
Create a Form filling session and store the returned ambient_session_id.
Stream visit audio on /ws/stream with that Form filling session ID.
End the session and confirm that Suki starts processing.
Poll session status until a terminal state, then retrieve structured data.

After this path works end to end on staging, add form template context, webhooks, recordings, and feedback.

Available tutorials

Form filling

Build a Form filling Session Client

Create a Form filling session, send template context, stream audio, and retrieve structured form data.

20 minIntermediate

Next steps

After completing your first session, add these capabilities when you need them:

Seed Form Filling Context

Bind a medical form template when you need structured form output for a specific template.

Configure Webhooks

Form Filling Error Messages

Map Form filling API error codes for create, stream, and retrieve calls.

Get Started

API References

Form Filling API Quickstart

Access and credentials

Prerequisites

Environments to use for development and testing

Complete staging script

Create your first Form filling session

Verify your first Form filling API session

Available tutorials

Build a Form filling Session Client

Next steps

Seed Form Filling Context

Configure Webhooks

Form Filling Error Messages

​Access and credentials

​Prerequisites

​Environments to use for development and testing

​Complete staging script

​Create your first Form filling session

​Verify your first Form filling API session

​Available tutorials

​Build a Form filling Session Client

​Next steps

Seed Form Filling Context

Configure Webhooks

Form Filling Error Messages

Access and credentials

Prerequisites

Environments to use for development and testing

Complete staging script

Create your first Form filling session

Verify your first Form filling API session

Available tutorials

Build a Form filling Session Client

Next steps