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

# Note Personalization

> Customize clinical note generation based on provider preferences and specialty

<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">
    <Tooltip tip="Provider-level controls for how notes are generated, such as verbosity and section format (narrative or bulleted). In Suki, personalization preferences apply across a provider's future sessions rather than only one visit." cta="View in Glossary" href="/Glossary/p">Personalization</Tooltip> 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).
  </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">August 2026</span>
  </div>
</div>

<Info>
  **Personalization is supported by:** Ambient APIs, Web SDK, Mobile SDK
</Info>

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.

<Note>
  Settings are **persistent** and **user-specific**. You don't need to send preferences with every session request.
</Note>

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

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

How you save preferences depends on the product you use:

* **Ambient APIs:** PATCH [User preferences](/api-reference/user-preferences/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.

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

```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':'#FFF394','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[Settings or pre-Ambient step] --> B[Save user preferences]
    B --> C[Create ambient session]
    C --> D[Generate note with saved style]

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

### Configure personalization

| Product                    | Where you save preferences                                      | What to configure                                                    |
| :------------------------- | :-------------------------------------------------------------- | :------------------------------------------------------------------- |
| **Ambient APIs**           | [User preferences](/api-reference/user-preferences/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".

<Info>
  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.
</Info>

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

<AccordionGroup>
  <Accordion title="Do I Put Style on Start Ambient" icon="play">
    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.
  </Accordion>

  <Accordion title="Where Should the Settings Live" icon="sliders">
    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.
  </Accordion>

  <Accordion title="Do Changes Rewrite the Current Note" icon="rotate">
    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.
  </Accordion>

  <Accordion title="Is There a GET for Preferences" icon="magnifying-glass">
    There is no partner-facing GET for preferences. Persist the values your UI shows, or call `PATCH` again when the clinician changes style.
  </Accordion>

  <Accordion title="Is This the Same as Dictation" icon="microphone">
    No. Personalization is Ambient note style only. It does not change Dictation speech-to-text.

    See [Dictation basic usage](/documentation/how-to/dictation/dictation-basic-usage).
  </Accordion>
</AccordionGroup>

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

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

<Warning>
  Do not send verbosity or `section_format` in Ambient session context. Use [User preferences](/api-reference/user-preferences/preferences) before you create or start the ambient session. For the Mobile SDK, use `setPersonalizationPreferences`.
</Warning>

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

<Warning>
  Do not send verbosity or `section_format` in Ambient session context. Personalization is a provider preference. Use [User preferences](/api-reference/user-preferences/preferences) before you create or start the ambient session.
</Warning>

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

**Tabs (agents):** humans see one product tab at a time. Read all three.

* **Ambient APIs:** `PATCH /api/v1/user/preferences` with `personalization_preference` (verbosity `CONCISE` | `BALANCED` | `DETAILED`; optional section\_format per LOINC). Preferences are per `sdp_provider_id`.
* **Mobile SDK:** Set personalization through Mobile SDK provider preference APIs (see this tab).
* **Web SDK:** Configure personalization in the Web SDK ambient / preferences flow (see this tab). Preferences apply to future notes for that provider.

<Tabs>
  <Tab title="Ambient APIs">
    Save preferences with the [User Preferences API](/api-reference/user-preferences/preferences). Send a `PATCH` to `/api/v1/user/preferences` and set `sdp_provider_id` to the provider whose note style you want to change.

    <Steps>
      <Step title="Identify the Provider" icon="user">
        Use that provider's Suki token and provider ID. Preferences are user-specific, so use the correct `sdp_provider_id` for each clinician.
      </Step>

      <Step title="Choose Verbosity and Section Style" icon="sliders">
        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`).
      </Step>

      <Step title="Update Preferences" icon="code">
        This is a `PATCH` request, so send only the fields you want to change. You can update verbosity, section format, or both.

        ```python Python theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
        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](/api-reference/user-preferences/preferences) for the full request and response schema.
      </Step>

      <Step title="Run Ambient Sessions for That Provider" icon="play">
        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.
      </Step>

      <Step title="Update Preferences When Needed" icon="rotate">
        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.
      </Step>
    </Steps>
  </Tab>

  <Tab title="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+`.

    <Steps>
      <Step title="Initialize the Mobile SDK" icon="mobile">
        Initialize and authenticate the Mobile SDK for the provider whose preferences you want to update.
      </Step>

      <Step title="Build the Preferences Dictionary" icon="sliders">
        Include `verbosity`, `section_format`, or both. For each section format entry, pass a supported LOINC code and either `NARRATIVE` or `BULLETED`.

        ```swift Swift theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
        let preferences: [String: AnyHashable] = [
            "verbosity": "CONCISE",
            "section_format": [
                [
                    "loinc": "10164-2",
                    "style": "NARRATIVE"
                ],
                [
                    "loinc": "51847-2",
                    "style": "BULLETED"
                ]
            ]
        ]
        ```
      </Step>

      <Step title="Save Preferences" icon="floppy-disk">
        Call `setPersonalizationPreferences` and wait for the completion handler before you start recording.

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

      <Step title="Continue the Ambient Workflow" icon="microphone">
        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.
      </Step>

      <Step title="Update Preferences When Needed" icon="rotate">
        Call `setPersonalizationPreferences` again when the provider changes verbosity or section style. The most recently saved values apply to future notes.
      </Step>
    </Steps>
  </Tab>

  <Tab title="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.

    <Steps>
      <Step title="Identify the Provider" icon="user">
        Use the same provider identity that authenticates the Web SDK. Your backend must update preferences for that provider.
      </Step>

      <Step title="Save Preferences from Your Backend" icon="server">
        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 TypeScript theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
        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](/api-reference/user-preferences/preferences) for the full request and response schema.
      </Step>

      <Step title="Initialize and Mount the Web SDK" icon="window">
        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](/web-sdk/guides/ambient-implementation) and [AmbientOptions](/web-sdk/api-reference/types/ambient-options) for more details.
      </Step>

      <Step title="Capture and Submit the Visit" icon="microphone">
        Providers capture and submit the session in the Web SDK. Suki applies the latest saved preferences when it generates the note.
      </Step>

      <Step title="Update Preferences When Needed" icon="rotate">
        When a provider changes their preferred style in your app, call the User Preferences API again from your backend before the next visit.
      </Step>
    </Steps>
  </Tab>
