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

# Problem-Based Charting

> Problem-based clinical documentation approach with diagnosis context integration

<Callout title="Updates" color="orange" icon="bell">
  **Updated**

  * Structured data output now includes **HCC** codes alongside ICD10, IMO, and SNOMED for each suggested diagnosis.
  * For how the system reconciles those diagnoses with the conversation (API flow), refer to [Reconciliation](/api-reference/capabilities/problem-based-charting#reconciliation). For Web SDK implementation details, refer to [Existing patient diagnoses](/web-sdk/guides/ambient-problem-based-charting#existing-patient-diagnoses).
</Callout>

<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">
    Problem-Based Charting (PBC) is a clinical documentation approach that organizes notes by patient problems instead of traditional note sections, and suggests diagnoses for each problem.
  </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">June 2026</span>
  </div>
</div>

<Info>
  **Problem-Based Charting is supported by:** Ambient APIs, Web SDK, Mobile SDK
</Info>

Problem-Based Charting (PBC) organizes clinical notes by patient problems instead of traditional note sections. When you use PBC, Suki generates two things:

1. **Clinical note**: Organized by each problem or diagnosis
2. **Structured artifacts**: Suggested diagnoses with ICD10, IMO, SNOMED, and HCC codes

PBC notes are different from traditional notes. In traditional notes, information is organized by sections like "History," "Assessment," and "Plan." In PBC notes, information is organized by each problem, grouping all related information together.

When you enable PBC, providers get a note that has the following benefits:

* **Easier to read**: See everything about each problem in one place
* **Better continuity**: Includes existing problems from previous visits automatically
* **Complete picture**: Captures both old and new problems discussed during the visit
* **Structured data**: Generates standardized codes (ICD10, IMO, SNOMED, and HCC) for EHR integration

## How to use PBC for APIs and SDKs

You enable PBC by doing three things:

* Define which note sections to generate and which one is the PBN
* Pass the patient's existing diagnoses into session context
* Read structured diagnosis output after the session finishes

<Tabs>
  <Tab title="Configure sections for PBC">
    - **Web SDK:** In `ambientOptions.sections`, set `isPBNSection: true` on **exactly one** section. Rules for defaults, overrides, and errors are in [Configuration rules](/api-reference/capabilities/problem-based-charting#configuration-rules-for-pbc).
    - **Ambient APIs:** Send the LOINC `sections` array in the [Context API](/api-reference/ambient-sessions/context) body so the Suki backend knows which note sections to generate. PBN defaults (for example, when Assessment & Plan, LOINC `51847-2`, is treated as the PBN) follow the same rules as in [Configuration rules](/api-reference/capabilities/problem-based-charting#configuration-rules-for-pbc).
    - **Mobile SDK (iOS):** Pass LOINC sections in `kSections` via `setSessionContext`. See the Mobile SDK [Create session](/mobile-sdk/ambient-guides/create-session#provide-clinical-context-optional-but-recommended) guide for field names and examples.
  </Tab>

  <Tab title="Provide existing diagnoses">
    * **Ambient APIs:** Include diagnoses when you POST (and, if needed, PATCH) session context.
    * **Web SDK:** Use `ambientOptions.diagnoses`. Refer to the [AmbientOptions type](/web-sdk/api-reference/types/ambient-options) for more details.
    * **Mobile SDK (iOS):** Use `SukiAmbientConstant.kDiagnosisInfo` in `setSessionContext`. Refer to the Mobile SDK [Create session](/mobile-sdk/ambient-guides/create-session#provide-clinical-context-optional-but-recommended) guide for more details.
  </Tab>

  <Tab title="Retrieve diagnosis results">
    * **Ambient APIs:** After the session has finished processing, use the [Structured Data](/api-reference/ambient-content/structured-data) or [Encounter Structured Data](/api-reference/ambient-content/encounter-structured-data) APIs and related endpoints to read suggested diagnoses.
    * **Mobile SDK (iOS):** After the session completes, call `getStructuredData(for:)`. See [Session status and content retrieval](/mobile-sdk/ambient-guides/session-status-and-content-retrieval#get-structured-data).
    * **Web SDK:** After the user submits the ambient session and note generation succeeds, read results from the **`onNoteSubmit`** callback (React) or the **`note-submission:success`** event (JavaScript and React). Refer to [Receiving note content](/web-sdk/guides/note-management#receiving-note-content), [Response structure](/web-sdk/guides/note-management#response-structure), [NoteContent](/web-sdk/api-reference/types/note-content), and [Diagnosis](/web-sdk/api-reference/types/diagnosis) for more details.
  </Tab>
</Tabs>

## Implementation examples

<Tabs>
  <Tab title="Web SDK">
    Use the `diagnoses` block in `ambientOptions` to provide existing patient diagnoses when starting a session.

    **Code example:**

    ```javascript JavaScript theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
    sdkClient.mount({
      rootElement: document.getElementById("suki-root"),
      encounter: encounterDetails,
      ambientOptions: {
        sections: [
          { loinc: "51848-0", isPBNSection: true }, // Mark as PBN section
          { loinc: "11450-4" },
          { loinc: "29545-1" },
        ],
        diagnoses: { // [!code ++:14] New in v2.1.2
          values: [
            {
              codes: [
                {
                  code: "I10",
                  description: "Essential hypertension",
                  type: "ICD10",
                },
              ],
              diagnosisNote: "Hypertension",
            },
          ],
        },
      },
    });
    ```
  </Tab>

  <Tab title="Mobile SDK (iOS)">
    Use `setSessionContext` to pass LOINC sections and structured diagnosis information. After the session ends, call `getStructuredData(for:)` to retrieve diagnoses and other structured output. Refer to the Mobile SDK [Create session](/mobile-sdk/ambient-guides/create-session#provide-clinical-context-optional-but-recommended) guide for more details.

    **Code example:**

    ```swift Swift theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
    let context = SukiAmbientContext(
      sections: [
        SukiAmbientSection(loinc: "51848-0", isPBNSection: true), // Mark as PBN section
        SukiAmbientSection(loinc: "11450-4"),
        SukiAmbientSection(loinc: "29545-1"),
      ],
      diagnosisInfo: [
        SukiAmbientDiagnosisInfo(
          codes: [
            SukiAmbientCode(code: "I10", description: "Essential hypertension", type: .icd10),
          ],
          diagnosisNote: "Hypertension",
        ),
      ],
    )
    ```
  </Tab>

  <Tab title="Ambient APIs">
    Use the [Context API](/api-reference/ambient-sessions/context) to provide existing patient diagnoses when starting a session.

    **Code example:**

    ```python Python theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
    payload = {
      "diagnoses": {
        "values": [
          {
            "codes": [
              {
                "code": "I10",
                "description": "Essential hypertension",
                "type": "ICD10",
              },
            ],
            "diagnosis_note": "Hypertension",
          },
        ],
      },
    }
    ```

    **APIs to use:**

    <CardGroup cols={2}>
      <Card title="POST Context API" icon="code" arrow={true} href="/api-reference/ambient-sessions/context">
        Provide initial diagnoses when starting a session
      </Card>

      <Card title="PATCH Update Context API" icon="code" arrow={true} href="/api-reference/ambient-sessions/update-context">
        Update or add diagnoses during a session
      </Card>
    </CardGroup>
  </Tab>
</Tabs>

## Configuration rules for PBC

When configuring PBC, follow these rules:

<Steps>
  <Step title="Single PBN section">
    Only one section can have `isPBNSection: true`. If multiple sections are marked as PBN, the ambient session will fail to start.
  </Step>

  <Step title="Default behavior">
    If no section includes the `isPBNSection` flag and the Assessment & Plan section (51847-2) is present, that section automatically becomes the PBN.
  </Step>

  <Step title="Explicit override">
    Explicitly set `isPBNSection: false` to prevent automatic PBN assignment.
  </Step>
</Steps>

<Warning>
  For a given ambient session, **only one section** can have `isPBNSection: true`. If more than one section is marked as PBN, the ambient session will fail to start.
</Warning>

## Core principles

Understanding these principles helps you use PBC effectively:

<AccordionGroup>
  <Accordion title="ICD10 source of truth">
    The <Tooltip tip="International Classification of Diseases, 10th Revision - a medical classification system used for coding diagnoses">ICD10</Tooltip> code is treated as the **primary identifier** for all clinical problems during processing.

    **System uses ICD10 for:**

    * Diagnosis identification and matching
    * Clinical problem categorization
    * Cross-session diagnosis continuity
    * Normalization of other code types (<Tooltip tip="Intelligent Medical Objects - a healthcare terminology company providing clinical code mapping services">IMO</Tooltip>, SNOMED)

    <Note> Non-ICD10 codes are automatically converted to ICD10 equivalents when possible. </Note>
  </Accordion>

  <Accordion title="Best-effort generation">
    All diagnosis generation is done on a **best-effort** basis. The system prioritizes returning partial, useful information over failing an entire request due to an issue with a single data point.
  </Accordion>

  <Accordion title="Clean slate sessions">
    In reambient scenarios, diagnoses from previous sessions are **not automatically carried forward**. You must provide the full context for each new session.

    <Tip> **Your Responsibility**: Include all relevant diagnoses (previous + new + modified) in each session context. </Tip>
  </Accordion>
</AccordionGroup>

## How PBC works

PBC processes diagnoses in three steps:

<Steps>
  <Step title="Provide existing diagnoses">
    You provide existing diagnoses when starting the session using the Context APIs.
  </Step>

  <Step title="Suki analyzes conversation">
    Suki's AI analyzes the conversation and identifies new problems or updates to existing diagnoses.
  </Step>

  <Step title="Generate structured output">
    Suki generates a clinical note organized by problem and structured artifacts with standardized codes.
  </Step>
</Steps>

```mermaid actions={false} theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
%%{init: {'theme':'base', 'themeVariables': { 'primaryColor':'#FFE148','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 TD
    A[Session audio/transcript] --> B[ML processing]
    B --> C[Suki Backend]
    C --> D{Valid ICD10?}
    D -->|Yes| E[Case 1: Enrich with IMO<br/>Add description, </br>laterality, IMO code]
    D -->|No| F[Case 2: Enrich with IMO<br/>Add ICD10, description, </br>laterality, IMO code]
    E --> G[Final Output<br/>Problems with Code, </br> Description, Diagnosis Note]
    F --> G
    
    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:#FFE148,stroke:#FFE148,stroke-width:2px,color:#111827
    style E fill:#FFF394,stroke:#FFE148,stroke-width:2px,color:#111827
    style F fill:#FFF394,stroke:#FFE148,stroke-width:2px,color:#111827
    style G fill:#FFF394,stroke:#FFE148,stroke-width:2px,color:#111827
```

<Note>
  Suki backend includes the ML-suggested problem name and returns standardized ICD10 code, description, and IMO equivalent in the final output.
</Note>

### Validation rules

Each diagnosis in your request must follow these rules:

* **One code per diagnosis**: Each diagnosis must have exactly one code (ICD10 or IMO)
* **No mixed codes**: A single diagnosis cannot contain multiple code types
* **Code required**: Every diagnosis must include a code

### Input processing

Suki processes diagnoses through normalization and deduplication:

<Warning>
  Normalization does not preserve the original input code. If a code cannot map to an ICD10 equivalent, **Suki skips the entire diagnosis object** and continues processing the remaining input.
</Warning>

### Reconciliation

When you send existing diagnoses via the Context API at session start, Suki **reconciles** them with what is discussed during the session. You get one problem list and no duplicates. This section describes the API flow (Context API to send, Structured Data API to retrieve).

For Web SDK, refer to the [Existing patient diagnoses](/web-sdk/guides/ambient-problem-based-charting#existing-patient-diagnoses) section in the ambient guide for more details.

**What happens to each diagnosis you send:**

* **Discussed in the session** - The diagnosis is updated and returned in the structured data output.
* **Not discussed in the session** - The diagnosis is not included in the final output.
* **Matches something discussed** - Your diagnosis and the one discussed are merged into a single entry (no duplicate).

<Note>
  The Structured Data API returns only diagnoses that were updated or newly generated.
</Note>

### How diagnoses are generated

During the session, Suki's AI analyzes the conversation and takes one of three actions on the diagnoses you provided:

1. **Update existing diagnosis**: Modify the content if it was discussed
2. **Generate new diagnosis**: Create a new diagnosis if a new problem was discussed
3. **Keep unchanged**: Leave a diagnosis untouched if it wasn't significantly discussed

<Warning>
  Only diagnoses that were **updated or newly generated** are returned in the final output. Untouched diagnoses are not returned. If a diagnosis wasn't discussed, it won't appear in the output.
</Warning>

### Output enrichment

For any diagnosis that was updated or newly generated, Suki enriches it with:

* **ICD10 code**: Standard diagnosis code
* **IMO code**: Intelligent Medical Objects code
* **SNOMED code**: SNOMED CT code (when available)
* **HCC code**: CMS-HCC model category derived from the ICD-10-CM code. The description uses the format `CMS-HCC model category <code>`.
* **Laterality**: Left/right/bilateral information when applicable
* **Post coordination flag**: Indicates if the diagnosis requires additional modifiers

<Note>
  The IMO code returned in the output may be different from any IMO code that was sent in the input payload. This is normal: Suki uses the most accurate code based on the conversation content.
</Note>

If enrichment fails, Suki still returns the diagnosis with available information to ensure you don't lose generated content.

### Retrieving generated diagnoses

Refer to the [How to use PBC for APIs and SDKs](/api-reference/capabilities/problem-based-charting#how-to-use-pbc-for-apis-and-sdks) section for more details.

## Handling reambient scenarios

In reambient scenarios, where a single patient encounter involves multiple recording sessions, understanding how context is managed is critical.

<Warning>
  Sessions do not **automatically inherit diagnoses** from previous sessions. Each session starts fresh. You must provide all relevant diagnoses for each new session.

  **What this means:**

  * When you use APIs in your implementation, only diagnoses passed via the Context APIs for the current session are considered
  * Diagnoses from previous sessions are **not automatically carried forward**
  * You must provide the complete and current list of all relevant diagnoses for each new session
</Warning>

**Your responsibilities:**

Because sessions don't inherit context, you must provide the complete list of all relevant diagnoses for each new session. This includes:

* **Modified diagnoses**: Any diagnoses that were changed by the provider in previous sessions
* **New diagnoses**: Any newly added diagnoses from previous sessions
* **Existing diagnoses**: Diagnoses from previous sessions that should be retained

**Recommended workflow:**

```mermaid actions={false} theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
%%{init: {'theme':'base', 'themeVariables': { 'primaryColor':'#FFE148','primaryTextColor':'#1a1a1a','primaryBorderColor':'#FFE148','lineColor':'#FFE148','secondaryColor':'#FFF394','tertiaryColor':'#FFFADE','mainBkg':'#FFF394','secondBkg':'#FFFADE','border1':'#FFE148','border2':'#FFE148','arrowheadColor':'#FFE148','fontFamily':'Inter, system-ui, sans-serif','fontSize':'14px','nodeBorder':'#FFE148','clusterBkg':'#FFFADE','clusterBorder':'#FFE148','defaultLinkColor':'#FFE148','titleColor':'#1a1a1a','edgeLabelBackground':'#FFE148','nodeTextColor':'#1a1a1a'}}}%%
graph TD
    A[Start session] --> B[Context with<br>existing diagnoses</br>]
    B --> C[Conduct encounter]
    C --> D[End session]
    D --> E[Get generated<br>diagnoses</br>]
    E --> F{Reambient session?}
    F -->|Yes| G[Include all<br>relevant diagnoses</br>]
    F -->|No| H[Complete]
    G --> B
    
    style A fill:#FFF394,stroke:#FFE148,stroke-width:2px,color:#1a1a1a
    style B fill:#FFF394,stroke:#FFE148,stroke-width:2px,color:#1a1a1a
    style C fill:#FFF394,stroke:#FFE148,stroke-width:2px,color:#1a1a1a
    style D fill:#FFF394,stroke:#FFE148,stroke-width:2px,color:#1a1a1a
    style E fill:#FFF394,stroke:#FFE148,stroke-width:2px,color:#1a1a1a
    style F fill:#FFE148,stroke:#FFE148,stroke-width:2px,color:#1a1a1a
    style G fill:#FFF394,stroke:#FFE148,stroke-width:2px,color:#1a1a1a
    style H fill:#FFF394,stroke:#FFE148,stroke-width:2px,color:#1a1a1a
```

<Note>
  After each session, retrieve the generated diagnoses using the Structured Data API, then include all relevant diagnoses (including any modifications) when starting the next session.
</Note>

## Best practices

<Tip>
  * **Provide complete context**: Always include all relevant existing diagnoses when starting a session
  * **Use ICD10 when possible**: ICD10 codes are preferred and processed most reliably
  * **Handle reambient carefully**: Retrieve diagnoses after each session and include them in the next session
  * **Validate codes**: Ensure diagnosis codes are valid before sending them
  * **Monitor output**: Check which diagnoses were updated or generated to understand what was discussed
  * **Update after user edits**: If providers modify diagnoses, include those modifications in subsequent sessions
</Tip>

## FAQs

<AccordionGroup>
  <Accordion title="How does the system handle reambient scenarios?">
    In reambient scenarios, the system does not automatically carry forward diagnoses from previous sessions. You must provide the complete and current list of all relevant diagnoses for each new session.
  </Accordion>

  <Accordion title="How does the system handle non-ICD10 codes?">
    The system uses [IMO APIs](https://www.imohealth.com/) to find the best possible ICD10 code equivalent for non-ICD10 codes. If a code cannot be mapped, that diagnosis is skipped.
  </Accordion>

  <Accordion title="How does diagnosis normalization work?">
    The system normalizes all codes to ICD10 before processing. ICD10 is used as the source of truth for all diagnosis operations.
  </Accordion>

  <Accordion title="How does diagnosis deduplication work?">
    The system deduplicates diagnoses based on the ICD10 code. Diagnoses with the same ICD10 code are merged, and their notes are combined.
  </Accordion>

  <Accordion title="Why aren't all input diagnoses returned?">
    Only diagnoses that were updated or newly generated are returned. Diagnoses that weren't discussed during the session are not included in the output.
  </Accordion>
</AccordionGroup>
