Create Session

Create an ambient session with createSession(with:onCompletion:), pass EMR encounter IDs for Ambient API interoperability, and store sessionId and compositionId

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:August 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 for interoperable notes and kSessionId (Ambient API encounter_id) for re-ambient workflows.
• 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.kSessionId: "visit-note-1",
    SukiAmbientConstant.kIsMultilingual: false,
]

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:

SukiAmbientConstant.kEmrEncounterId · 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.

SukiAmbientConstant.kSessionId · string

Ambient API encounter_id for re-ambient workflows. String key: "sessionId".

This field is required for re-ambient workflows. Reuse the same value for every session on that note.

This value is not the create response sessionId, which identifies the current ambient session. It is also not compositionId, which identifies the shared clinical note.

SukiAmbientConstant.kIsMultilingual · 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.
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 kSessionId / Ambient API encounter_id for re-ambient sessions. The create response sessionId is not that value. compositionId is the note 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.