Skip to main content
Quick summary
Dynamic Form filling lets you fill medical forms you define yourself, as well as medical form templates that Suki provides. In one session you can use Suki templates, your own form layouts, or a mix of both. For each form, send either a Suki template or your own field definitions, not both. The same XOR contract applies on Form filling APIs, Form filling SDK, Web SDK Form filling, and Mobile SDK Form filling (iOS).
Last updated:September 2026
Dynamic Form filling lets you use your own hospital or EHR medical forms, instead of limiting your workflow to the predefined Suki Medical form templates. You define the fields for your form with a schema object. Suki uses the visit conversation to fill those fields and returns the results as structured data. You can also continue using Suki form templates in the same session.
Dynamic Form filling is available on the Form filling APIs, the hosted Form filling SDK (v0.1.0-beta.3 or later), Web SDK Form filling (v3.3.1 or later), and Mobile SDK Form filling (v2.9.0 or later, iOS).
  • APIs: Pass entries in form_filling.values when you seed or update session context.
  • Form filling SDK and Web SDK: Pass the same entry shapes in forms when you start the hosted UI.
  • Mobile SDK: Pass entries in form_filling.values through setFormFillingContext. On iOS, dynamic schema must be a JSON object string.
Refer to Configuration for hosted SDK options and Set context and retrieve results for iOS.

โ€‹
How Dynamic Form filling works

Each Form filling session receives a list of form entries. Each entry represents one form to fill and must use exactly one of:
  • form_template_id for a predefined Suki Medical form
  • schema for a partner-defined form
You can use either type independently or combine both types in the same session. Where you send that list depends on the product:
Each entry must contain exactly one of form_template_id or schema. An entry cannot contain both fields, and an entry containing neither field is rejected. The same rule applies to API values[] and SDK forms[].

โ€‹
When to use Dynamic Form filling

Use a dynamic schema when:
  • Your hospital or product uses a form that is not available in the Suki Medical form template catalog.
  • You need a partner-owned field contract that matches your EHR or internal charting model.
  • A single visit needs to fill both Suki templates and partner-specific forms in the same Form filling session.
Continue using static templates when:
  • A published Suki Medical form template already matches the assessment.
  • You want Suki-managed field definitions from Suki Medical form templates.

โ€‹
Common use cases

Hospital-Specific Assessments

Map your hospitalโ€™s charting form to a schema and fill it from the visit conversation without waiting for a new Suki catalog template.

Mixed Visit Capture

Use a Suki vitals template together with a partner-specific neuro or wound form in the same Form filling session.

Partner Correlation IDs

Pass id and name on dynamic entries so you can match results (APIs: generated_values[].id / title; hosted SDKs: partner_form_id; Mobile: partnerFormId).

Catalog and Custom Fields

Continue using Suki Medical form templates where they fit and add schemas only for the fields owned by your product.

โ€‹
Configure Form filling context

Each item must use one of the following configurations:

โ€‹
Dynamic entry fields

Dynamic entries can also include these optional fields: Choose your product to see how to use the Dynamic Form filling feature:
Form configuration is sent under:
The values array must not be empty when form_filling is included while seeding the session context.Seed context with Seed Form filling session context. To change it later, use Update Form filling session context.
A single entry can contain form_template_id or schema, but not both.An entry containing neither field is also rejected.You can mix static and dynamic objects in the same values or forms array.
When you provide type, use the MedicalFormType enum name, not its numeric value.Supported values:
If type is empty or omitted, it maps to FORM_TYPE_UNSPECIFIED. An unknown enum name is rejected.

โ€‹
Session patterns

You can configure a Form filling session in three ways:
  • Pure static: Suki Medical form templates only
  • Pure dynamic: Partner-defined schemas only
  • Mixed: Suki Medical form templates and partner-defined schemas together
Use the tabs below for API context payloads or hosted SDK forms examples.
Use form_template_id for every entry. This is the original Form filling context pattern.
After processing, structured data typically includes medical-form fields such as id, data, correlation_id, created_at, type, title, patient_id, status, and form_template_id.

โ€‹
Steps to use Dynamic Form filling

Follow these steps for your integration path:
1

Create a Form Filling Session

Call POST Create Form filling session.Store the returned ambient_session_id. You will use it for the rest of the Form filling workflow.
2

Seed the Session Context

Call POST Seed Form filling session context.Add your form configuration under form_filling.values.For each entry, use:
  • form_template_id for a Suki Medical form template
  • schema for a partner-defined form
You can use both entry types in the same session.To change the context later, use Update Form filling session context.
3

Stream Visit Audio and End the Session

Stream visit audio through /ws/stream.When the visit is complete, call End Form filling session.For the complete capture workflow, see Form filling basic usage.
4

Retrieve Structured Data

Poll status until processing is complete.Then call structured data.For dynamic forms, match results with id (same as Context form_filling.values[].id) or title (same as Context name). Do not rely on list order.
If your API workflow needs patient_id in the structured-data response, also send the normal ambient context fields required to provide patient information.

โ€‹
Structured data

Dynamic and static Form filling sessions use the same structured-data envelope:
The fields returned in generated_values differ depending on whether the form was created from a Suki template or a dynamic schema.
When you send id on a dynamic form entry, match the result using the field your product returns: Form filling APIs use generated_values[].id (and title for Context name). Form filling SDK / Web SDK use partner_form_id. Mobile SDK uses partnerFormId. Do not rely on list order.

โ€‹
Non-generated values

non_generated_values lists forms you asked Suki to fill that did not produce filled results. That usually happens when the visit conversation did not include enough information for that form. For Suki Medical form templates, each entry often includes only the form_template_id, so you can tell which template had no output and decide whether to retry, leave the fields blank, or collect the values another way.

โ€‹
Validation and rejected requests

The following context payloads fail validation:

โ€‹
Best practices

  • Use form_template_id for Suki Medical form templates.
  • Use schema for partner-defined forms.
  • Each entry must contain exactly one of these fields.
  • You can mix static and dynamic entries in the same session.
  • API values cannot be empty when form_filling is included. When you pass SDK forms, that list is the only Context source.
  • type must use a MedicalFormType enum name, not a numeric value.
  • An omitted or empty type maps to FORM_TYPE_UNSPECIFIED.
  • Use Context id and name on dynamic entries when you need reliable partner-side correlation.
  • Form filling APIs: match with generated_values[].id / title. Hosted SDKs: partner_form_id. Mobile: partnerFormId. Do not rely on list order.
  • Form filling SDK and Web SDK Form filling accept the same static / dynamic / mixed contract through forms. form_template_ids is deprecated, but still works when forms is omitted. When you pass forms (including forms: [] or forms={[]}), form_template_ids is ignored.
  • Mobile SDK uses setFormFillingContext with form_filling.values. On iOS, dynamic schema must be a JSON object string.

โ€‹
Next steps

Refer to Form filling templates for Suki Medical form templates and static form_template_id binding. Refer to Form filling basic usage for the API create, context, stream, end, and structured-data workflow. Refer to Form filling SDK configuration or Web SDK Form filling to pass forms in the hosted UI. Refer to Set context and retrieve results for iOS setFormFillingContext. Refer to Seed Form filling session context for API request examples.
Last modified on September 29, 2026