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

# Form Filling with iOS Mobile SDK

> Fill structured medical forms on iOS with the Mobile SDK: create a Form filling session, set form context, record, and retrieve results

<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">
    The iOS Mobile SDK (`SukiAmbientCore`) also supports running a Form filling session, apart from an Ambient note session. Pass `sessionType: .formFilling` on `createSession`, set forms with `setFormFillingContext`, record as usual, end the session, then call `getFormFillingStructuredData(for:)` with `recordingId`. You are responsible for building the form review UI as the SDK is headless and does not render forms.
  </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>

Form filling lets you fill medical forms from the patient visit conversation. You can use Suki defined medical form templates, your own form **`schema`**, or a mix of both. Your application can then review, edit, and save the structured form data.

The Mobile SDK (`SukiAmbientCore`) now supports Form filling sessions in your iOS app. Installation, initialization, Partner Token setup, microphone permissions, and the **start**, **pause**, **resume**, and **cancel** methods work the same way as they do for Ambient. The main differences are how you create a session, provide form context, end the session, and retrieve the results.

You are responsible for building the recorder and form review UI. The SDK manages the Form filling session, audio capture, and structured form output. It does not render forms.

<Note>
  Form filling on Mobile SDK requires Mobile SDK **v2.9.0** or later (iOS).
</Note>

## Prerequisites

Before you begin:

* Install and configure the Mobile SDK. Refer to [Installation](/mobile-sdk/installation) and [Configuration](/mobile-sdk/configuration).
* Initialize the SDK and provide a Partner Token the same way you do for Ambient.
* Request microphone permission before you call `start`.
* Decide which forms to fill: Suki Medical form templates (ask Suki support for template IDs), your own form `schema`, or both. Refer to [Form filling templates](/documentation/concepts/form-filling/form-filling-templates) and [Dynamic Form filling](/documentation/concepts/form-filling/dynamic-form-filling).
* Have an appointment or encounter id ready if you want to pass `kCorrelationId`.

## Common use cases

Below are common ways to use Form filling in an iOS app with the Mobile SDK.

<CardGroup cols={2}>
  <Card title="Fill Suki Medical Form Templates" icon="clipboard-list" href="/mobile-sdk/form-filling/form-filling-context-and-results" arrow={true}>
    Record the visit on device and fill Suki Medical form templates, such as a nursing assessment, then review the filled fields in your app.
  </Card>

  <Card title="Fill Hospital-Specific Forms" icon="code" href="/mobile-sdk/form-filling/form-filling-context-and-results" arrow={true}>
    Fill your own hospital or partner medical forms from the visit conversation, then review and save the structured data in your workflow.
  </Card>

  <Card title="Use Templates and Custom Forms Together" icon="layer-group" href="/mobile-sdk/form-filling/form-filling-context-and-results" arrow={true}>
    In one visit, fill both Suki Medical form templates and your own partner forms, then review all results in your form UI.
  </Card>

  <Card title="Review Forms in Your Own App" icon="paint-brush" href="/mobile-sdk/form-filling/form-filling-context-and-results" arrow={true}>
    Keep your native recorder and form review experience. Use the SDK for the session, audio, and structured form output only.
  </Card>

  <Card title="Run Ambient and Form Filling Sequentially" icon="arrows-rotate" href="/mobile-sdk/form-filling/create-form-filling-session" arrow={true}>
    For the same appointment, run Ambient and Form filling one after the other in either order. They cannot run at the same time.
  </Card>

  <Card title="Collect Feedback on Filled Forms" icon="star" href="/mobile-sdk/form-filling/form-filling-context-and-results#submit-form-filling-feedback" arrow={true}>
    After a clinician reviews the filled forms, collect a rating and optional comments so you can track form quality.
  </Card>
</CardGroup>

## Ambient vs Form filling

The following table compares Ambient and Form filling on the Mobile SDK and how they differ.

