Skip to main content
Before you integrate the Form filling SDK, ensure you have partner credentials, Medical form template IDs, a browser on HTTPS with microphone access, and a production webhook.

​
Partner credentials

You need a partnerId from Partner onboarding, plus a partnerToken (JWT from your identity provider) to sign in. Form filling does not open until sign-in succeeds with valid credentials.

​
Medical form templates and dynamic forms

The Form filling SDK supports Suki defined medical form templates (such as Vitals, Neuro, and Skin) and partner-defined dynamic schemas. You use the forms array when you call client.start() or render FormFilling. The forms array can contain both static Suki templates and dynamic schemas.
  • Static: Pass { form_template_id: "YOUR_TEMPLATE_ID" }. Work with Suki’s Support team to get IDs enabled for your partner account. Each template_id is a unique 36-character UUID.
  • Dynamic: Pass a partner schema (optional id, name, type). Refer to Dynamic Form filling.
  • form_template_ids: Still accepted for static Suki templates when you omit forms, but this option is deprecated. Use forms: [{ form_template_id }] instead. We will remove form_template_ids in a future release.
Requires Form filling SDK v0.1.0-beta.3 or later for dynamic and mixed forms.
  • 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.
If you also use the Form filling API, template_id values are returned from Suki Medical form templates (GET /api/v1/info/suki-medical-form-templates).
SDK integrations should still use static IDs provided by Suki support, or partner-owned schemas you define yourself.

​
Browser and layout

  • Run the SDK in a browser on HTTPS. Microphone access requires a secure context.
  • Give the Form filling container explicit height so the hosted UI is visible.
  • If your app uses a Content-Security-Policy header, allow the hosted Form filling iframe in frame-src:.
Form filling runs in an iframe from that URL. If your CSP blocks it, the UI may not appear or you may see error SUKI_FF_002.

​
Partner webhook

After the clinician submits, Suki processes the Form filling session before structured JSON is ready. Processing may take some time and finishes after the clinician closes the tab. The SDK calls onSubmit in the browser when results are available. For production, also register a Partner webhook during Partner onboarding. Suki sends the same structured data to your server when processing completes. For more information, refer to the Webhook quickstart and Signature verification, or use the Webhook handler example.
Do not rely on onSubmit alone to save results. Use a webhook in production so structured data still reaches your server if the tab closes before processing finishes.

​
Provider context

Form filling only requires partnerId and partnerToken to sign in. Provider fields are optional when you set autoRegister: false (recommended unless you use provider auto-registration). autoRegister defaults to true, and when it is true you must also pass providerName and providerOrgId. If your app already knows which clinician is using Form filling, pass their details when you create SukiAuthManager:
  • providerId: your identifier for that clinician in your system.
  • providerName: display name shown in the hosted UI.
  • providerSpecialty: clinical specialty, for example FAMILY_MEDICINE.
These fields tie the session to the right provider in your workflow. For allowed specialty values, refer to Specialties. Refer to Authentication for autoRegister and the full sign-in options.

​
Next steps

Quickstart - Open your first Form filling session after you have credentials and template IDs.
Last modified on October 16, 2026