> ## 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.
# Seed Form Filling with a Suki Template
> List Suki Medical form template IDs, then seed Form filling session context with form_template_id before you stream
export const CbRecipeMeta = ({items = []}) =>
;
};
}
sidebar={{
tutorialHref: "/documentation/tutorials/form-filling-websocket-code-example",
apiHref: "/form-filling-api-reference/form-filling-sessions/context",
authSections: [
{
title: "Partner API",
text: "Authenticate every REST call with Partner Token headers on each request. See",
href: "/documentation/get-started/partner-authentication",
linkLabel: "Partner authentication",
scopes: ["sdp_suki_token", "sdp_provider_id"],
},
],
glance: [
{ label: "Product", value: "Form Filling" },
{ label: "Surface", value: "Partner API" },
{ label: "Time", value: "~10 min" },
{ label: "Level", value: "Beginner" },
],
}}
>
## Problem
You create a Form filling session and stream audio, but structured results are empty or the context call fails. The session has no form bound yet.
Seed context with at least one Suki `form_template_id` (or a partner `schema`) before you end the session. List available templates from [Suki Medical form templates](/form-filling-api-reference/info/suki-medical-form-templates), then call [Seed Form filling session context](/form-filling-api-reference/form-filling-sessions/context).
## Architecture
```mermaid actions={false} theme={"theme":{"light":"one-light","dark":"material-theme-darker"}}
%%{init: {'theme':'base', 'themeVariables': { 'primaryColor':'#FFFBDE','primaryTextColor':'#1C1C1C','primaryBorderColor':'#FFD147','lineColor':'#6F5410','secondaryColor':'#FFFDF5','tertiaryColor':'#FFEB94','fontSize':'13px'}}}%%
flowchart LR
A[Login] --> B[Create Form filling session]
B --> C[List Suki templates]
C --> D[POST /context]
D --> E[Stream /ws/stream]
```
## Prerequisites
Completed [Partner onboarding](/documentation/get-started/partner-onboarding) and can obtain `sdp_suki_token` from Login.A Form filling session id from create (`ambient_session_id` on the Form filling create response).Suki enabled Medical form templates for your partner account. Do not invent template UUIDs.
## Solution
Login, then create a Form filling session.
List Suki templates and seed context with `form_template_id`.
Stream on `/ws/stream` with [Send START\_TIME Before Ambient Audio](/documentation/cookbooks/send-start-time-before-ambient-audio), then end the Form filling session.
Each object in `form_filling.values` must use exactly one of `form_template_id` or `schema`. This recipe uses a static Suki template. For partner-defined forms, see [Dynamic Form filling](/documentation/concepts/form-filling/dynamic-form-filling).
```typescript theme={"theme":{"light":"one-light","dark":"material-theme-darker"}}
// seed-form-filling-template-context.ts
// Flow: list Suki templates → pick template_id → POST Form filling context
const BASE_URL = process.env.SUKI_BASE_URL ?? "https://sdp.suki.ai";
const SDP_SUKI_TOKEN = process.env.SDP_SUKI_TOKEN!;
const SDP_PROVIDER_ID = process.env.SDP_PROVIDER_ID ?? "";
const AMBIENT_SESSION_ID = process.env.AMBIENT_SESSION_ID!; // Form filling create response
function restHeaders(): Record {
const headers: Record = {
"Content-Type": "application/json",
sdp_suki_token: SDP_SUKI_TOKEN,
};
if (SDP_PROVIDER_ID) headers.sdp_provider_id = SDP_PROVIDER_ID;
return headers;
}
type MedicalFormTemplate = {
template_id?: string;
name?: string;
description?: string;
};
async function listSukiFormTemplates(): Promise {
const res = await fetch(`${BASE_URL}/api/v1/info/suki-medical-form-templates`, {
headers: restHeaders(),
});
if (!res.ok) {
throw new Error(`List form templates failed: ${res.status}`);
}
const data = (await res.json()) as { form_templates?: MedicalFormTemplate[] };
if (!Array.isArray(data.form_templates)) {
throw new Error("Response missing form_templates array");
}
return data.form_templates;
}
async function seedFormFillingTemplateContext(
ambientSessionId: string,
formTemplateId: string
): Promise {
const res = await fetch(
`${BASE_URL}/api/v1/form-filling/session/${ambientSessionId}/context`,
{
method: "POST",
headers: restHeaders(),
body: JSON.stringify({
form_filling: {
values: [{ form_template_id: formTemplateId }],
},
}),
}
);
if (!res.ok) {
throw new Error(`Seed Form filling context failed: ${res.status}`);
}
}
const templates = await listSukiFormTemplates();
const formTemplateId = templates.find((t) => typeof t.template_id === "string")
?.template_id;
if (!formTemplateId) {
throw new Error("No template_id returned. Confirm templates are enabled for your partner.");
}
await seedFormFillingTemplateContext(AMBIENT_SESSION_ID, formTemplateId);
console.log("Seeded form_template_id:", formTemplateId);
```
```python theme={"theme":{"light":"one-light","dark":"material-theme-darker"}}
# seed_form_filling_template_context.py
# Flow: list Suki templates → pick template_id → POST Form filling context
# pip install requests
import os
from typing import Any
import requests
BASE_URL = os.environ.get("SUKI_BASE_URL", "https://sdp.suki.ai")
SDP_SUKI_TOKEN = os.environ["SDP_SUKI_TOKEN"]
SDP_PROVIDER_ID = os.environ.get("SDP_PROVIDER_ID", "")
AMBIENT_SESSION_ID = os.environ["AMBIENT_SESSION_ID"] # Form filling create response
def rest_headers() -> dict[str, str]:
headers = {
"Content-Type": "application/json",
"sdp_suki_token": SDP_SUKI_TOKEN,
}
if SDP_PROVIDER_ID:
headers["sdp_provider_id"] = SDP_PROVIDER_ID
return headers
def list_suki_form_templates() -> list[dict[str, Any]]:
res = requests.get(
f"{BASE_URL}/api/v1/info/suki-medical-form-templates",
headers=rest_headers(),
timeout=60,
)
res.raise_for_status()
templates = res.json().get("form_templates")
if not isinstance(templates, list):
raise RuntimeError("Response missing form_templates array")
return templates
def seed_form_filling_template_context(
ambient_session_id: str,
form_template_id: str,
) -> None:
res = requests.post(
f"{BASE_URL}/api/v1/form-filling/session/{ambient_session_id}/context",
headers=rest_headers(),
json={
"form_filling": {
"values": [{"form_template_id": form_template_id}],
}
},
timeout=60,
)
if res.status_code != 200:
raise RuntimeError(f"Seed Form filling context failed: {res.status_code} {res.text}")
templates = list_suki_form_templates()
form_template_id = next(
(t["template_id"] for t in templates if isinstance(t.get("template_id"), str)),
None,
)
if not form_template_id:
raise RuntimeError(
"No template_id returned. Confirm templates are enabled for your partner."
)
seed_form_filling_template_context(AMBIENT_SESSION_ID, form_template_id)
print("Seeded form_template_id:", form_template_id)
```
Call Form filling create and store `ambient_session_id`. See [Form filling basic usage](/documentation/how-to/form-filling/form-filling-basic-usage).
`GET /api/v1/info/suki-medical-form-templates` returns `form_templates[].template_id`. Use those values as `form_template_id`.
`POST /api/v1/form-filling/session/{ambient_session_id}/context` with `form_filling.values` containing `{ "form_template_id": "..." }`. Expect HTTP 200.
Stream on `/ws/stream` (same wire format as Ambient), then end with the Form filling REST end endpoint. Retrieve structured data after the session completes.
## Try it
* **List returns real template\_id values**
Your partner account should return one or more `template_id` strings. Empty list means templates are not enabled yet.
* **Context accepts form\_template\_id**
A successful seed returns HTTP 200. Do not send both `form_template_id` and `schema` in the same `values[]` object.
* **Stream uses Ambient wire format**
Form filling audio uses `/ws/stream` with `START_TIME`, PCM in `data`, and `RU9G`, then Form filling REST end.
## Common mistakes
* Invent a `form_template_id` UUID instead of listing Suki templates for your partner.
* Put both `form_template_id` and `schema` in the same `values[]` entry.
* Seed after you already ended the session, or skip seed entirely before retrieve.
## Related cookbooks
Send START\_TIME before PCM on /ws/stream.
Same RU9G wire end; use Form filling REST end for Form filling sessions.