Problem-Based Charting

Problem-based clinical documentation approach with diagnosis context integration

Updated

• Ambient API structured data now includes HCC codes alongside ICD10, IMO, and SNOMED for each suggested diagnosis.
• For how Ambient APIs reconcile seeded diagnoses with the conversation, refer to Reconciliation.

Problem-Based Charting is supported by: Ambient APIs, Web SDK, Mobile SDK

The Headed Web SDK does not auto-generate ICD-10 codes for new problems discussed during the visit. You can still enable Problem-Based Charting and seed existing EMR diagnoses with ICD-10. For suggested diagnosis codes (ICD10, IMO, SNOMED, and HCC), retrieve Ambient session structured data or Encounter structured data after an Ambient API session.

Problem-Based Charting (PBC) organizes clinical notes by patient problems instead of traditional note sections. When you use PBC, Suki generates a clinical note organized by each problem or diagnosis.

• With Ambient APIs, you can also retrieve structured diagnosis output: suggested diagnoses with ICD10, IMO, SNOMED, and HCC codes when available.

• PBC notes are different from traditional notes. In normal clinical 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: Include existing problems from previous visits when you pass diagnoses into session context.
• Complete picture: Capture both old and new problems discussed during the visit.
• Structured data (Ambient APIs): Retrieve standardized codes (ICD10, IMO, SNOMED, and HCC) for EHR integration. The headed Web SDK does not auto-generate these codes yet.

How Problem-Based Charting improves clinical documentation

Problem-Based Charting improves documentation by organizing the note around clinical problems. With Ambient APIs, you can also retrieve coded diagnoses for EHR write-back.

What you configure	How the note gets better
One PBN section (for example Assessment & Plan)	Related history, assessment, and plan content groups under each problem
Existing patient diagnoses in session context	Continuity of care is reflected instead of treating every visit as a blank slate
Structured diagnosis output after generation (Ambient APIs)	Suggested ICD10, IMO, SNOMED, and HCC codes support coding and EHR workflows

Traditional section-based notes can scatter details about one problem across the note. PBC keeps problem-specific content together. With Ambient APIs, you can also retrieve structured diagnosis artifacts for review, coding, and EHR submission.

How to enable PBC using APIs and SDKs

You enable PBC by completing the following steps:

• Define which note sections to generate and which one is the PBN.
• Pass the patient’s existing diagnoses into session context when you have them.
• After the session finishes, read the note. With Ambient APIs, also retrieve structured diagnosis output when you need suggested codes.

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.

Ambient APIs

Send the LOINC sections array in the Context API 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.

Mobile SDK (iOS)

Pass LOINC sections in kSections via setSessionContext. See the Mobile SDK Create session guide for field names and examples.

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 for more details.

Mobile SDK (iOS)

Use SukiAmbientConstant.kDiagnosisInfo in setSessionContext. Refer to the Mobile SDK Create session guide for more details.

Retrieve Diagnosis Results

Ambient APIs

After the session has finished processing, use the Structured Data or Encounter Structured Data APIs to read suggested diagnoses and codes.

Mobile SDK (iOS)

After the session completes, call getStructuredData(for:). See Check status and retrieve content.

Web SDK

After note generation succeeds, read the note from onNoteSubmit (React) or note-submission:success (JavaScript and React). A section can include a diagnosis object when you passed that problem into the session and it was discussed. The Headed Web SDK does not auto-generate ICD-10 codes for new problems. Refer to Receiving note content, Response structure, and Diagnosis.

Implementation examples

Web SDK

Use the diagnoses block in ambientOptions to provide existing patient diagnoses when starting a session.

Code example:

JavaScript

sdkClient.mount({
  rootElement: document.getElementById("suki-root"),
  encounter: encounterDetails,
  ambientOptions: {
    sections: [
      { loinc: "51847-2", isPBNSection: true }, // Assessment and Plan as PBN
      { loinc: "11450-4" }, // Problem List
      { loinc: "29545-1" }, // Physical Exam
    ],
    diagnoses: { // New in v2.1.2
      values: [
        {
          codes: [
            {
              code: "I10",
              description: "Essential hypertension",
              type: "ICD10",
            },
          ],
          diagnosisNote: "Hypertension",
        },
      ],
    },
  },
});

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 guide for more details.

Code example:

Swift

