> ## Documentation Index
> Fetch the complete documentation index at: https://developer.suki.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Dynamic Form Filling

> Use partner-defined medical form schemas with Form filling APIs, Form filling SDK, Web SDK Form filling, and Mobile SDK Form filling, alone or mixed with Suki defined medical form templates

<div className="quick-summary-wrapper">
  <div className="quick-summary-header">
    <span className="quick-summary-icon" aria-hidden="true" />

    <span className="quick-summary-title">Quick summary</span>
  </div>

  <div className="quick-summary-content">
    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).
  </div>

  <div className="quick-summary-footer">
    <span className="quick-summary-footer-icon" aria-hidden="true" />

    <span className="quick-summary-footer-text">Last updated:</span>
    <span className="quick-summary-footer-date">September 2026</span>
  </div>
</div>

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.

<Note>
  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](/form-filling-sdk/guides/configuration#forms-for-the-session) for hosted SDK options and [Set context and retrieve results](/mobile-sdk/form-filling/form-filling-context-and-results) for iOS.
</Note>

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

| Product | Where you pass entries |
| - | - |
| **Form filling APIs** | **`context.form_filling.values`** on seed or update context |
| **Form filling SDK** | **`forms`** on **`FormFillingClient.start()`** or **`FormFilling`** |
| **Web SDK Form filling** | **`forms`** on **`FormFillingClient.start()`** or **`FormFilling`** (from **`@suki-sdk/js`** or **`@suki-sdk/react`**) |
| **Mobile SDK (iOS)** | **`form_filling.values`** on **`setFormFillingContext`** (`schema` as a JSON object string) |

<Warning>
  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[]`**.
</Warning>

## 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](/form-filling-api-reference/info/suki-medical-form-templates).

## Common use cases

<CardGroup cols={2}>
  <Card title="Hospital-Specific Assessments" icon="hospital">
    Map your hospital's charting form to a `schema` and fill it from the visit conversation without waiting for a new Suki catalog template.
  </Card>

  <Card title="Mixed Visit Capture" icon="layer-group">
    Use a Suki vitals template together with a partner-specific neuro or wound form in the same Form filling session.
  </Card>

  <Card title="Partner Correlation IDs" icon="link">
    Pass `id` and `name` on dynamic entries so you can match results (APIs: `generated_values[].id` / `title`; hosted SDKs: `partner_form_id`; Mobile: `partnerFormId`).
  </Card>

  <Card title="Catalog and Custom Fields" icon="list">
    Continue using Suki Medical form templates where they fit and add schemas only for the fields owned by your product.
  </Card>
</CardGroup>

## Configure Form filling context

Each item must use one of the following configurations:

| Field | Use when | Required |
| - | - | - |
| **`form_template_id`** | Using a static Suki Medical form template | Required if **`schema`** is omitted |
| **`schema`** | Using a dynamic partner-defined form | Required if **`form_template_id`** is omitted |

### Dynamic entry fields

Dynamic entries can also include these optional fields:

| Field | Purpose |
| - | - |
| **`id`** | Partner correlation ID on Context **`form_filling.values[]`** (APIs / Mobile) or **`forms[]`** (hosted SDKs). This is **not** a Suki template UUID. On Form filling APIs, results echo it as **`generated_values[].id`**. On Form filling SDK / Web SDK, results echo it as **`partner_form_id`**. On Mobile SDK, results echo it as **`partnerFormId`**. |
| **`name`** | Display name for the dynamic form. When provided, it is preferred as **`generated_values[].title`** in the structured-data response. |
| **`type`** | MedicalFormType enum **name**, such as **`SKIN_ASSESSMENT`**. If omitted or empty, it maps to **`FORM_TYPE_UNSPECIFIED`**. Unknown enum names are rejected. |

Choose your product to see how to use the Dynamic Form filling feature:

<Tabs>
  <Tab title="Form Filling APIs">
    Form configuration is sent under:

    ```json theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
    {
      "form_filling": {
        "values": []
      }
    }
    ```

    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](/form-filling-api-reference/form-filling-sessions/context). To change it later, use [Update Form filling session context](/form-filling-api-reference/form-filling-sessions/update-context).
  </Tab>

  <Tab title="Form Filling SDK">
    Pass **`forms`** when you call **`start()`** or render **`FormFilling`**. Prefer **`forms`**. **`form_template_ids`** is deprecated, but still works for static Suki templates when **`forms`** is omitted.

    When **`forms`** is provided (including an empty array), it is the only source of Context. **`form_template_ids`** is ignored in that case.

    Requires Form filling SDK **v0.1.0-beta.3** or later. Refer to [Configuration](/form-filling-sdk/guides/configuration#forms-for-the-session).

    ```javascript theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
    // JavaScript: @suki-sdk/form-filling
    await client.start({
      rootElement: document.getElementById("suki-form-container"),
      correlation_id: "YOUR_ENCOUNTER_ID",
      forms: [
        /* static and/or dynamic entries */
      ],
      onSubmit: (result) => {
        /* structured_data */
      },
    });
    ```
  </Tab>

  <Tab title="Web SDK">
    Same **`forms`** contract as Form filling SDK. Import **`FormFillingClient`** / **`FormFilling`** from **`@suki-sdk/js`** or **`@suki-sdk/react`**. You do not need the standalone Form filling packages.

    Requires Web SDK **v3.3.1** or later for dynamic and mixed **`forms`**. Refer to [Web SDK Form filling](/web-sdk/form-filling-overview).

    ```javascript theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
    // JavaScript: @suki-sdk/js
    await formFillingClient.start({
      rootElement: document.getElementById("suki-form-container"),
      correlation_id: "YOUR_ENCOUNTER_ID",
      forms: [
        /* static and/or dynamic entries */
      ],
      onSubmit: (result) => {
        /* structured_data */
      },
    });
    ```
  </Tab>

  <Tab title="Mobile SDK">
    Pass **`form_filling.values`** with **`setFormFillingContext`** after you create a session with **`sessionType: .formFilling`**.

    On Mobile SDK, dynamic **`schema`** must be a **JSON object string**, not a nested dictionary. Match results with **`partnerFormId`** (Context **`id`**), not result **`id`**.

    Requires Mobile SDK **v2.9.0** or later. Refer to [Set context and retrieve results](/mobile-sdk/form-filling/form-filling-context-and-results).

    ```swift theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
    let context: [String: AnyHashable] = [
      "form_filling": [
        "values": [
          ["form_template_id": "<template-uuid>"],
          [
            "id": "partner-wound-1",
            "name": "Wound Check",
            "type": "SKIN_ASSESSMENT",
            "schema": schemaJsonString  // JSON object string
          ]
        ]
      ]
    ]
    SukiAmbientCoreManager.shared.setFormFillingContext(with: context) { _ in }
    ```
  </Tab>
</Tabs>

<AccordionGroup>
  <Accordion title="Mutual Exclusivity Rule" icon="triangle-exclamation">
    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.
  </Accordion>

  <Accordion title="Valid Type Values" icon="list">
    When you provide **`type`**, use the **MedicalFormType enum name**, not its numeric value.

    Supported values:

    ```text theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
    FORM_TYPE_UNSPECIFIED
    SKIN_ASSESSMENT
    NEURO_ASSESSMENT
    VITALS_ASSESSMENT
    RESPIRATORY_ASSESSMENT
    GENITO_URINARY_ASSESSMENT
    GASTRO_INTESTINAL_ASSESSMENT
    CARDIAC_ASSESSMENT
    MSK_ASSESSMENT
    IO_ASSESSMENT
    PAIN_ASSESSMENT
    NIHSS_ASSESSMENT
    BRADEN_ASSESSMENT
    HRA_ASSESSMENT
    LDA_GROUP
    ROVER_NURSING_SCHEMA_LOAD
    ```

    If **`type`** is empty or omitted, it maps to **`FORM_TYPE_UNSPECIFIED`**. An unknown enum name is rejected.
  </Accordion>
</AccordionGroup>

## 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.

<Tabs>
  <Tab title="Form Filling APIs">
    <Tabs>
      <Tab title="Pure Static">
        Use **`form_template_id`** for every entry. This is the original Form filling context pattern.

        ```json theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
        {
          "form_filling": {
            "values": [
              {
                "form_template_id": "019d4cdc-9319-7d81-ae2e-fd6de7f1b4f0"
              },
              {
                "form_template_id": "019d4cdc-aaaa-bbbb-cccc-dddddddddddd"
              }
            ]
          }
        }
        ```

        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`**.
      </Tab>

      <Tab title="Pure Dynamic">
        Use **`schema`** for every entry. You can also provide **`id`**, **`name`**, and **`type`**.

        ```json theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
        {
          "form_filling": {
            "values": [
              {
                "id": "partner-wound-1",
                "name": "Wound Check",
                "type": "SKIN_ASSESSMENT",
                "schema": {
                  "title": "Wound Check",
                  "type": "object",
                  "properties": {
                    "wound_status": {
                      "type": "string"
                    }
                  }
                }
              },
              {
                "id": "partner-pain-1",
                "name": "Pain Form",
                "type": "PAIN_ASSESSMENT",
                "schema": {
                  "title": "Pain",
                  "type": "object",
                  "properties": {
                    "pain_score": {
                      "type": "number"
                    }
                  }
                }
              }
            ]
          }
        }
        ```

        #### Minimal dynamic entry

        The only required field for a dynamic entry is **`schema`**.

        ```json theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
        {
          "form_filling": {
            "values": [
              {
                "schema": {
                  "type": "object",
                  "properties": {
                    "note": {
                      "type": "string"
                    }
                  }
                }
              }
            ]
          }
        }
        ```
      </Tab>

      <Tab title="Mixed">
        You can include static and dynamic entries in the same **`values`** array. The mutual exclusivity rule still applies to each individual object.

        ```json theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
        {
          "form_filling": {
            "values": [
              {
                "form_template_id": "019d4cdc-9319-7d81-ae2e-fd6de7f1b4f0"
              },
              {
                "id": "partner-custom-1",
                "name": "Custom Partner Form",
                "type": "NEURO_ASSESSMENT",
                "schema": {
                  "type": "object",
                  "properties": {
                    "gcs": {
                      "type": "number"
                    }
                  }
                }
              }
            ]
          }
        }
        ```

        For this configuration, expect one **`generated_values`** entry shaped like a static medical form instance and one shaped like a dynamic form instance.
      </Tab>
    </Tabs>
  </Tab>

  <Tab title="Form Filling SDK">
    Pass the same entry shapes in **`forms`**. Import from **`@suki-sdk/form-filling`** or **`@suki-sdk/form-filling-react`**.

    <Tabs>
      <Tab title="Pure Static">
        ```javascript theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
        forms: [
          { form_template_id: "019d4cdc-9319-7d81-ae2e-fd6de7f1b4f0" },
          { form_template_id: "019d4cdc-aaaa-bbbb-cccc-dddddddddddd" },
        ]
        ```
      </Tab>

      <Tab title="Pure Dynamic">
        ```javascript theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
        forms: [
          {
            id: "partner-wound-1",
            name: "Wound Check",
            type: "SKIN_ASSESSMENT",
            schema: {
              title: "Wound Check",
              type: "object",
              properties: {
                wound_status: { type: "string" },
              },
            },
          },
          {
            id: "partner-pain-1",
            name: "Pain Form",
            type: "PAIN_ASSESSMENT",
            schema: {
              title: "Pain",
              type: "object",
              properties: {
                pain_score: { type: "number" },
              },
            },
          },
        ]
        ```

        Minimal dynamic entry:

        ```javascript theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
        forms: [
          {
            schema: {
              type: "object",
              properties: {
                note: { type: "string" },
              },
            },
          },
        ]
        ```
      </Tab>

      <Tab title="Mixed">
        ```javascript theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
        forms: [
          { form_template_id: "019d4cdc-9319-7d81-ae2e-fd6de7f1b4f0" },
          {
            id: "partner-custom-1",
            name: "Custom Partner Form",
            type: "NEURO_ASSESSMENT",
            schema: {
              type: "object",
              properties: {
                gcs: { type: "number" },
              },
            },
          },
        ]
        ```

        In **`onSubmit`**, correlate dynamic rows with **`partner_form_id`** (echo of Context **`id`**), not list order. Refer to [Form filling SDK quickstart](/form-filling-sdk/quickstart).
      </Tab>
    </Tabs>
  </Tab>

  <Tab title="Web SDK">
    Import from **`@suki-sdk/js`** or **`@suki-sdk/react`**.

    <Tabs>
      <Tab title="Pure Static">
        ```javascript theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
        forms: [
          { form_template_id: "019d4cdc-9319-7d81-ae2e-fd6de7f1b4f0" },
          { form_template_id: "019d4cdc-aaaa-bbbb-cccc-dddddddddddd" },
        ]
        ```
      </Tab>

      <Tab title="Pure Dynamic">
        ```javascript theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
        forms: [
          {
            id: "partner-wound-1",
            name: "Wound Check",
            type: "SKIN_ASSESSMENT",
            schema: {
              title: "Wound Check",
              type: "object",
              properties: {
                wound_status: { type: "string" },
              },
            },
          },
        ]
        ```
      </Tab>

      <Tab title="Mixed">
        ```javascript theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
        // JavaScript (@suki-sdk/js)
        await formFillingClient.start({
          rootElement: document.getElementById("suki-form-container"),
          correlation_id: "YOUR_ENCOUNTER_ID",
          forms: [
            { form_template_id: "YOUR_TEMPLATE_ID" },
            {
              id: "partner-wound-1",
              name: "Wound Check",
              type: "SKIN_ASSESSMENT",
              schema: {
                title: "Wound Check",
                type: "object",
                properties: {
                  wound_status: { type: "string" },
                },
              },
            },
          ],
          onSubmit: (result) => {
            for (const row of result.structured_data.generated_values ?? []) {
              // Dynamic: row.partner_form_id === "partner-wound-1"
              console.log(row.partner_form_id, row.form_template_id, row.data);
            }
          },
        });
        ```

        ```jsx theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
        // React (@suki-sdk/react)
        <FormFilling
          correlation_id={encounterId}
          forms={[
            { form_template_id: "YOUR_TEMPLATE_ID" },
            {
              id: "partner-wound-1",
              name: "Wound Check",
              type: "SKIN_ASSESSMENT",
              schema: {
                title: "Wound Check",
                type: "object",
                properties: {
                  wound_status: { type: "string" },
                },
              },
            },
          ]}
          onSubmit={(result) => {
            /* map by partner_form_id */
          }}
        />
        ```

        Refer to [Web SDK Form filling JavaScript](/web-sdk/guides/form-filling-javascript) and [React](/web-sdk/guides/form-filling-react).
      </Tab>
    </Tabs>
  </Tab>
</Tabs>

## Steps to use Dynamic Form filling

Follow these steps for your integration path:

<Tabs>
  <Tab title="Form Filling APIs">
    <Steps>
      <Step title="Create a Form Filling Session">
        Call <Badge color="blue" size="sm">POST</Badge> [Create Form filling session](/form-filling-api-reference/form-filling-sessions/create).

        Store the returned **`ambient_session_id`**. You will use it for the rest of the Form filling workflow.
      </Step>

      <Step title="Seed the Session Context">
        Call <Badge color="blue" size="sm">POST</Badge> [Seed Form filling session context](/form-filling-api-reference/form-filling-sessions/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](/form-filling-api-reference/form-filling-sessions/update-context).
      </Step>

      <Step title="Stream Visit Audio and End the Session">
        Stream visit audio through **`/ws/stream`**.

        When the visit is complete, call [End Form filling session](/form-filling-api-reference/form-filling-sessions/end).

        For the complete capture workflow, see [Form filling basic usage](/documentation/how-to/form-filling/form-filling-basic-usage).
      </Step>

      <Step title="Retrieve Structured Data">
        Poll [status](/form-filling-api-reference/form-filling-sessions/status) until processing is complete.

        Then call [structured data](/form-filling-api-reference/form-filling-sessions/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.
      </Step>
    </Steps>
  </Tab>

  <Tab title="Form Filling SDK">
    <Steps>
      <Step title="Install and Authenticate">
        Install **`@suki-sdk/form-filling`** or **`@suki-sdk/form-filling-react`** with **`@suki-sdk/core`** (**v0.1.0-beta.3** or later). Sign in with **`SukiAuthManager`**.

        Refer to [Form filling SDK quickstart](/form-filling-sdk/quickstart).
      </Step>

      <Step title="Pass Forms When You Start">
        Create **`FormFillingClient`**, then call **`start()`** (JavaScript) or render **`FormFilling`** (React) with **`forms`**: static **`form_template_id`**, partner **`schema`**, or both.

        Pass **`correlation_id`** so callbacks and webhooks map to your encounter. Prefer **`forms`**. **`form_template_ids`** is deprecated, but still works when **`forms`** is omitted.
      </Step>

      <Step title="Capture in the Hosted UI">
        The SDK opens the hosted iframe. The clinician records and submits. You do not manage WebSocket audio yourself.
      </Step>

      <Step title="Handle Structured Results">
        Implement required **`onSubmit`**. For dynamic forms, match **`partner_form_id`** (and/or **`name`**), not list index.

        Register a [partner webhook](/documentation/webhook/overview) for production delivery if the browser can close before processing finishes.
      </Step>
    </Steps>
  </Tab>

  <Tab title="Web SDK">
    <Steps>
      <Step title="Install Web SDK Form Filling">
        Use **`@suki-sdk/js`** or **`@suki-sdk/react`** with **`@suki-sdk/core`**. Dynamic and mixed **`forms`** require Web SDK **v3.3.1** or later. You do not need the standalone Form filling packages.

        Refer to [Web SDK Form filling overview](/web-sdk/form-filling-overview).
      </Step>

      <Step title="Pass Forms When You Start">
        Import **`FormFillingClient`** / **`FormFilling`** from the Web SDK package. Pass the same **`forms`** contract as Form filling SDK: static, dynamic, or mixed.
      </Step>

      <Step title="Capture in the Hosted UI">
        Open Form filling from a click handler (**`start()`**) or by mounting **`FormFilling`**. The hosted UI handles recording and submit.
      </Step>

      <Step title="Handle Structured Results">
        Use **`onSubmit`** (and React **`onBackgroundSubmit`** when needed). Correlate dynamic rows with **`partner_form_id`**.

        Refer to [Form filling JavaScript](/web-sdk/guides/form-filling-javascript) or [Form filling React](/web-sdk/guides/form-filling-react).
      </Step>
    </Steps>
  </Tab>

  <Tab title="Mobile SDK">
    <Steps>
      <Step title="Create with sessionType Form Filling">
        Call **`createSession`** with **`sessionType: .formFilling`** and optional **`kCorrelationId`**. Store **`recordingId`**.

        Refer to [Create Form filling session](/mobile-sdk/form-filling/create-form-filling-session).
      </Step>

      <Step title="Set Form Filling Context">
        Call **`setFormFillingContext`** with **`form_filling.values`**. For dynamic entries, pass **`schema`** as a **JSON object string**. You can mix static and dynamic entries.

        Refer to [Set context and retrieve results](/mobile-sdk/form-filling/form-filling-context-and-results).
      </Step>

      <Step title="Record and End">
        Use **start** / **pause** / **resume**, then **`endFormFillingSession()`** (or **`end()`**).
      </Step>

      <Step title="Retrieve Structured Data">
        Call **`getFormFillingStructuredData(for: recordingId)`**. Match dynamic rows with **`partnerFormId`**. There is no Form filling status API.
      </Step>
    </Steps>
  </Tab>
</Tabs>

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:

```json theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
{
  "structured_data": {
    "generated_values": [],
    "non_generated_values": []
  }
}
```

The fields returned in **`generated_values`** differ depending on whether the form was created from a Suki template or a dynamic schema.

| Field | Static template | Dynamic schema |
| - | - | - |
| **`id`** (APIs) | Suki medical form UUID | Partner Context **`form_filling.values[].id`** when you sent one |
| **`partner_form_id`** (hosted SDKs) | Typically empty | Echo of Context / **`forms[].id`** when you sent one |
| **`partnerFormId`** (Mobile SDK) | Typically empty | Echo of Context **`id`** when you sent one |
| **`data`** | Filled JSON | Filled JSON |
| **`correlation_id`** | Session group | Session group |
| **`created_at`** | Set | Set |
| **`type`** | From template or instance | From context **`type`** when provided |
| **`title`** | From form or template | From context **`name`** when provided |
| **`patient_id`** | From medical form when available | From ambient context or dynamic row when available |
| **`status`** | Set, for example **`completed`** | Typically empty |
| **`form_template_id`** | Set | Typically empty |

<Warning>
  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.
</Warning>

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

| Payload | Result |
| - | - |
| **`values: []`** (API) or empty usable **`forms`** after resolve (SDK) | Rejected or **`SUKI_FF_001`**. Supply at least one valid entry. |
| Entry containing both **`form_template_id`** and **`schema`** | Rejected because the fields are mutually exclusive. |
| Entry containing neither **`form_template_id`** nor **`schema`** | Rejected. |
| Invalid UUID in **`form_template_id`** | Rejected. |
| Unknown **`type`** enum name | Rejected. |

## Best practices

<AccordionGroup>
  <Accordion title="Context and Entry Best Practices" icon="circle-check">
    * 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.
  </Accordion>

  <Accordion title="Type, Correlation, and SDK Notes" icon="circle-info">
    * **`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**.
  </Accordion>
</AccordionGroup>

## Next steps

<Icon icon="file-lines" iconType="solid" /> Refer to [Form filling templates](/documentation/concepts/form-filling/form-filling-templates) for Suki Medical form templates and static **`form_template_id`** binding.

<Icon icon="file-lines" iconType="solid" /> Refer to [Form filling basic usage](/documentation/how-to/form-filling/form-filling-basic-usage) for the API create, context, stream, end, and structured-data workflow.

<Icon icon="file-lines" iconType="solid" /> Refer to [Form filling SDK configuration](/form-filling-sdk/guides/configuration#forms-for-the-session) or [Web SDK Form filling](/web-sdk/form-filling-overview) to pass **`forms`** in the hosted UI.

<Icon icon="file-lines" iconType="solid" /> Refer to [Set context and retrieve results](/mobile-sdk/form-filling/form-filling-context-and-results) for iOS **`setFormFillingContext`**.

<Icon icon="file-lines" iconType="solid" /> Refer to [Seed Form filling session context](/form-filling-api-reference/form-filling-sessions/context) for API request examples.