> ## 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. # Form Filling SDK Session Workflow > How Form filling sessions start, run, and deliver structured data to your application
When you call `start()` or render ``, the SDK opens Suki's hosted UI in your page. The clinician fills forms by voice, then submits for processing. Pass one value in `form_template_ids` to skip form selection; pass more than one to show the selection screen first.

Structured results arrive in your app through `onSubmit` after processing completes. For production, also register a partner webhook so your server receives the same data even if the clinician closes the browser early.
When you call **`client.start()`** or render **``**, the SDK opens Suki's hosted iframe in your page. The clinician completes the session there by voice. After processing, structured JSON arrives in your app through **`onSubmit`** and on your server through your [Partner webhook](/documentation/webhook/overview). Create **`SukiAuthManager`** and **`FormFillingClient`** once per page. Open Form filling only when the clinician is ready. ## How a session works The hosted UI loads inside your container on your web page. If you passed more than **one** `template_id` in `form_template_ids`, the clinician sees a selection screen. All forms start checked. They confirm which forms to fill, then start recording. If you passed **only one** `template_id`, this step is skipped. Recording starts right away. The clinician speaks to fill the selected forms. They can pause, resume, cancel, or submit. If they cancel, your app receives **`onCancel`** and **`form-filling:cancelled`**. No structured data is returned. If they tap **Close** during recording, a confirmation appears. **Resume Session** returns to recording. **Cancel Session** ends the session with no results. Submit does not return structured data immediately. Suki processes the recording first. The hosted UI shows a processing screen. When structured data is ready, **`onSubmit`** runs and your app receives a **`FormFillingResult`**. Refer to [Payload shape](/form-filling-sdk/guides/callbacks#formfillingresult-payload-shape) to learn more about what it returns. Before the iframe opens, **`FormFillingClient.start()`** validates **`form_template_ids`**. Unsupported IDs are dropped. If none remain, the SDK emits **`SUKI_FF_001`** and does not open the UI. How many values you pass in **`form_template_ids`** decides whether the clinician sees a selection screen first, or goes straight to recording: ```mermaid actions={false} theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}} %%{init: {'theme':'base', 'themeVariables': { 'primaryColor':'#FFE148','primaryTextColor':'#111827','lineColor':'#6B7280','fontSize':'14px','edgeLabelBackground':'#FFFFFF','tertiaryColor':'#F9FAFB','tertiaryTextColor':'#111827','tertiaryBorderColor':'#D1D5DB'}}}%% flowchart TB Start["Start session
client.start or FormFilling"] --> Check{"form_template_ids"} Check -->|One template_id| Single["Skip selection
Recording starts right away"] Check -->|Two or more template_ids| Multi["Selection screen
Clinician confirms forms"] Multi --> Record["Record and submit"] Single --> Record Record --> Process["Suki processes session
Processing screen in iframe"] Process --> Result["onSubmit / form-filling:submitted
FormFillingResult in your app"] style Start fill:#FFE148,stroke:#111827,stroke-width:3px,color:#111827 style Check fill:#FFF394,stroke:#D1D5DB,stroke-width:2px,color:#111827 style Single fill:#ffffff,stroke:#9CA3AF,stroke-width:2px,color:#111827 style Multi fill:#ffffff,stroke:#9CA3AF,stroke-width:2px,color:#111827 style Record fill:#ffffff,stroke:#9CA3AF,stroke-width:2px,color:#111827 style Process fill:#FFFADE,stroke:#D1D5DB,stroke-width:2px,color:#111827 style Result fill:#FFE148,stroke:#111827,stroke-width:3px,color:#111827 ``` ## Single-form session A **single-form session** starts Form filling with **one** `template_id` in **`form_template_ids`**. Suki opens the hosted UI and the clinician goes **straight to recording**. There is no form selection screen. Use this pattern when your app already knows which template the clinician needs, for example a vitals assessment, a skin check, or another fixed form tied to a workflow step in your UI. **What it lets you do** * **Skip selection:** The clinician does not pick forms from a list. Recording starts as soon as the iframe loads. * **Focused workflow:** One session maps to one Medical form template. Your **`onSubmit`** handler receives structured data for that template in **`structured_data.generated_values`**. * **Faster path:** Fewer steps between opening Form filling and speaking, which suits repeat tasks during a shift. * **Same callbacks and webhook flow:** Pass **`correlation_id`**, handle **`onSubmit`**, and register a [Partner webhook](/documentation/webhook/overview) the same way as a multi-form session. The hosted UI shows the **form name** and a **recording banner** so the clinician knows which form they are filling. Below is an example of how to start a single-form session with one **`template_id`** in **`form_template_ids`**: ```jsx React theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}} {isFormOpen && ( { handleResult(result); setIsFormOpen(false); }} onCancel={() => setIsFormOpen(false)} /> )} ``` ## Multi-form session A **multi-form session** starts Form filling with **two or more** `template_id` values in **`form_template_ids`**. Suki opens the hosted UI on a **selection screen** first. The clinician confirms which forms to fill, then starts recording. Use this pattern when one visit or workflow may need **several** Medical form templates, and the clinician should choose which ones apply this time. For example, a head-to-toe assessment where vitals, skin, and neurological forms might all be relevant, but not every form is needed on every round. **What it lets you do** * **Offer a form menu:** Pass every template your workflow supports. The clinician picks the subset for this session instead of you hard-coding one form per launch. * **One recording, multiple forms:** The clinician can fill more than one selected form in a single session. **`onSubmit`** may return multiple entries in **`structured_data.generated_values`**, one per completed form. * **Change selection during the session:** All forms start selected. The clinician can add or remove forms before or during recording. At least one form must stay selected; when only one remains, they cannot deselect it. * **Route results per template:** Loop over **`generated_values`** and map each item to the right EHR section using **`form_template_id`** and **`type`**. * **Same callbacks and webhook flow:** Pass **`correlation_id`**, handle **`onSubmit`**, and register a [Partner webhook](/documentation/webhook/overview) the same way as a single-form session. Below is an example of how to start a multi-form session with several **`template_id`** values in **`form_template_ids`**: ```jsx React theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}} { for (const form of result.structured_data.generated_values) { routeToEhrSection(form); } }} /> ``` ## Submit and processing **`onSubmit`** and **`form-filling:submitted`** do not fire when the clinician taps **submit**. The hosted UI moves to a processing screen while Suki processes the session on the backend. When structured data is ready for the session currently open in the SDK, **`onSubmit`** runs in the browser with a **`FormFillingResult`**. The SDK removes the iframe after that callback. ### Processing screen states While Suki processes the session, the hosted UI may show: * **Uploading** if the clinician submitted while offline. **Close** is disabled until the upload finishes. * **Processing** while Suki generates structured data. **Close** is available. * **Timeout** if processing takes longer than 60 seconds online. **Close** is still available. If the clinician leaves this screen open, results still arrive as **`onSubmit`** / **`form-filling:submitted`** for the same foreground session. If the clinician closes the processing screen before results reach the SDK, your app receives **`form-filling:closed`**. No **`onSubmit`** from that action. ### Handling results via onSubmit **`form-filling:submitted`** fires when structured data is ready for the session currently open in the SDK. This happens when the result's **`ambient_session_id`** matches the active session. Handle this with **`onSubmit`**. It is required in both JavaScript and React. Use it to update your app when results arrive. For example, you can: * Display the completed forms * Show a confirmation message For production, register a [Partner webhook](/documentation/webhook/overview) during [Partner onboarding](/documentation/get-started/partner-onboarding). When processing is complete, Suki sends the same structured results to your server, even if the clinician has already closed the browser. Use **`correlation_id`** and **`ambient_session_id`** to match the results to the correct patient record. If the webhook does not include the full structured data, call [Get Form filling structured data](/form-filling-api-reference/form-filling-sessions/structured-data) to retrieve it. Do not rely on **`onSubmit`** alone to save results. Processing may finish after the clinician closes the tab. Use a webhook in production. Refer to [Callbacks](/form-filling-sdk/guides/callbacks), the [Webhook handler example](/form-filling-sdk/examples/webhook-handler), and the [EHR handoff example](/form-filling-sdk/examples/ehr-handoff) for more information. ### Handling background results **`form-filling:background-submitted`** fires when structured data is ready for a session that is no longer the active session. This happens when the result's **`ambient_session_id`** does not match the session currently open in the SDK. For example, this can happen if: * The clinician closes the timeout or processing screen and starts a new session before the previous session finishes. * A previous or offline session finishes processing while a newer session is already open. In React, handle this event with **`onBackgroundSubmit`**. The iframe remains open. If the clinician stays on the timeout or processing screen for the same session, the result is delivered through **`onSubmit`** or **`form-filling:submitted`**, not **`form-filling:background-submitted`**. ## Available cookbooks
## Available tutorials