let context = SukiAmbientContext(
  sections: [
    SukiAmbientSection(loinc: "51847-2", isPBNSection: true), // Assessment and Plan as PBN
    SukiAmbientSection(loinc: "11450-4"), // Problem List
    SukiAmbientSection(loinc: "29545-1"), // Physical Exam
  ],
  diagnosisInfo: [
    SukiAmbientDiagnosisInfo(
      codes: [
        SukiAmbientCode(code: "I10", description: "Essential hypertension", type: .icd10),
      ],
      diagnosisNote: "Hypertension",
    ),
  ],
)

Ambient APIs

Use the Context API to provide existing patient diagnoses when starting a session.

Code example:

Python

payload = {
  "diagnoses": {
    "values": [
      {
        "codes": [
          {
            "code": "I10",
            "description": "Essential hypertension",
            "type": "ICD10",
          },
        ],
        "diagnosis_note": "Hypertension",
      },
    ],
  },
}

APIs to use:

POST Context API

Provide initial diagnoses when starting a session.

PATCH Update Context API

Update or add diagnoses during a session.

Configuration rules for PBC

When configuring PBC, follow these rules:

1. Single PBN Section

   Only one section can have isPBNSection: true. If multiple sections are marked as PBN, the ambient session will fail to start.

2. Default Behavior

   If no section includes the isPBNSection flag and the Assessment & Plan section (51847-2) is present, that section automatically becomes the PBN.

3. Explicit Override

   Explicitly set isPBNSection: false to prevent automatic PBN assignment.

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.

Core principles

Understanding these principles helps you use PBC effectively:

ICD10 Source of Truth

The ICD10 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 (IMO, SNOMED).

Non-ICD10 codes are automatically converted to ICD10 equivalents when possible.

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.

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.

Your Responsibility: Include all relevant diagnoses (previous + new + modified) in each session context.

How PBC works

PBC processes diagnoses in three steps:

1. Provide Existing Diagnoses

   You provide existing diagnoses when starting the session using the Context APIs.

2. Suki Analyzes Conversation

   Suki’s AI analyzes the conversation and identifies new problems or updates to existing diagnoses.

3. Generate Structured Output

   Suki generates a clinical note organized by problem. With Ambient APIs, you can also retrieve structured diagnosis artifacts with standardized codes when available.

With Ambient API structured data, Suki returns the suggested problem name with standardized ICD10, description, and IMO when enrichment succeeds.

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:

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.

Reconciliation flow for APIs and SDKs

When you send existing diagnoses at session start, Suki reconciles them with what is discussed during the visit. Matching problems are merged into one entry, so the output stays free of duplicates.

For Ambient APIs, send diagnoses through the Context API, then retrieve results from the Structured Data API. For the Web SDK, pass diagnoses in ambientOptions.diagnoses. Refer to Existing patient diagnoses for the Web SDK flow.

What happens to each diagnosis you send:

• Discussed in the session: The diagnosis is updated and returned in Ambient API structured data. On the Web SDK, it can appear on the note when that problem was discussed.
• 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).

The Structured Data API returns only diagnoses that were updated or newly generated.

How diagnoses are generated

During the session, Suki 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.

With Ambient APIs, new and updated diagnoses can include suggested codes in structured data. With the Headed Web SDK, you can pass existing ICD-10 diagnoses into the session and generate a problem-based note but you cannot auto-generate ICD-10 codes for new problems.

For Ambient API structured data, only diagnoses that were updated or newly generated are returned. Untouched diagnoses are not returned. If a diagnosis wasn’t discussed, it won’t appear in the output.

Output enrichment

For Ambient API structured data, when a diagnosis was updated or newly generated, Suki can enrich it with:

• ICD10 code: Standard diagnosis code.
• IMO code: Intelligent Medical Objects code.
• SNOMED code: SNOMED CT code (when available).
• HCC code: Returned in structured-data output as "type": "HCC" when a mapping exists for that problem. Do not send HCC in session context.

CMS-HCC model category derived from the ICD-10-CM code. The description uses the format `CMS-HCC model category.

• Laterality: Left/right/bilateral information when applicable.
• Post coordination flag: Indicates if the diagnosis requires additional modifiers.

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.

If enrichment fails, Suki still returns the diagnosis with available information so you do not lose generated content. This enrichment does not apply to the headed Web SDK today.

Retrieving generated diagnoses

Refer to the How to enable PBC using APIs and SDKs section for more details.

Handling re-Ambient scenarios

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

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.

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:

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.

Best practices

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

FAQs

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.

How Does the System Handle Non-ICD10 Codes?

The system uses IMO APIs to find the best possible ICD10 code equivalent for non-ICD10 codes. If a code cannot be mapped, that diagnosis is skipped.

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.

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.

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.