Note Personalization

Customize clinical note generation based on provider preferences and specialty

Quick summary

Personalization 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:August 2026

Personalization is supported by: Ambient 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:

1. Set preferences: Use the Mobile SDK setPersonalizationPreferences method or the User Preferences API to configure a provider’s preferences.
2. Automatic application: Suki applies these settings to all future notes for that provider.
3. 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.

Build personalization into your product

If you are deciding to build personalization into your product, you need to understand how and when to use it. Personalization lets each clinician choose how detailed Ambient notes are (CONCISE, BALANCED, or DETAILED), and optionally whether supported sections use narrative or bulleted style.

Do not put verbosity or section_format on the Start Ambient payload or in session context. Personalization belongs in provider settings, not on Ambient create.

How you save preferences depends on the product you use:

• Ambient APIs: PATCH User preferences for that sdp_provider_id before Ambient create when the clinician saves.
• Web SDK: Save preferences from your backend with the User Preferences API for the same provider. Do not put personalization fields in ambientOptions.
• Mobile SDK (v2.3.0+): Call setPersonalizationPreferences after you initialize the SDK for that provider.

Preferences are per clinician, not per visit. Suki applies the latest saved values to future Ambient notes for that provider.

Personalization applies to Ambient note style only. It does not change Dictation transcripts. If you never set preferences, verbosity defaults to BALANCED. Notes still generate. Section format is optional.

Configure personalization

Product	Where you save preferences	What to configure
Ambient APIs	User preferences	verbosity and optional section_format for that sdp_provider_id
Web SDK	User Preferences API from your backend	Same fields. Do not add personalization to ambientOptions
Mobile SDK (v2.3.0+)	setPersonalizationPreferences	Same fields for the signed-in provider

Recommended UI patterns

Put Documentation style in provider settings, or as a short pre-Ambient step. Use plain-language labels such as “Shorter notes” / “Balanced” / “More detail”.

These patterns apply when you build your own ambient experience with the Ambient APIs or the Headless modalities. The headed Web SDK already provides Ambient UI, so you do not recreate these patterns there.

Before the visit

Save preferences before Ambient create when the clinician chooses a style. Tell them updates apply to future notes.

During Ambient

Run create, context, stream, and End as usual. You do not send verbosity or section_format with the ambient session.

After a note feels wrong

Save preferences again, then run a new Ambient session. The current note does not rewrite itself.

Do I Put Style on Start Ambient

No. Do not put verbosity or section_format on the Start Ambient payload or in session context.

Save preferences with User Preferences (or Mobile SDK setPersonalizationPreferences), then run Ambient as usual.

Where Should the Settings Live

Provider settings is the recommended place. A short pre-Ambient confirmation step also works.

Show Concise / Balanced / Detailed. Optionally Narrative / Bulleted for supported LOINC sections.

Do Changes Rewrite the Current Note

No. Suki applies the latest saved values to future notes for that provider.

If the clinician changes verbosity or section format while an ambient session is already in progress, this recording does not restyle. Show UI copy such as Applies to future notes. After they change style, run a new Ambient session for the new preference to show up.

Is There a GET for Preferences

There is no partner-facing GET for preferences. Persist the values your UI shows, or call PATCH again when the clinician changes style.

Is This the Same as Dictation

No. Personalization is Ambient note style only. It does not change Dictation speech-to-text.

See Dictation basic usage.

Verbosity, section format, and when preferences apply

When you build personalization into your app, keep the following concepts separate. They look related, but serve different purposes.

Concept	What it is	What you do in your app
Verbosity	How detailed the whole Ambient note is for that provider	Offer Concise / Balanced / Detailed. Save with User Preferences or Mobile SDK. Default is BALANCED if you never set it.
Section format	Narrative or bulleted style on supported sections only	Optional. Use only for HPI (10164-2), Assessment and Plan (51847-2), Assessment (51848-0), and Plan (18776-5).
When preferences apply	Latest saved values for that clinician	Apply to future Ambient notes. Do not expect the note already on screen to rewrite itself.

What to wire in your product

1. Build a Documentation style settings experience (or a short pre-Ambient step).
2. Save with User Preferences (or Mobile SDK) for that provider before Ambient create when the clinician saves.
3. Run Ambient as usual. Show messaging that updates apply to future notes.

Personalization is per clinician. Set it once in settings, then Ambient uses the saved style on future notes for that provider.

Do not send verbosity or section_format in Ambient session context. Use User preferences before you create or start the ambient session. For the Mobile SDK, use setPersonalizationPreferences.

How to set personalization preferences

Personalization controls how detailed the Ambient note is, and whether selected sections use narrative or bulleted style. Preferences are saved per clinician, not per visit.

When to set them: Before the visit starts, ideally when you register the provider or from a settings screen before Ambient create. Suki applies the latest saved values to future notes for that provider.

Default if you never call the API: Verbosity is BALANCED. Notes still generate. Section format is optional.

Do not send verbosity or section_format in Ambient session context. Personalization is a provider preference. Use User preferences before you create or start the ambient session.

Click the tabs below to see the implementation details for your integration path.

Ambient APIs

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.

1. 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.

2. 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).

3. 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.

4. 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.

5. 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.

Mobile SDK

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+.

1. Initialize the Mobile SDK

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

2. 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"
           ]
       ]
   ]
   
3. 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.

4. 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.

5. Update Preferences When Needed

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

Web SDK

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.

1. Identify the Provider

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

2. 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.

3. 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.

4. 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.

5. 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.

verbosity · string · default: "BALANCED"

Applies to: All note sections

Hide Options

CONCISE · string

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

BALANCED · string

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

DETAILED · 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.

section_format · array

Applies to:

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

Hide Options

NARRATIVE · string

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

BULLETED · 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. If you skip this step, notes still generate with BALANCED verbosity.
• Change before ambient starts: Save preferences before create or start. Tell clinicians that updates apply to future notes, not to a recording that is already in progress.
• Label in plain language: Use clinician-facing labels such as “Shorter notes” / “Balanced” / “More detail”. Keep Dictation separate. Personalization does not change Dictation speech-to-text.
• Limit section format: Send section_format only for History of Present Illness (10164-2), Assessment and Plan (51847-2), Assessment (51848-0), and Plan (18776-5). Invalid LOINC or style values return an error.

Related APIs

User Preferences API

Set and update personalization preferences for providers