Provide Additional Clinical Context

Updated:Starting with Mobile SDK v2.6.0+ on iOS SDK, you can attach structured medication orders to an ambient session’s context by passing SukiAmbientConstant.kOrdersInfo into setSessionContext(with:) after you create the session.Learn more in the Medication orders section.

Quick summary

The setSessionContext(with:) method in the mobile SDK allows you to provide optional clinical context to the ambient session for better note generation. This context helps Suki generate more accurate and relevant clinical notes. Call setSessionContext(with:) multiple times. Each call updates or adds to the existing context. This allows you to provide information as it becomes available in your app.

Last updated:April 2026

Overview

After creating a session, you can provide additional clinical information using the setSessionContext(with:) method. This context helps Suki’s AI generate more accurate and relevant clinical notes.

All context parameters mentioned below are optional. Use one or more of these parameters to help Suki generate more accurate and relevant clinical notes. The absence of any parameter will not break existing functionality.

Why provide context?

Better note quality: More accurate sections and diagnoses
Specialty-specific formatting: Notes match your medical specialty
Structured organization: Notes organized by the sections you need
Diagnosis accuracy: Better identification of conditions discussed

Set session context (optional but recommended)

Call setSessionContext(with:) multiple times. Each call updates or adds to the existing context. This allows you to provide information as it becomes available in your app.

do {
    let contextDetail: [String: AnyHashable] = [
        SukiAmbientConstant.kPatientInfo: [
            SukiAmbientConstant.kBirthdate: Date(), // Use yyyy-mm-dd format
            SukiAmbientConstant.kGender: "MALE"
        ],
        SukiAmbientConstant.kProviderContext: [
            SukiAmbientConstant.kSpeciality: "FAMILY_MEDICINE",
            SukiAmbientConstant.kProviderRole: "PRIMARY/ATTENDING" // New in v2.5.0: Optional provider role (Primary/Attending or Consulting)
        ],
        SukiAmbientConstant.kVisitContext: [ 
          // New in v2.5.0: Visit context parameters for improved note generation
            SukiAmbientConstant.kVisitType: "ESTABLISHED_PATIENT", // Optional: New Patient / Intake, Established patient, Wellness, ED
            SukiAmbientConstant.kEncounterType: "AMBULATORY", // Optional: ambulatory, inpatient, ED
            SukiAmbientConstant.kReasonForVisit: "Annual checkup", // Optional: String, max 255 characters
            SukiAmbientConstant.kChiefComplaint: "Routine follow-up" // Optional: String, max 255 characters
        ],

        SukiAmbientConstant.kEmrInfo: [ // New in v2.6.0: Optional EMR info (string)
            SukiAmbientConstant.kTargetEmr: "<emr_identifier>" // Required: which EMR this session uses (string)
        ],
        SukiAmbientConstant.kSections: [
            [SukiAmbientConstant.kCode: "51848-0", SukiAmbientConstant.kCodeType: "loinc"],
            [SukiAmbientConstant.kCode: "11450-4", SukiAmbientConstant.kCodeType: "loinc"]
        ],
        SukiAmbientConstant.kDiagnosisInfo: [
            [
                SukiAmbientConstant.kDiagnosisNote: "Patient presents with chest pain",
                SukiAmbientConstant.kCodes: [
                    [
                        SukiAmbientConstant.kCodeType: "ICD-10",
                        SukiAmbientConstant.kCode: "R06.02",
                        SukiAmbientConstant.kCodeDescription: "Shortness of breath"
                    ]
                ]
            ]
        ],
        // New in v2.6.0: medication orders context parameter for suggesting medication orders
        SukiAmbientConstant.kOrdersInfo: [ 
            MedicationOrderKeys.kMedicationOrders: [
                [
                    MedicationOrderKeys.kDrugName: "Atorvastatin",
                    MedicationOrderKeys.kMedicationCode: [
                        SukiAmbientConstant.kCodeType: "<code_type>", // required; coded values must match a supported catalog in your SDK version
                        SukiAmbientConstant.kCode: "<code>" // required
                    ],
                    MedicationOrderKeys.kStrength: "10 mg", // required
                    MedicationOrderKeys.kFormat: "tablet", // required
                    MedicationOrderKeys.kRoute: "oral", // required
                    MedicationOrderKeys.kLinkedDiagnosisCodes: [
                        [
                            SukiAmbientConstant.kCodeType: "ICD-10",
                            SukiAmbientConstant.kCode: "E78.5"
                        ]
                    ],
                    MedicationOrderKeys.kMetadata: [
                        MedicationOrderKeys.kOrigin: "EMR",
                        MedicationOrderKeys.kEncounterRelation: "CURRENT_ENCOUNTER"
                    ]
                    // Optional: MedicationOrderKeys.kDosage, kFrequency, kMedicationTiming, kStatus, kQuantityDispensed, kNumberOfRefills, kStartDate, kEndDate, kDurationInDays, kInstructions, etc

                ]
            ]
        ]
    ]
    
    try SukiAmbientCore.shared.setSessionContext(with: contextDetail) { result in
        switch result {
        case .success:
            print("Context updated successfully")
        case .failure(let error):
            print("Error updating context: \(error)")
        }
    }
} catch {
    print(error)
}

