Create Session

Quick summary

Call createSession(with:onCompletion:) to create an ambient session. For a shared note across Suki products, pass SukiAmbientConstant.kEmrEncounterId. On success, store sessionId and, when present, compositionId.

Last updated:July 2026

If you want ambient interoperability across Ambient APIs, Mobile SDK, Headless Web SDK, and Web SDK, you must pass SukiAmbientConstant.kEmrEncounterId on createSession. Without it, the session is created, but the clinical note is not shared across products. For the full workflow, refer to Ambient interoperability and Use ambient across modalities.

Before you can record audio and generate clinical notes, you must create an ambient session. This guide explains how to create a session, pass the identifiers required for ambient interoperability, and store the response fields needed for recording and later note retrieval. What will you learn? In this guide, you will learn how to:

Create an ambient session using createSession(with:onCompletion:)
Pass kEmrEncounterId and kSessionId (Session Group ID) for interoperable notes
Store sessionId and compositionId from the success response
Handle create errors that do not fall back to offline

Create an Ambient session

To start capturing audio and generating notes, you must first create a session. The session holds the audio and context for a single patient encounter. Call createSession(with:onCompletion:). When successful, store the returned identifiers for recording and later retrieval.

Swift

let sessionInfo: [String: AnyHashable] = [
    SukiAmbientConstant.kEmrEncounterId: "6ec3920f-b0b1-499d-a4e9-889bf788e5ab",
    SukiAmbientConstant.kIsMultilingual: false,
    // Session Group ID (Ambient API encounter_id):
    // SukiAmbientConstant.kSessionId: existingSessionGroupId,
]

SukiAmbientCoreManager.shared.createSession(with: sessionInfo, onCompletion: { result in
    switch result {
    case .success(let sessionResponse):
        let sessionId = sessionResponse.sessionId
        let compositionId = sessionResponse.compositionId // optional; online only
        print("Session: \(sessionId)")
    case .failure(let error):
        print("Error creating session: \(error)")
    }
})

Session info parameters

The withSessionInfo dictionary accepts these parameters:

string

Your EMR or EHR encounter UUID for the patient visit. String key: "emrEncounterId". Maps to Ambient API emr_encounter_id. Pass this value to make the session interoperable across Ambient APIs, Mobile SDK, and Web SDK.

string

The Session Group ID for the clinical note. String key: "sessionId". Maps to Ambient API encounter_id.Pass this value when you create or re-ambient a session so related ambient sessions contribute to the same note. Do not confuse it with the create response sessionId, which identifies the current ambient session, or with compositionId, which identifies the note.

boolean

default:"false"

Enables multilingual processing for the session. Set this to true if the conversation will be in languages other than English. The default value is false (English only). Once set, this cannot be changed for the session.

Create session success response

A successful createSession call returns the following identifiers. Store these values if you need to continue the session, access the recording, or retrieve the generated clinical note later.

Mobile SDK	Ambient APIs	Available	Use for
`sessionId`	`ambient_session_id`	Always	Identifies the current ambient session. Use it for recording controls and session-scoped content APIs. This is not the Session Group ID.
`compositionId`	`composition_id` (used as `note_id`)	Online sessions only	Identifies the shared clinical note. Store this value for note-level read APIs. Offline `createSession` calls do not return this field.

On Ambient APIs, the equivalent create response fields are ambient_session_id and composition_id.

Always store sessionId for recording and session content. It maps to Ambient API ambient_session_id.
Store compositionId when present for note-level reads. It maps to Ambient API composition_id.
Store the Session Group ID you pass as kSessionId. The create response sessionId is not the Session Group ID. compositionId is the note id. It is not the Session Group ID.

Create session errors

Some createSession failures do not fall back to an offline session. Handle these errors before retrying createSession.

Error	Description	Offline fallback
`remoteSessionConflict(blockingSessionId:)`	Another Suki product already has an active ambient session for the same encounter.	No. Call `cancelRemoteAmbientSession` or `endSessionRemotely` with the returned `blockingSessionId`, then retry `createSession`. For more information, see Ambient interoperability.
`sessionInProgress`	An ambient session is already active on the current device.	No. End or cancel the current session before calling `createSession` again.
`SukiStatus` `FAILED_PRECONDITION` (code `9`)	The backend rejected the create request. For example, the note has already been submitted and cannot be re-ambiented.	No.
`SukiStatus` `INVALID_ARGUMENT` (code `3`)	The backend rejected the create request. For example, the encounter UUID is invalid.	No.

Other createSession failures can still follow the existing offline workflow. For more information, see Offline mode and Error messages.

Next steps

Refer to Ambient interoperability for conflict handling, peer terminate, and shared note reads. Refer to Provide clinical context to enrich the session for better note quality. After you create a session, proceed to Recording controls to start recording.

Get Started

Concepts & Feature Guides

Resources

Create Session

Create an Ambient session

Session info parameters

Create session success response

Create session errors

Next steps

​Create an Ambient session

​Session info parameters

​Create session success response

​Create session errors

​Next steps

Create an Ambient session

Session info parameters

Create session success response

Create session errors

Next steps