Personalization

Quick summary

allows you to customize how Suki generates clinical notes based on each provider’s preferences. Control how much detail (short and concise, balanced, or very detailed) and how it’s formatted (continuous paragraphs or bullet points).

Last updated:July 2026

Personalization is supported by: APIs, Web SDK, Mobile SDK

Personalization allows you to help providers customize how Suki generates their clinical notes. Every provider has different preferences, some want short bullet points, others want detailed paragraphs. Personalization ensures each provider gets notes that match their style. When you use personalization, you can customize two aspects of note generation:

How much detail: Short and concise, balanced, or very detailed notes
How it’s formatted: Continuous paragraphs (narrative) or bullet points

Once you set a provider’s preferences, Suki automatically applies them to all future notes for that provider. You set it once, and Suki remembers, no need to send preferences with every request. Using personalization, you get the following benefits:

Provider satisfaction: Notes match each provider’s preferred style and level of detail
Consistent documentation: Once set, preferences apply automatically to all future notes
Efficiency: Providers don’t need to manually adjust notes; they’re generated according to their preferences
Flexibility: Different providers can have different preferences based on their specialty and workflow
Better adoption: When notes match provider preferences, they’re more likely to use and trust the system

How Personalization improves clinical documentation

Personalization reduces post-generation editing by aligning note style with how each provider already documents. This helps clinicians trust the generated notes and reduces the need for manual edits before signing.

What you configure	How the note gets better
Verbosity (`CONCISE`, `BALANCED`, or `DETAILED`)	Notes have the right amount of detail for that provider
Section format (`NARRATIVE` or `BULLETED`)	Sections match the reading style the provider expects
Persistent provider preferences	Future notes stay consistent without sending settings on every session

When notes match provider preference, clinicians usually make fewer style edits before sign. That improves trust and adoption, and it shortens the path from generated note to final documentation.

How Personalization works

Settings are saved at the user level (not per session) and applied to all future note generation for that provider. The process:

Set preferences: Use the Mobile SDK setPersonalizationPreferences method or the User Preferences API to configure a provider’s preferences
Automatic application: Suki applies these settings to all future notes for that provider
Update anytime: Update preferences at any time; the most recent settings always take effect

Settings are persistent and user-specific. You don’t need to send preferences with every session request.

How to set Personalization preferences

Personalization is saved for the provider, not for one ambient session. Set preferences before the visit starts. Suki uses the latest saved values for that provider’s future notes. Click the tabs below to see the implementation details for your integration path.

Ambient APIs
Mobile SDK
Web SDK

Save preferences with the User Preferences API. Send a PATCH to /api/v1/user/preferences and set sdp_provider_id to the provider whose note style you want to change.

Identify the Provider

Use that provider’s Suki token and provider ID. Preferences are user-specific, so use the correct sdp_provider_id for each clinician.

Choose Verbosity and Section Style

Set verbosity to CONCISE, BALANCED, or DETAILED. Optionally set section format to NARRATIVE or BULLETED for supported LOINC sections: History of Present Illness (10164-2), Assessment and Plan (51847-2), Assessment (51848-0), and Plan (18776-5).

Update Preferences

This is a PATCH request, so send only the fields you want to change. You can update verbosity, section format, or both.

Python

import requests

response = requests.patch(
    "https://sdp.suki.ai/api/v1/user/preferences",
    headers={
        "sdp_suki_token": "<sdp_suki_token>",
        "sdp_provider_id": "<sdp_provider_id>",
        "Content-Type": "application/json",
    },
    json={
        "personalization_preference": {
            "verbosity": "CONCISE",
            "section_format": [
                {
                    "loinc": "10164-2",
                    "style": "NARRATIVE",
                }
            ],
        }
    },
)

if response.status_code == 200:
    print("Preferences updated successfully")
    print(response.json())
else:
    print(f"Failed to update preferences: {response.status_code}")
    print(response.json())

Refer to User Preferences for the full request and response schema.

Run Ambient Sessions for That Provider

After the update succeeds, create ambient sessions as usual for the same provider. You do not send personalization fields in session context. Suki applies the saved preferences when it generates the note.

Update Preferences When Needed

When a provider changes their preferred style, call the same PATCH endpoint again before the next visit. The most recent values apply to future notes.

Call setPersonalizationPreferences after you initialize the Mobile SDK. Preferences are saved for the signed-in provider and apply to future notes. Requires Mobile SDK v2.3.0+.

Initialize the Mobile SDK

Initialize and authenticate the Mobile SDK for the provider whose preferences you want to update.

Build the Preferences Dictionary

Include verbosity, section_format, or both. For each section format entry, pass a supported LOINC code and either NARRATIVE or BULLETED.

Swift