Call setSessionContext(with:) only after a session has been successfully created. Call createSession first and wait for it to succeed before calling setSessionContext.

Retrieve the generated note and structured dataAfter you call setSessionContext with your additional clinical context (such as provider, patient, or visit details), you can use the Suki Mobile SDK to retrieve your results.Use the content(for:) method to retrieve the generated clinical note and extracted blocks. To pull structured output once processing completes, call getStructuredData(for:).The structured output includes all data the service produces from your specific context, including diagnoses and medication order payloads.For more information on how to retrieve these elements, read our guide on Session status and content retrieval.

Additional context parameters

Patient info

SukiAmbientConstant.kPatientInfo

dictionary

Use this parameter to provide demographic information that helps personalize the note generation.

Hide properties

SukiAmbientConstant.kBirthdate

date

Patient’s date of birth in yyyy-mm-dd format.

SukiAmbientConstant.kGender

string

Patient’s gender. Valid values: “MALE” or “FEMALE”.

Provider context

SukiAmbientConstant.kProviderContext

dictionary

Use this parameter to provide information about the healthcare provider to tailor note generation to your specialty and role.

Hide properties

SukiAmbientConstant.kSpeciality

string

The provider’s medical specialty (e.g., “FAMILY_MEDICINE”, “CARDIOLOGY”). This helps format notes according to your specialty’s conventions.

SukiAmbientConstant.kProviderRole

string

The provider’s role in the encounter. Valid values: “Primary/Attending” or “Consulting”. This helps distinguish between primary care providers and consulting specialists.

Visit context

SukiAmbientConstant.kVisitContext

dictionary

Use this parameter to provide visit-related metadata that provides context about the type and purpose of the encounter.

Hide properties

SukiAmbientConstant.kVisitType

string

The type of patient visit. Valid values: “New Patient / Intake”, “Established patient”, “Wellness”, “ED”. This helps format notes appropriately for the visit type.

SukiAmbientConstant.kEncounterType

string

The setting where the encounter occurs. Valid values: “ambulatory”, “inpatient”, “ED”. This helps structure notes for the appropriate care setting.

SukiAmbientConstant.kReasonForVisit

string

A free-text description explaining why the patient is visiting. Maximum 255 characters. This helps focus the note on the primary reason for the visit.

SukiAmbientConstant.kChiefComplaint

string

The patient’s primary complaint or concern. Maximum 255 characters. This helps structure the note’s chief complaint section.

EMR info

SukiAmbientConstant.kEmrInfo

dictionary

Use this parameter to identify which EMR applies to an ambient session. Provide a string identifier that matches what your integration and Suki use for that EMR (for example a vendor code or environment-specific label).

Hide properties

SukiAmbientConstant.kTargetEmr

string

required

The target EMR for this encounter. Provide a string identifier that matches what your integration and Suki use for that EMR (for example a vendor code or environment-specific label).

SukiAmbientConstant.kSections

array of dictionaries

An array of LOINC codes that specify which clinical note sections you want in the generated note. Each dictionary contains a LOINC code.

You only need to provide LOINC codes. The SDK automatically generates the appropriate clinical section titles based on the codes you provide.

Code example:

Swift

SukiAmbientConstant.kSections: [
    [SukiAmbientConstant.kCode: "51848-0", SukiAmbientConstant.kCodeType: "loinc"],
    [SukiAmbientConstant.kCode: "11450-4", SukiAmbientConstant.kCodeType: "loinc"]
]

Diagnosis info

SukiAmbientConstant.kDiagnosisInfo

array of dictionaries

Structured diagnosis information that helps the AI identify and code conditions discussed during the encounter. Each dictionary represents one diagnosis.

Hide properties

SukiAmbientConstant.kDiagnosisNote

string

A text note describing the diagnosis or condition.

SukiAmbientConstant.kCodes

array of dictionaries

An array of diagnosis codes. Each code dictionary must contain:

Hide code properties

SukiAmbientConstant.kCodeType

string

required

The coding system used (e.g., “ICD-10”, “IMO”, “SNOMED”).

SukiAmbientConstant.kCode

string

required

The actual diagnosis code.

