Form Filling SDK Session Workflow

Quick summary

When you call start() or render <FormFilling>, 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.

Last updated:August 2026

When you call client.start() or render <FormFilling>, the SDK opens Suki’s 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. Create SukiAuthManager and once per page. Open Form filling only when the clinician is ready.

How a session works

The Iframe Loads

The hosted UI loads inside your container on your web page.

The Clinician Selects Forms (Multi-Form Only)

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 Records and Submits

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.

Suki Processes the Session

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

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

React

{isFormOpen && (
  <FormFilling
    form_template_ids={["YOUR_TEMPLATE_ID"]}
    correlation_id={encounterId}
    onSubmit={(result) => {
      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 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:

React

<FormFilling
  form_template_ids={["template-a", "template-b", "template-c"]}
  correlation_id={encounterId}
  onSubmit={(result) => {
    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 during 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 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, the Webhook handler example, and the EHR handoff example 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

WebhooksAPI

Verify Webhook HMAC Signature

Verify HMAC before parsing JSON.

5 min

Available tutorials

Form filling

Build a Form Filling Session with EHR Handoff

Open a Form filling session and map structured_data to your EHR using correlation_id.

20 minIntermediate

Webhooks

Build a Webhook Notification Receiver

Verify HMAC signatures, parse partner notifications, and handle success and failure events.

10 minBeginner

Next steps

Refer to Callbacks for all session callbacks and events Refer to Configuration for form_template_ids, correlation_id, and session options Refer to Javascript integration and React integration for full setup steps

Get Started

Integration Guides

Concepts & Feature Guides

API Reference

Resources

Form Filling SDK Session Workflow

How a session works

Single-form session

Multi-form session

Submit and processing

Processing screen states

Handling results via onSubmit

Handling background results

Available cookbooks

Verify Webhook HMAC Signature

Available tutorials

Build a Form Filling Session with EHR Handoff

Build a Webhook Notification Receiver

Next steps

​How a session works

​Single-form session

​Multi-form session

​Submit and processing

​Processing screen states

​Handling results via onSubmit

​Handling background results

​Available cookbooks

​Verify Webhook HMAC Signature

​Available tutorials

​Build a Form Filling Session with EHR Handoff

​Build a Webhook Notification Receiver

​Next steps

How a session works

Single-form session

Multi-form session

Submit and processing

Processing screen states

Handling results via onSubmit

Handling background results

Available cookbooks

Verify Webhook HMAC Signature

Available tutorials

Build a Form Filling Session with EHR Handoff

Build a Webhook Notification Receiver

Next steps