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

> Learn how to create an ambient session, pass EMR encounter and session group IDs, and store the create response in the iOS SDK

<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:onCompletion:)` to create an ambient session. For a shared note across Suki products, pass `SukiAmbientConstant.kEmrEncounterId`. On success, store `sessionId` and, when present, `compositionId`.
  </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">July 2026</span>
  </div>
</div>

<Info>
  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](/mobile-sdk/ambient-guides/ambient-interoperability) and [Use ambient across modalities](/documentation/how-to/ambient-clinical-notes/use-ambient-across-modalities).
</Info>

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.

```mermaid actions={false} theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
%%{init: {'theme':'base', 'themeVariables': { 'primaryColor':'#FFF394','primaryTextColor':'#111827','primaryBorderColor':'#FFE148','lineColor':'#FFE148','secondaryColor':'#FFE148','tertiaryColor':'#FFFADE','mainBkg':'#FFF394','secondBkg':'#FFFADE','tertiaryBorderColor':'#FFE148','border1':'#FFE148','border2':'#FFE148','arrowheadColor':'#FFE148','fontFamily':'Inter, system-ui, sans-serif','fontSize':'14px','nodeBorder':'#FFE148','edgeLabelBackground':'#FFE148','clusterBkg':'#FFFADE','clusterBorder':'#FFE148','defaultLinkColor':'#FFE148','titleColor':'#111827','nodeTextColor':'#111827'}}}%%
flowchart LR
    A[Your App] -->|Call createSession| B[Mobile SDK]
    B -->|Request to API| C[Suki Backend]
    C -->|Return sessionId, compositionId| B
    B -->|Return response| A
    A -->|Store IDs| D[Use for recording and notes]

    style A fill:#FFF394,stroke:#FFE148,stroke-width:2px,color:#111827
    style B fill:#FFF394,stroke:#FFE148,stroke-width:2px,color:#111827
    style C fill:#FFF394,stroke:#FFE148,stroke-width:2px,color:#111827
    style D fill:#FFF394,stroke:#FFE148,stroke-width:2px,color:#111827
```

Call `createSession(with:onCompletion:)`. When successful, store the returned identifiers for recording and later retrieval.

```swift Swift theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
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:

<ResponseField name="SukiAmbientConstant.kEmrEncounterId" type="string" required={false}>
  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.
</ResponseField>

<ResponseField name="SukiAmbientConstant.kSessionId" type="string" required={false}>
  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.
</ResponseField>

<ResponseField name="SukiAmbientConstant.kIsMultilingual" type="boolean" default="false" required={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.
</ResponseField>

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

<Note>
  * 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.
</Note>

### 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](/mobile-sdk/ambient-guides/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](/mobile-sdk/ambient-guides/offline-mode) and [Error messages](/mobile-sdk/error-messages).

## Next steps

<Icon icon="file-lines" iconType="solid" /> Refer to [Ambient interoperability](/mobile-sdk/ambient-guides/ambient-interoperability) for conflict handling, peer terminate, and shared note reads.

<Icon icon="file-lines" iconType="solid" /> Refer to [Provide clinical context](/mobile-sdk/ambient-guides/provide-clinical-context) to enrich the session for better note quality.

<Icon icon="file-lines" iconType="solid" /> After you create a session, proceed to [Recording controls](/mobile-sdk/ambient-guides/recording) to start recording.