Form Filling SDK Introduction

Integrate the Form filling SDK to run voice-driven medical forms in a hosted iframe, with sessions, templates, and structured EHR-ready output

The Suki Form filling SDK is a headed JavaScript and React library. It embeds Suki’s hosted iframe UI in your web app so clinicians can complete medical forms by voice. Use it when you want structured medical form data for your EHR without building the Form filling UI yourself.

This standalone SDK is not headless. For Form filling without a hosted iframe, use the Form filling API.

After you initialize the SDK, start a single-form or multi-form Form filling session.

During a Form filling session:

• The SDK opens Suki’s hosted iframe UI in your web application.
• The clinician selects a form (when multiple templates are available), completes it by voice, and submits the session.
• After processing completes, Suki returns structured form data through onSubmit and your partner webhook.

• The Form filling SDK is a headed SDK: it manages authentication, the hosted iframe UI, and result callbacks for you.
• If you need a custom UI or want to capture audio outside the hosted iframe, use the Form filling API.

Supported packages

React

Use @suki-sdk/form-filling-react for React web applications.

Install the Form filling SDK for React:

Install for React Command Copied!

Learn more

Vanilla JavaScript

Use @suki-sdk/form-filling for vanilla JavaScript applications.

Install the Form filling SDK for JavaScript:

Install for JavaScript Command Copied!

Learn more

What you need to start a session

Prefer the forms array when you open Form filling. For static Suki forms, work with Suki’s Support team to get the Medical form template IDs enabled for your partner account. For partner-defined forms, pass a schema in forms. Pass your encounter ID as correlation_id so structured results map to the correct record in your app and on your server.

Refer to Prerequisites and Dynamic Form filling.

Single-form and Multi-form sessions

How Form filling behaves depends on how many forms you include in forms (or form_template_ids when forms is omitted) when you start a session.

Single Form

Use one form. The clinician goes straight to recording. Suki shows the form name and a recording banner.

Multi-Form

Use more than one form. The clinician picks which forms to fill on a selection screen first. All forms start selected, and at least one must stay selected.

Refer to Session workflow for recording controls, cancel behavior, and how results are delivered.

Common integration patterns and use cases

The Form filling SDK provides a hosted UI for selecting forms, recording by voice, and returning structured form results. Your application owns the forms you pass (static template IDs, partner schemas, or both), encounter correlation, and how structured fields map into your EHR.

The following examples show common ways to integrate the Form filling SDK into your web application.

Capture a Single Assessment by Voice

Start Form filling with one entry in forms. After the clinician records and submits, map the structured fields from onSubmit into the patient record.

Capture Multiple Forms in One Session

Pass multiple entries in forms so the clinician can select forms in the hosted UI, then receive structured results for each submitted form.

Update Forms Mid-Session

Change the selected templates during the assessment without ending the session so recording continues with the updated set.

Persist Results to Your EHR

Handle onSubmit in the browser and configure a partner webhook so your backend still receives results if the tab closes during processing.

Capture Forms in Person

Open the hosted Form filling UI from bedside workflows and map returned fields into your charting model without building the full Form filling API yourself.

Capture Forms on Telehealth Screens

Open the same hosted Form filling UI on virtual visit screens and hand structured results back to your app the same way as in-person sessions.

How the Form filling SDK works

1. Your Web Application

   • You choose when Form filling opens and where it appears on the page.
   • Your code starts a session and listens for onSubmit and other callbacks.
   • Your app maps the structured JSON to your EHR or downstream systems.
2. Suki Services

   • Sign-in: SukiAuthManager authenticates with your partner credentials and supplies tokens to the hosted UI.
   • Hosted Form filling: Form selection, recording, and processing run in a hosted iframe at https://sdk.suki.ai/form-filling (production) or https://sdk.suki-stage.com/form-filling (staging).
3. Typical Session

   1. Create SukiAuthManager and FormFillingClient with partner credentials.
   2. Call client.start() or render FormFilling with preferred forms (static, dynamic, or mixed) and optional correlation_id. form_template_ids is deprecated, but still works when forms is omitted.
   3. The clinician selects forms (multi-form only), speaks, and submits in the hosted UI.
   4. After processing, structured JSON arrives through onSubmit in the browser and through your Partner webhook on your server.

Refer to Session workflow for single-form, multi-form, offline, and webhook details.

Next steps

Installation - Add packages to your project.

Prerequisites - Browser, webhook, and template requirements.

Quickstart - JavaScript and React examples through your first session.