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

# 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">July 2026</span>
  </div>
</div>

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

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

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