let preferences: [String: AnyHashable] = [
    "verbosity": "CONCISE",
    "section_format": [
        [
            "loinc": "10164-2",
            "style": "NARRATIVE"
        ],
        [
            "loinc": "51847-2",
            "style": "BULLETED"
        ]
    ]
]

Save Preferences

Call setPersonalizationPreferences and wait for the completion handler before you start recording.

Swift

SukiAmbientCoreManager.shared.setPersonalizationPreferences(preferences) { result in
    switch result {
    case .success:
        print("Preferences updated successfully")
    case .failure(let error):
        print("Error updating preferences: \(error)")
    }
}

Do not pass a nil or empty preferences dictionary. The SDK returns invalidPreferences for that input.

Continue the Ambient Workflow

Create the session, set clinical context, record, and end the session as usual. Do not add personalization fields to setSessionContext(with:). The SDK uses the saved preferences for future note generation.

Update Preferences When Needed

Call setPersonalizationPreferences again when the provider changes verbosity or section style. The most recently saved values apply to future notes.

The Web SDK does not take personalization fields in ambientOptions. Save preferences from your backend with the User Preferences API for the same provider, then run the Web SDK ambient workflow as usual.

Identify the Provider

Use the same provider identity that authenticates the Web SDK. Your backend must update preferences for that provider.

Save Preferences from Your Backend

Call PATCH /api/v1/user/preferences from your backend with the provider’s Suki token and sdp_provider_id. Keep API credentials on the server, not in browser code.

TypeScript

const response = await fetch(
  "https://sdp.suki.ai/api/v1/user/preferences",
  {
    method: "PATCH",
    headers: {
      "Content-Type": "application/json",
      "sdp_suki_token": "<sdp_suki_token>",
      "sdp_provider_id": "<sdp_provider_id>",
    },
    body: JSON.stringify({
      personalization_preference: {
        verbosity: "CONCISE",
        section_format: [
          {
            loinc: "10164-2",
            style: "NARRATIVE",
          },
        ],
      },
    }),
  },
);

if (response.ok) {
  const data = await response.json();
  console.log("Preferences updated successfully", data);
} else {
  const error = await response.json();
  console.error(`Failed to update preferences: ${response.status}`, error);
}

Refer to User Preferences for the full request and response schema.

Initialize and Mount the Web SDK

After preferences are saved, initialize and mount the Web SDK for that provider. Configure note sections in ambientOptions.sections as usual. Do not add verbosity or section-format fields to ambientOptions.Refer to Ambient implementation and AmbientOptions for more details.

Capture and Submit the Visit

Providers capture and submit the session in the Web SDK. Suki applies the latest saved preferences when it generates the note.

Update Preferences When Needed

When a provider changes their preferred style in your app, call the User Preferences API again from your backend before the next visit.

Personalization options

With Personalization, you can customize two aspects of note generation: verbosity and section style.

Verbosity

Verbosity controls how much detail is included in the generated note. This setting applies to all note sections.

string

default:"BALANCED"

Applies to: All note sections

Hide Options

string

Generates shorter, to-the-point notes with essential information only.

string

Provides a moderate level of detail: comprehensive but not excessive.

string

Generates comprehensive notes with extensive detail and context.

Section style

Section style lets you control the formatting style for specific clinical sections. Set different styles for different sections as needed.

array

Applies to:

History of Present Illness (10164-2)
Assessment and Plan (51847-2)
Assessment (51848-0)
Plan (18776-5)

Hide Options

string

Generates notes in a continuous, story-like format that flows naturally.

string

Generates notes using bullet points for easy scanning and quick reference.

Example:

JSON

"section_format": [
  {
    "loinc": "10164-2",
    "style": "NARRATIVE"
  },
  {
    "loinc": "51848-0",
    "style": "BULLETED"
  }
]

Best practices

Set defaults early: Configure preferences when providers are first registered in your system
Offer a UI: Let providers choose their preferences through your application’s settings page
Explain options: Help providers understand the difference between verbosity levels and style options
Update when requested: Make it easy for providers to change their preferences as their needs evolve
Test with real notes: Verify that preferences produce notes that match provider expectations

User Preferences API

Set and update personalization preferences for providers

Get Started

Concepts & Feature Guides

Tutorials

Resources

FAQs & Support

Personalization

How Personalization improves clinical documentation

How Personalization works

How to set Personalization preferences

Personalization options

Verbosity

Section style

Best practices

User Preferences API

​How Personalization improves clinical documentation

​How Personalization works

​How to set Personalization preferences

​Personalization options

​Verbosity

​Section style

​Best practices

​Related APIs

User Preferences API

How Personalization improves clinical documentation

How Personalization works

How to set Personalization preferences

Personalization options

Verbosity

Section style

Best practices

Related APIs