SukiAmbientConstant.kCodeDescription

string

A human-readable description of what the code represents. Recommended for clarity.

Orders info

SukiAmbientConstant.kOrdersInfo

dictionary

Use this parameter to provide information about medications relevant to a patient visit, such as existing prescriptions or the patient’s current medication list.The data is structured as a single bundle. On the wire, the outer payload key is orders. Inside this bundle, you must include a single list keyed by MedicationOrderKeys.kMedicationOrders (wire string medication_orders). Each entry in this list represents a single medication order and must be formatted as an individual dictionary.You can skip kOrdersInfo entirely if it is not required for your workflow. If you do send the MedicationOrderKeys.kMedicationOrders list, each order in that list must satisfy the following requirements.

Missing information or incomplete metadata fails with invalidMedicationOrder. If you include origin or encounter_relation under metadata, each value must be non-empty and match one of the allowed choices. Values that do not match can fail parsing with invalidOrderMetadata.

Payload keysYou must include the following payload (wire) keys for every order in the MedicationOrderKeys.kMedicationOrders array:

medication_code: You must include both code_type and code.
linked_diagnosis_codes: You must include at least one item containing both code_type and code.
metadata.origin and metadata.encounter_relation: You must use only the approved values for these fields.

When you use optional fields that carry codes (medication_code.code_type, dosage.unit, frequency, medication_timing, status), the SDK checks them against its own supported lists. Use only values that your SDK already accepts to avoid validation errors.

Code example:

Swift

SukiAmbientConstant.kOrdersInfo: [
    MedicationOrderKeys.kMedicationOrders: [
        [
            MedicationOrderKeys.kDrugName: "Atorvastatin", // required
            MedicationOrderKeys.kMedicationCode: [
                SukiAmbientConstant.kCodeType: "<code_type>", // required
                SukiAmbientConstant.kCode: "<code>" // required
            ],
            MedicationOrderKeys.kStrength: "10 mg", // required
            MedicationOrderKeys.kFormat: "tablet", // required
            MedicationOrderKeys.kRoute: "oral", // required
            MedicationOrderKeys.kLinkedDiagnosisCodes: [
                [SukiAmbientConstant.kCodeType: "ICD-10", SukiAmbientConstant.kCode: "E78.5"]
            ],
            MedicationOrderKeys.kMetadata: [
                MedicationOrderKeys.kOrigin: "EMR",
                MedicationOrderKeys.kEncounterRelation: "CURRENT_ENCOUNTER"
            ]
        ]
    ]
]

Hide properties

Each object in the MedicationOrderKeys.kMedicationOrders array can include the following. The payload keys checklist above defines the minimum; the ResponseField entries use Swift constant names for the same rules.

MedicationOrderKeys.kDrugName

string

required

The medication name. Required when this order is included in the array.

MedicationOrderKeys.kMedicationCode

dictionary

required

The coded medication identifier. Required when this order is included.

Hide medication_code properties

SukiAmbientConstant.kCodeType

string

required

The coding system for the medication code. Required for validation. Must match a supported catalog when you send a coded value.

SukiAmbientConstant.kCode

string

required

The medication code. Required for validation. Must match a supported catalog when you send a coded value.

MedicationOrderKeys.kStrength

string

required

The medication strength (for example dosage amount with unit). Required when this order is included.

MedicationOrderKeys.kFormat

string

required

The dose form (for example tablet, capsule). Required when this order is included.

MedicationOrderKeys.kRoute

string

required

The route of administration. Required when this order is included.

MedicationOrderKeys.kDosage

dictionary

Optional structured dosage information.

Show dosage properties

MedicationOrderKeys.kRawValue

string

Free-text dosage as entered in your system.

MedicationOrderKeys.kQuantity

number

Numeric quantity for the dose.

MedicationOrderKeys.kUnit

string

Unit for the quantity. When used as a coded field, must match a supported catalog.

MedicationOrderKeys.kFrequency

dictionary

Optional dosing frequency. Uses the same inner keys as MedicationOrderKeys.kMedicationTiming.

Show frequency properties

MedicationOrderKeys.kRawValue

string

Free-text frequency.

MedicationOrderKeys.kStructuredValue

string

Structured frequency value. When used as a coded field, must match a supported catalog.

MedicationOrderKeys.kQuantityDispensed

string

Quantity dispensed.

MedicationOrderKeys.kNumberOfRefills

integer

Number of refills.

MedicationOrderKeys.kStartDate

date

Start date for the order when you supply it through context bridging.

MedicationOrderKeys.kEndDate

date

End date for the order.

MedicationOrderKeys.kDurationInDays

integer

Duration of therapy in days.

MedicationOrderKeys.kInstructions

