Form Filling SDK Quickstart

Install Form filling SDK packages, configure SukiAuthManager and FormFillingClient, and start your first Form filling session with forms

This guide walks you through your first Form filling SDK integration.

What you will do

1. Get Suki template_id UUIDs for static entries, and/or define partner schema objects for dynamic form entries.
2. Install the package for your framework (JavaScript or React).
3. Create SukiAuthManager with your partnerToken and provider fields.
4. Create FormFillingClient with that auth manager.
5. Start a session with forms and your encounter ID as correlation_id.

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 for Form filling SDK work.

CopiedCopy promptOpen in Cursor

Prerequisites

Before you start, ensure you have the following:

• Partner credentials from Suki (partnerId and partnerToken).
• Medical form template IDs from Suki’s Support team for static forms, and/or partner schema objects for dynamic forms. Refer to Medical form templates and Dynamic Form filling.
• A browser on HTTPS with microphone access and a page container that has explicit height for the Form filling UI.
• Form filling SDK v0.1.0-beta.3 or later for dynamic and mixed forms.

Refer to Prerequisites for webhooks and CSP requirements.

Forms for the session

The Form filling SDK supports Suki Medical form templates (such as Vitals, Neuro, and Skin) and partner-defined dynamic schemas. Prefer the forms array. Each entry uses either form_template_id or schema. You can mix both in one session. Refer to Form filling templates and Dynamic Form filling.

You can also pass static Suki template IDs with form_template_ids when forms is omitted. That option is deprecated. Prefer forms: [{ form_template_id }]. If you provide forms, it is the only source of Context.

• Template IDs are different for staging and production environments.
• Unsupported static template IDs are dropped when you call start().
• Each forms[] entry must use exactly one of form_template_id or schema.

Your encounter ID (correlation_id)

When you start a Form filling session, pass your encounter or appointment ID in the correlation_id parameter. Suki includes this ID in SDK callbacks and partner webhooks so you can associate results with the correct patient record.

Pass correlation_id when you call start() or render FormFilling, together with forms. Suki returns the same correlation_id in SDK callbacks and partner webhooks when results are available.

Strongly recommended for production:

If you do not provide correlation_id, the hosted UI creates its own ID for the session. That ID does not match your encounter ID, so you must map sessions to patient encounters yourself.

Register a Partner webhook and use correlation_id together with the Form filling session ID to associate webhook events with the correct encounter. For more information, refer to Configuration and the Webhook handler example.

Recommended integration pattern

Create SukiAuthManager and FormFillingClient once per page, then open Form filling only when the clinician starts a session.

Suki Auth Manager

Create SukiAuthManager once after the partner token is available.

Form Filling Client

Create FormFillingClient with that auth manager and reuse it across sessions on the page.

Form Filling Provider (React)

Wrap your components with FormFillingProvider.

Start Form Filling

Mount FormFilling or call client.start() only when the clinician starts a Form filling session.

Do not create a new FormFillingClient on every React render. Reuse a single instance by creating it with useMemo or at module scope.

Create your first Form filling session

1. Install the Packages

   Install the Form filling package for your framework, plus @suki-sdk/core for authentication.

   JavaScript

   pnpm

   pnpm add @suki-sdk/form-filling @suki-sdk/core
   

   React

   pnpm

   pnpm add @suki-sdk/form-filling-react @suki-sdk/core
   
2. Add the Page Container

   Give Form filling a container with real height before the hosted UI opens. JavaScript uses a DOM node you pass as rootElement. React mounts into .suki-form-filling.

   JavaScript

   HTML

   <div id="suki-form-container" style="width: 100%; height: 600px;"></div>
   <button type="button" id="fill-forms-btn">Fill Forms with Suki</button>
   

   React

   CSS

   .suki-form-filling {
     width: 100%;
     height: 600px;
   }
   