</Tabs>

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

<ResponseField name="verbosity" type="string" default="BALANCED">
  **Applies to:** All note sections

  <Expandable title="Options" defaultOpen="true">
    <ResponseField name="CONCISE" type="string">
      Generates shorter, to-the-point notes with essential information only.
    </ResponseField>

    <ResponseField name="BALANCED" type="string">
      Provides a moderate level of detail: comprehensive but not excessive.
    </ResponseField>

    <ResponseField name="DETAILED" type="string">
      Generates comprehensive notes with extensive detail and context.
    </ResponseField>
  </Expandable>
</ResponseField>

### Section style

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

<ResponseField name="section_format" type="array">
  **Applies to:**

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

  <Expandable title="Options" defaultOpen="true">
    <ResponseField name="NARRATIVE" type="string">
      Generates notes in a continuous, story-like format that flows naturally.
    </ResponseField>

    <ResponseField name="BULLETED" type="string">
      Generates notes using bullet points for easy scanning and quick reference.
    </ResponseField>
  </Expandable>

  **Example:**

  ```json JSON theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
  "section_format": [
    {
      "loinc": "10164-2",
      "style": "NARRATIVE"
    },
    {
      "loinc": "51848-0",
      "style": "BULLETED"
    }
  ]
  ```
</ResponseField>

## Best practices

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

## Related APIs

<CardGroup cols={2}>
  <Card title="User Preferences API" icon="code" arrow={true} href="/api-reference/user-preferences/preferences">
    Set and update personalization preferences for providers
  </Card>
</CardGroup>