Create Form Filling Session

Quick summary

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.

Last updated:September 2026

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.

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.

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

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.

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

Create session parameters

SukiAmbientSessionType

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.

string

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.

SukiAmbientSessionDelegate

Optional session delegate for this create call. In most apps you set the delegate when you initialize the SDK instead.

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`

Store recordingId and sessionId. Pass recordingId into getFormFillingStructuredData and submitFormFillingFeedback. Do not pass sessionId into those methods.

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.

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.

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.
`SDKNotInitilized`	The SDK is not initialized.	Initialize the SDK, then retry.

Form filling create failures can fall back to offline in the same way as Ambient create. For more error detail, refer to 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.

Next steps

Continue to Set context and retrieve results to set forms, record, end, and retrieve structured data. Refer to Form filling on Mobile SDK for the overview, use cases, and workflow diagram. Refer to Recording controls for start, pause, and resume. Refer to Create ambient session for Ambient create (default sessionType). Refer to Error messages for SukiAmbientCoreError cases.

Get Started

Concepts & Feature Guides

Resources

Create Form Filling Session

Prerequisites

Create a Form filling session

Create session parameters

Create session success response

Create session errors

Next steps

​Prerequisites

​Create a Form filling session

​Create session parameters

​Create session success response

​Create session errors

​Next steps

Prerequisites

Create a Form filling session

Create session parameters

Create session success response

Create session errors

Next steps