Create Session

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

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.

To run Form filling instead of an Ambient note session, pass sessionType: .formFilling on createSession. Omit sessionType to keep Ambient behavior (default .ambient). Refer to Create Form filling session.

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 noteId 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 noteId = sessionResponse.noteId // 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 id for the patient visit (UUID or non-UUID, at most 36 characters). 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 when you set it on the first create. If the first create omitted encounter_id, pass the returned noteId as this value.

This value is not the create response sessionId, which identifies the current ambient session.

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.
noteId	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 note_id.

• Always store sessionId for recording and session content. It maps to Ambient API ambient_session_id.
• Store noteId when present for note-level reads. It maps to Ambient API note_id.
• Store kSessionId / Ambient API encounter_id for re-ambient sessions when you set it on create. If the first create omitted it, pass the returned noteId as the kSessionId value on later creates. The create response sessionId is not that value. noteId is also the path id for note-level APIs.

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 EMR encounter id is invalid or longer than 36 characters.	No.

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

Next steps

Ambient interoperability - Conflict handling, peer terminate, and shared note reads.

Provide clinical context - Enrich the session for better note quality.

Recording controls - Start, pause, and resume recording.