string

Patient- or pharmacy-facing instructions.

MedicationOrderKeys.kMedicationTiming

dictionary

Optional timing details for the medication. Same shape as MedicationOrderKeys.kFrequency.

Show medication_timing properties

MedicationOrderKeys.kRawValue

string

Free-text timing.

MedicationOrderKeys.kStructuredValue

string

Structured timing value. When used as a coded field, must match a supported catalog.

MedicationOrderKeys.kLinkedDiagnosisCodes

array of dictionaries

required

Required for validation: at least one object. Each array element uses code_type and code (SukiAmbientConstant.kCodeType and SukiAmbientConstant.kCode in Swift).

Hide code properties

SukiAmbientConstant.kCodeType

string

required

The coding system for the diagnosis (for example “ICD-10”). Must match a supported catalog when you send a coded value.

SukiAmbientConstant.kCode

string

required

The diagnosis code. Must match a supported catalog when you send a coded value.

MedicationOrderKeys.kStatus

string

Order status. When used as a coded field, must match a supported catalog.

MedicationOrderKeys.kMetadata

dictionary

required

Provenance for the order. Required when this order is included. You must set both origin and encounter_relation under metadata (use MedicationOrderKeys.kOrigin and MedicationOrderKeys.kEncounterRelation in Swift). Each value must be non-empty after trim and must be one of the allowed strings below.

Hide metadata properties

MedicationOrderKeys.kOrigin

string

required

Payload key origin. Where the order came from. Valid values: SUKI_AMBIENT, EMR.

MedicationOrderKeys.kEncounterRelation

string

Payload key encounter_relation. How the order relates to the encounter. Valid values: PRIOR_ENCOUNTER, CURRENT_ENCOUNTER.

This field is required if the origin is EMR.

Best practices

Follow these practices to ensure reliable session management:

Always initialize the SDK first: Make sure SukiAmbientCore.shared.initialize() has been called successfully before creating a session.
Store the session ID: Save the sessionId returned from createSession immediately. You’ll need it for all subsequent operations.
Handle errors properly: Use the completion handler’s result to check for success or failure. Display appropriate error messages to users.
Provide context when available: Call setSessionContext with any clinical information you have. Even partial context improves note quality.
Medication orders: If you send MedicationOrderKeys.kMedicationOrders under kOrdersInfo, include every required field per order and valid metadata values, or the SDK can reject the update.
Call setSessionContext after createSession: Wait for createSession to succeed before calling setSessionContext.
Handle background limitations: On iOS, you cannot start a recording while the app is in the background. Ensure your app is active before starting a recording.

FAQs

Why is session creation failing?

Session creation can fail for several reasons:Common causes:

SDK not initialized: Make sure you’ve called initialize() before creating a session
Invalid partner information: Check that your partner ID and provider information are correct
Network connectivity issues: Ensure the device has an active internet connection
Authentication token problems: Verify your token provider is returning valid tokens
Missing microphone permissions: Ensure your app has microphone access permissions

How to debug: Check the error returned in the completion handler’s .failure case. The error will indicate the specific reason for failure.

Why isn't my session context updating?

The session context may not update if:

Session not created: You must call createSession first and wait for it to succeed
Method not called: Ensure you’re actually calling setSessionContext after session creation
Invalid parameters: Check that specialty strings and codes match the expected formats. For medication orders, confirm every required field per order, valid metadata values, and at least one linked diagnosis code object
Network error: The update request may have failed due to connectivity issues

How to verify: Check the completion handler result. If it returns .failure, examine the error to understand what went wrong.

Can I start recording immediately after creating a session?

Yes, once createSession succeeds and returns a sessionId, you can start recording. However, it’s recommended to call setSessionContext first if you have clinical context available, as this improves note quality.The typical flow is:

Create session → Get sessionId
Set session context (optional but recommended)
Start recording

Next steps

After you create a session and optionally set context, proceed to the Recording controls guide to learn how to start recording and manage the recording lifecycle.

Get Started

Mobile SDK Guides

FAQs

Provide Additional Clinical Context

Overview

Set session context (optional but recommended)

Additional context parameters

Patient info

Provider context

Visit context

EMR info

Diagnosis info

Orders info

Best practices

FAQs

Next steps

Get Started

Mobile SDK Guides

FAQs

​Overview

​Set session context (optional but recommended)

​Additional context parameters

​Patient info

​Provider context

​Visit context

​EMR info

​Diagnosis info

​Orders info

​Best practices

​FAQs

​Next steps

Overview

Set session context (optional but recommended)

Additional context parameters

Patient info

Provider context

Visit context

EMR info

Diagnosis info

Orders info

Best practices

FAQs

Next steps