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

# Create Form Filling Session

> Create a Form filling session on iOS with createSession and sessionType formFilling, pass kCorrelationId, and store recordingId

<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">
    Call `createSession` with `sessionType: .formFilling` to start a Form filling session on iOS SDK. Pass optional `SukiAmbientConstant.kCorrelationId` for your appointment id. On success, store `recordingId` for retrieve and feedback. The response `sessionId` is the correlation id (passed or generated), not the retrieve key.
  </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>

Before you can record audio and fill medical forms, you must create a Form filling session. This guide explains how to create that session, which create parameters Form filling uses, and how to store the response fields you need for context, recording, retrieve, and feedback.

<Note>
  Form filling on Mobile SDK requires Mobile SDK **v2.9.0** or later (iOS). For the product overview and Ambient vs Form filling comparison, refer to [Form filling on Mobile SDK](/mobile-sdk/form-filling/overview).
</Note>

**What will you learn?**

In this guide, you will learn how to:

* Create a Form filling session with `createSession` and `sessionType: .formFilling`.
* Pass optional `kCorrelationId` and understand which Ambient create keys Form filling ignores.
* Store `recordingId` and `sessionId` from the success response.
* Handle create errors such as `sessionInProgress` and `remoteSessionConflict`.

## Prerequisites

Before you call `createSession` for Form filling:

* Install, configure, and initialize the Mobile SDK. Refer to [Installation](/mobile-sdk/installation) and [Configuration](/mobile-sdk/configuration).
* Provide a Partner Token the same way you do for Ambient.
* Have an appointment or encounter id ready if you want to pass `kCorrelationId`.
* End or cancel any active session on this device. Only one local session can run at a time.

## Create a Form filling session

To fill medical forms from a visit, create a Form filling session instead of an Ambient note session. The session holds the audio and form context for that encounter.

Pass `sessionType: .formFilling` on `createSession`. Omit `sessionType` to keep Ambient behavior (defaults to `.ambient`).

```swift Swift theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
public enum SukiAmbientSessionType {
    case ambient      // default: existing Ambient behavior
    case formFilling
}
```

For Form filling create, the SDK reads **only** `kCorrelationId` from the session info dictionary. Other Ambient create keys such as `kEmrEncounterId`, `kSessionId`, and `kIsMultilingual` are not used.

<CodeGroup>
  ```swift Swift theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
  SukiAmbientCoreManager.shared.createSession(
      with: [
          SukiAmbientConstant.kCorrelationId: appointmentId  // key: "correlationId"
      ],
      sessionType: .formFilling,
      withSessionDelegate: nil,  // optional; usually set on initialize
      onCompletion: { result in
          switch result {
          case .success(let response):
              // Store recordingId for retrieve and feedback after the visit.
              let recordingId = response.recordingId
              let sessionId = response.sessionId  // correlation id, not the retrieve key
              // noteId is always nil for Form filling
          case .failure(let error):
              // sessionInProgress, remoteSessionConflict, or offline fallback
              print(error)
          }
      }
  )
  ```
</CodeGroup>

### Create session parameters

<ResponseField name="sessionType" type="SukiAmbientSessionType" required={false}>
  Session kind for this create call. Pass `.formFilling` for Form filling. Omit the argument or pass `.ambient` for an Ambient note session. The default is `.ambient`.
</ResponseField>

<ResponseField name="SukiAmbientConstant.kCorrelationId" type="string" required={false}>
  Your appointment or encounter id for this Form filling session. String key: `"correlationId"`.

  If you omit it, the SDK generates a UUID. The create response `sessionId` is this correlation id (passed or generated). Use the same value for every Form filling create that belongs to the same visit when you care about offline queueing for that encounter.
</ResponseField>

<ResponseField name="withSessionDelegate" type="SukiAmbientSessionDelegate" required={false}>
  Optional session delegate for this create call. In most apps you set the delegate when you initialize the SDK instead.
</ResponseField>

### Create session success response

A successful `createSession` call still returns `SessionResponse`, but the fields mean different things for Form filling than for Ambient. Refer to the following table for the differences.

| Field | Ambient | Form filling |
| - | - | - |
| Dict **`sessionId`** (`kSessionId`) | Ambient API `encounter_id` (re-ambient) | Ignored |
| Dict **`correlationId`** (`kCorrelationId`) | n/a | Optional partner encounter / appointment id. If omitted, the SDK generates a UUID |
| Dict **`emrEncounterId`** (`kEmrEncounterId`) | Shared note across products | Not used |
| Dict **`isMultilingual`** | Ambient | Not used |
| **`SessionResponse.sessionId`** | Ambient session id | The correlation id (passed or generated) |
| **`SessionResponse.recordingId`** | Recording id | Recording id for retrieve and feedback. **Store this** |
| **`SessionResponse.noteId`** / **`compositionId`** | Online note id | Always **`nil`** |

<Warning>
  Store **`recordingId`** and **`sessionId`**. Pass **`recordingId`** into **`getFormFillingStructuredData`** and **`submitFormFillingFeedback`**. Do **not** pass **`sessionId`** into those methods.
</Warning>

<Note>
  For Ambient sessions, **`sessionId`** and **`recordingId`** are the same value. For Form filling, treat them as different: **`recordingId`** is what you use for retrieve and feedback.
</Note>

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

## Create session errors

Handle these errors before you retry `createSession`.

| Error | Description | What to do |
| - | - | - |
| **`sessionInProgress`** | Another session is already creating, recording, or paused on this device. | End or cancel the current session, then retry. |
| **`remoteSessionConflict(blockingSessionId:)`** | Another Suki session is in progress for the same encounter. | Call `cancelRemoteAmbientSession` or `endSessionRemotely` with the returned `blockingSessionId`, then retry. Refer to [Ambient interoperability](/mobile-sdk/ambient-guides/ambient-interoperability). |
| **`SDKNotInitilized`** | The SDK is not initialized. | Initialize the SDK, then retry. |

<Note>
  * Form filling create failures can fall back to offline in the same way as Ambient create. For more error detail, refer to [Error messages](/mobile-sdk/error-messages).

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

## Next steps

<Icon icon="file-lines" iconType="solid" /> Continue to [Set context and retrieve results](/mobile-sdk/form-filling/form-filling-context-and-results) to set forms, record, end, and retrieve structured data.

<Icon icon="file-lines" iconType="solid" /> Refer to [Form filling on Mobile SDK](/mobile-sdk/form-filling/overview) for the overview, use cases, and workflow diagram.

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

<Icon icon="file-lines" iconType="solid" /> Refer to [Create ambient session](/mobile-sdk/ambient-guides/create-session) for Ambient create (default **`sessionType`**).

<Icon icon="file-lines" iconType="solid" /> Refer to [Error messages](/mobile-sdk/error-messages) for **`SukiAmbientCoreError`** cases.