3. Run Your First Session

   Create SukiAuthManager and FormFillingClient, then open Form filling when the clinician is ready. Pass forms and your encounter ID as correlation_id.

   JavaScript

   JavaScript

   import { SukiAuthManager } from "@suki-sdk/core";
   import { FormFillingClient } from "@suki-sdk/form-filling";
   
   const authManager = new SukiAuthManager({
     partnerId: "YOUR_PARTNER_ID", // Required
     partnerToken: "YOUR_PARTNER_TOKEN", // Required
     environment: "staging", // Optional
     loginOnInitialize: true, // Optional
     autoRegister: false, // optional (default true); when true, provider fields below are often required
     providerId: "provider-123", // Optional
     providerName: "Dr. Jane Smith", // Optional
   });
   
   const client = new FormFillingClient({
     authManager, // Required
     onError: (err) => console.error(`[${err.code}]`, err.message), // Optional
   });
   
   document.getElementById("fill-forms-btn").addEventListener("click", async () => {
     await client.start({
       rootElement: document.getElementById("suki-form-container"), // Required
       correlation_id: "YOUR_ENCOUNTER_ID", // Optional
       forms: [ // New in v0.1.0-beta.3
         { form_template_id: "YOUR_TEMPLATE_ID" },
         {
           id: "partner-vitals-1",
           name: "Custom vitals",
           schema: {
             items: [
               { id: "heart_rate", type: "int", question: "Heart rate?", unit: "bpm" },
             ],
           },
         },
       ],
       onReady: () => console.log("Form UI ready"), // Optional
       onSubmit: (result) => { // Required
         for (const row of result.structured_data.generated_values ?? []) {
           console.log(row.partner_form_id, row.form_template_id, row.data); // New in v0.1.0-beta.3
         }
       },
       onCancel: () => console.log("Cancelled"), // Optional
     });
   });
   

   Your integration works when the Form filling UI appears, the microphone is active, and onSubmit returns structured_data.

   Replace YOUR_TEMPLATE_ID with template_id UUIDs from your Suki support team. For dynamic-only sessions, omit the static entry and keep partner schema objects.

   Pass your encounter ID as correlation_id so callbacks and webhooks match your record. Register a Partner webhook for production saves on your server.

   React

   React

   import { useMemo, useState } from "react";
   import { SukiAuthManager } from "@suki-sdk/core";
   import {
     FormFillingClient,
     FormFillingProvider,
     FormFilling,
   } from "@suki-sdk/form-filling-react";
   
   export function EncounterPage({ encounterId }: { encounterId: string }) {
     const client = useMemo(() => {
       const authManager = new SukiAuthManager({
         partnerId: "YOUR_PARTNER_ID", // Required
         partnerToken: "YOUR_PARTNER_TOKEN", // Required
         environment: "staging", // Optional
         loginOnInitialize: true, // Optional
         autoRegister: false, // optional (default true); when true, providerName and providerOrgId are often required
         providerId: "provider-123", // Optional
       });
       return new FormFillingClient({ authManager }); // authManager required
     }, []);
   
     const [isFormOpen, setIsFormOpen] = useState(false);
   
     return (
       <FormFillingProvider client={client}>
         <button type="button" onClick={() => setIsFormOpen(true)} disabled={isFormOpen}>
           Fill Forms with Suki
         </button>
   
         {isFormOpen && (
           <FormFilling
             correlation_id={encounterId} // Optional
             forms={[ // New in v0.1.0-beta.3
               { form_template_id: "YOUR_TEMPLATE_ID" },
               {
                 id: "partner-vitals-1",
                 name: "Custom vitals",
                 schema: {
                   items: [
                     { id: "heart_rate", type: "int", question: "Heart rate?", unit: "bpm" },
                   ],
                 },
               },
             ]}
             onReady={() => console.log("Ready")} // Optional
             onSubmit={(result) => { // Required
               for (const row of result.structured_data.generated_values ?? []) {
                 console.log(row.partner_form_id, row.form_template_id, row.data); // New in v0.1.0-beta.3
               }
               setIsFormOpen(false);
             }}
             onCancel={() => setIsFormOpen(false)} // Optional
           />
         )}
       </FormFillingProvider>
     );
   }
   

   Replace YOUR_TEMPLATE_ID with template_id UUIDs from your Suki support team. Match dynamic rows with partner_form_id.

Verify your integration

After you complete your first Form filling session, verify that:

• The hosted Form filling UI loads in your page container.
• The microphone is active during recording. You should see a microphone icon in the UI.
• onSubmit returns structured_data.generated_values. Match dynamic rows with partner_form_id, and static rows with form_template_id.
• correlation_id matches your encounter in SDK callbacks and partner webhooks (when provided).

Available tutorials

Next steps

Session workflow - Single-form vs multi-form sessions, offline behavior, and webhooks.

Callbacks - Event payloads and FormFillingResult.

Authentication - If you need to sign in after page load.