| | **Ambient** | **Form filling** |
| - | - | - |
| **Purpose** | Clinical note from the visit | Structured medical form fields from the visit |
| **Partner UI** | Recorder + note review | Recorder + form review (you build the form UI) |
| **Create** | `createSession` (default) | `createSession(..., sessionType: .formFilling)` |
| **Context** | `setSessionContext` | `setFormFillingContext` |
| **End** | `end()` | `endFormFillingSession()` or `end()` |
| **Retrieve** | Status, content, transcript, `getStructuredData` | `getFormFillingStructuredData` only |
| **Feedback** | `submitFeedback` | `submitFormFillingFeedback` |
| **Output** | Note, transcript, diagnoses | `generatedValues` / `nonGeneratedValues` |

<Note>
  One appointment can run Ambient and Form filling **one after the other**. They cannot run at the same time on a device or on another Suki product for the same encounter.
</Note>

If another session is already in progress, create returns **`remoteSessionConflict(blockingSessionId:)`**. Resolve with **`cancelRemoteAmbientSession`** or **`endSessionRemotely`**, then retry. For more information, refer to [Ambient interoperability](/mobile-sdk/ambient-guides/ambient-interoperability) and [Create Form filling session](/mobile-sdk/form-filling/create-form-filling-session).

<Warning>
  Ambient interoperability with `kEmrEncounterId` applies only to Ambient note workflows. It is not supported for Form filling. Passing `emrEncounterId` does not make Form filling share an Ambient note.
</Warning>

## Form filling workflow

The diagram below shows the Form filling session workflow. It follows the same pattern as an Ambient note session, except the create, form context, end, and retrieve steps are Form filling specific.

```mermaid actions={false} theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
sequenceDiagram
    actor User
    participant SDK as Mobile SDK
    participant Backend as Suki Backend

    Note over User,Backend: 1. Initialize and create session
    User->>SDK: Initialize SDK
    User->>SDK: Create session (Form filling)
    SDK->>Backend: Create Form filling session
    Backend-->>SDK: Session created
    SDK-->>User: Return sessionId, recordingId

    Note over User,Backend: 2. Set form context
    User->>SDK: Set Form filling context
    SDK->>Backend: Send form templates or schema

    Note over User,Backend: 3. Record
    User->>SDK: Start, pause, or resume
    SDK->>Backend: Capture audio

    Note over User,Backend: 4. End session
    User->>SDK: End Form filling session
    SDK->>Backend: Finalize recording
    Backend-->>SDK: Generate form field values

    Note over User,Backend: 5. Retrieve structured data
    User->>SDK: Get Form filling structured data
    SDK->>Backend: Request form results
    Backend-->>SDK: Return generatedValues and nonGeneratedValues
    SDK-->>User: Return structured form data

    Note over User,Backend: 6. Optional feedback
    User->>SDK: Submit Form filling feedback
    SDK->>Backend: Send feedback
```

## Related guides

Follow these guides in order to implement Form filling on Mobile SDK.

<CardGroup cols={2}>
  <Card title="Create Form Filling Session" icon="play" href="/mobile-sdk/form-filling/create-form-filling-session" arrow={true}>
    Pass `sessionType: .formFilling`, optional `kCorrelationId`, and store `recordingId` from the create response.
  </Card>

  <Card title="Set Context and Retrieve Results" icon="database" href="/mobile-sdk/form-filling/form-filling-context-and-results" arrow={true}>
    Set templates or partner schemas, record and end the session, retrieve structured data, and submit optional feedback.
  </Card>
</CardGroup>

## Next steps

<Icon icon="file-lines" iconType="solid" /> Start with [Create Form filling session](/mobile-sdk/form-filling/create-form-filling-session).

<Icon icon="file-lines" iconType="solid" /> Then continue to [Set context and retrieve results](/mobile-sdk/form-filling/form-filling-context-and-results).

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

<Icon icon="file-lines" iconType="solid" /> Refer to [Dynamic Form filling](/documentation/concepts/form-filling/dynamic-form-filling) for XOR rules and partner schemas.

<Icon icon="file-lines" iconType="solid" /> Refer to [Recording controls](/mobile-sdk/ambient-guides/recording) for start, pause, and resume.