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

# Patient Summary In Web SDK

> Show pre-visit Patient Summary in the Headed Web SDK patient profile after you ingest FHIR into CKG and pass matching encounter.identifier and encounter.practitionerFhirId

<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">
    Patient Summary shows a concise pre-visit overview of a patient's recent history on the Headed Web SDK patient profile (<strong>v3.3.0+</strong>). Ingest FHIR into CKG, ask Technical Support to enable Patient Summary for your organization, then pass matching <code>encounter.identifier</code>, <code>encounter.practitionerFhirId</code>, and <code>encounter.patient</code> when you initialize and when you mount.

    <br />

    <br />

    The SDK triggers generation at login from the initialize options. The patient profile shows the snippet and full summary in the Web SDK UI. You do <strong>not</strong> call Patient Summary generate, status, or retrieve APIs, and you do <strong>not control</strong> how the summary sections are rendered in your app.
  </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>

Patient Summary gives clinicians a concise overview of a patient's recent clinical history before an appointment. It helps clinicians quickly understand relevant patient information without having to review the patient's history in detail.

In the Web SDK, the Patient Summary appears as a short snippet on the patient's profile when the clinician opens the patient record. The clinician can expand the snippet to view the full summary and review the patient's recent history before the encounter begins.

This guide is for partners using **`@suki-sdk/js`** or **`@suki-sdk/react`** to integrate Patient Summary into the headed Web SDK experience.

<Note>
  The Web SDK **owns** the Patient Summary UI inside the iframe. Your application ingests FHIR data into CKG and passes matching encounter context when you initialize and mount the SDK. You do **not** need to maintain any state for Patient Summary like calling Patient Summary generate, status, or retrieve APIs. You also do **not control** how the summary sections are rendered in your app via the SDK.
</Note>

**Agent summary:** Headed Web SDK Patient Summary (`v3.3.0+`): upgrade `@suki-sdk/js` or `@suki-sdk/react`, ingest FHIR via CKG, ask Technical Support to enable Patient Summary, then pass partner-supplied `encounter.identifier`, `encounter.practitionerFhirId`, and `encounter.patient` at initialize and at mount. Generation runs at login when `practitionerFhirId` is already present when you initialize. `setEncounter` (or the React `encounter` prop) loads another encounter so the profile can display that summary. It does not generate again. To generate for a different practitioner, initialize the SDK again with the new id. Do not reuse auth `providerId` as `encounter.practitionerFhirId`. Deep links: [Integrate CKG](/documentation/concepts/patient-summary/integrate-ckg), [CKG data ingestion](/patient-summary-api-reference/ckg-data-ingestion), [Best practices](/documentation/how-to/patient-summary/best-practices), [Encounter](/web-sdk/api-reference/types/encounter).

## Prerequisites

Before you start, make sure you have:

* **Web SDK v3.3.0 or later**
* **FHIR data ingested into CKG** using the [Patient Summary CKG Data Ingestion APIs](/patient-summary-api-reference/ckg-data-ingestion). Your backend owns this step.
* Patient Summary **enabled** for your organization. You must ask Suki Technical Support to enable it.

**Workflow:**

```mermaid actions={false} theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
flowchart TB
  A["Your EMR / FHIR resources"] --> B["FHIR encounter id<br/><code>encounter.identifier</code>"]
  A --> C["FHIR practitioner id<br/><code>encounter.practitionerFhirId</code>"]
  A --> D["Patient data"]
  B --> E["Your backend / CKG ingestion"]
  C --> E
  D --> E
  E --> F["Clinical Knowledge Graph<br/><code>fhir_encounter_id</code><br/><code>fhir_practitioner_id</code>"]
  F --> G["Headed Web SDK<br/>matching ids"]
  G --> H["Patient profile"]
  H --> I["Snippet"]
  H --> J["Full summary"]

  style A fill:#FFF394,stroke:#333,color:#000
  style B fill:#FFF394,stroke:#333,color:#000
  style C fill:#FFF394,stroke:#333,color:#000
  style D fill:#FFF394,stroke:#333,color:#000
  style E fill:#FFF394,stroke:#333,color:#000
  style F fill:#FFF394,stroke:#333,color:#000
  style G fill:#FFF394,stroke:#333,color:#000
  style H fill:#FFF394,stroke:#333,color:#000
  style I fill:#FFF394,stroke:#333,color:#000
  style J fill:#FFF394,stroke:#333,color:#000
```

## Steps to integrate Patient Summary

Follow these steps to integrate Patient Summary into the headed Web SDK:

<Steps>
  <Step title="Upgrade the Web SDK">
    Use **`@suki-sdk/js`** or **`@suki-sdk/react`** version **3.3.0 or later**. Patient Summary is not supported in earlier versions.
  </Step>

  <Step title="Ingest FHIR Data into CKG">
    Use the Patient Summary **CKG Data Ingestion APIs** from your backend to upload the FHIR R4 data required for Patient Summary.

    Upload the FHIR bundles and poll the ingestion status until processing completes. Keep the following data current:

    * Schedule
    * Encounter
    * Practitioner
    * Clinical history

    For production, ingest the data ahead of the clinic day so it is available when clinicians open patient profiles.

    * [Integrate CKG](/documentation/concepts/patient-summary/integrate-ckg)
    * [CKG data ingestion APIs](/patient-summary-api-reference/ckg-data-ingestion)
    * [Patient Summary basic usage](/documentation/how-to/patient-summary/basic-usage)

    <Warning>
      The Web SDK does not upload FHIR bundles. Your backend is responsible for keeping CKG data up to date.
    </Warning>
  </Step>

  <Step title="Enable Patient Summary">
    Contact **Suki Technical Support** to enable Patient Summary for your organization.

    Patient Summary must be enabled for the organization before the UI appears. Without organization enablement, the Patient Summary UI remains hidden even when the SDK version, CKG data, and `encounter.identifier` / `encounter.practitionerFhirId` are configured correctly.

    Refer to [Partner support](/documentation/references/support) (`support@suki.ai`) for help.
  </Step>

  <Step title="Pass Encounter Context">
    When you initialize and mount the Web SDK, pass an `encounter` object that contains:

    * `encounter.identifier`: FHIR encounter id (must match CKG `fhir_encounter_id`)
    * `encounter.practitionerFhirId`: FHIR practitioner id (must match CKG `fhir_practitioner_id`)
    * `encounter.patient`: your existing patient object

    Pass this `encounter` object in both places:

    | When you call                               | Why it matters                                                  |
    | :------------------------------------------ | :-------------------------------------------------------------- |
    | `initialize` (JavaScript) or `init` (React) | The SDK can trigger Patient Summary generation at login         |
    | `mount` or `SukiAssistant`                  | The headed UI can open the patient profile and load the summary |

    <Note>
      Pass `encounter` when you initialize, not only when you mount. Patient Summary generation runs at login and needs `practitionerFhirId` when you initialize.
    </Note>
  </Step>

  <Step title="Open the Patient Profile">
    After login, open the patient profile in the headed Web SDK.

    When Patient Summary is enabled, matching CKG data is available, and `encounter.identifier` plus `encounter.practitionerFhirId` are present at initialize and at mount, the patient profile displays the Patient Summary snippet. Clinicians expand the snippet to view the full summary.
  </Step>
</Steps>

## Required encounter fields

The Patient Summary integration requires two FHIR ids in addition to your existing [Patient context](/web-sdk/api-reference/types/patient). Use these names consistently:

| Concept              | Web SDK field                  | CKG / Patient Summary API | Where it comes from                       |
| :------------------- | :----------------------------- | :------------------------ | :---------------------------------------- |
| FHIR encounter id    | `encounter.identifier`         | `fhir_encounter_id`       | Your EMR / FHIR Encounter resource (UUID) |
| FHIR practitioner id | `encounter.practitionerFhirId` | `fhir_practitioner_id`    | Your EMR / FHIR Practitioner resource     |
| Patient context      | `encounter.patient`            | (unchanged)               | Your existing Web SDK patient object      |

<Tip>
  **You supply both FHIR ids. Suki does not.** Take them from your EMR or FHIR resources and keep the same values in CKG ingestion (`fhir_encounter_id`, `fhir_practitioner_id`) and on the Web SDK `encounter` (`encounter.identifier`, `encounter.practitionerFhirId`). A mismatch prevents Patient Summary from resolving on the patient profile.
</Tip>

### encounter.identifier

Pass your **FHIR encounter id** as `encounter.identifier`.

* Use the **same value** as in your FHIR Encounter resource and as CKG `fhir_encounter_id`.
* The SDK maps this value to `emr_encounter_id`. Ambient and Patient Summary use that field for the same visit to support interoperability.
* Prefer a **UUID**. The platform field supports a UUID today. Non-UUID values will **break note retrieval** even when ambient session start, pause, and submit still work. The platform expects a maximum of **36 characters**. The Web SDK does not validate length or UUID format.
* Patient Summary uses this field from Web SDK v3.3.0+. It must match CKG `fhir_encounter_id` for that visit.
* Pass the id on `encounter.identifier`. Patient Summary does not read `ambientOptions.emrEncounterId`. That option is **not a supported partner setting**.

### encounter.practitionerFhirId

Pass your **FHIR practitioner id** as `encounter.practitionerFhirId`.

* This field is **required** for Patient Summary generation at login and for the Patient Summary UI on the patient profile.
* **You supply this id. Suki does not.** Use the same value as CKG `fhir_practitioner_id` from your EMR or FHIR Practitioner resource.

<Note>
  - Each logged-in practitioner has **one** FHIR practitioner id. Pass it as `encounter.practitionerFhirId` when you **initialize the Web SDK** so generation can run at login. Pass it again when you **mount**, and keep it on every `setEncounter` call or React `encounter` prop update so the headed UI can load the summary.

  - `setEncounter` updates which encounter the profile loads. It does **not** generate again.

  - To generate Patient Summary for another practitioner's appointments, **initialize the Web SDK again** with the new `encounter.practitionerFhirId`. Remounting the iframe alone is not enough.
</Note>

<Warning>
  Do not use auth **`providerId`** as **`encounter.practitionerFhirId`**. `providerId` belongs on `SukiAuthManager` for authentication. `encounter.practitionerFhirId` belongs on `encounter` for Patient Summary and must match CKG `fhir_practitioner_id`. The SDK does not map one field to the other.
</Warning>

### Identifier mapping

One value per concept across your EMR, CKG, and Web SDK:

| Concept              | Your system                   | CKG                    | Web SDK                        |
| :------------------- | :---------------------------- | :--------------------- | :----------------------------- |
| FHIR encounter id    | FHIR Encounter resource id    | `fhir_encounter_id`    | `encounter.identifier`         |
| FHIR practitioner id | FHIR Practitioner resource id | `fhir_practitioner_id` | `encounter.practitionerFhirId` |

<Warning>
  If `encounter.identifier` or `encounter.practitionerFhirId` is missing from encounter context, the Patient Summary UI stays **hidden** on the patient profile.
</Warning>

## Pass encounter context

Authenticate and initialize the Web SDK, then pass `encounter` when you initialize and when you mount. The two calls need the same `identifier`, `practitionerFhirId`, and `patient` values. They do not need to share one object.

* **JavaScript:** Pass `encounter` to `initialize` and to `mount`.
* **React:** Pass `encounter` to `init` and to `SukiAssistant`.

<Note>
  Use `setEncounter` in JavaScript, or update the React `encounter` prop, when the same clinician opens another visit. Keep that clinician's `encounter.practitionerFhirId`. The profile loads that visit's summary. Generation already ran at login. If a different clinician logs in, initialize the SDK again with their `practitionerFhirId`.
</Note>

### Code examples

The following code examples show how to integrate Patient Summary into the headed Web SDK.

**Language tabs (agents):** Equivalent samples: JavaScript, React.

* **JavaScript:** `initialize({ authManager, encounter })`, then `mount({ rootElement, encounter })` with the same `encounter.identifier`, `encounter.practitionerFhirId`, and `patient`. Switch encounters for the same practitioner with `setEncounter`. That call loads the summary. It does not generate again. Initialize again to generate for a different practitioner. Remounting is not enough.
* **React:** `init({ authManager, encounter })`, then `<SukiAssistant encounter={...} />`. Updating the prop calls `setEncounter` and loads the summary. It does not generate again. Remount `SukiProvider` (for example `key={fhirPractitionerId}`) so `init` runs again with the new practitioner id. A `key` on `SukiAssistant` alone is not enough.
* Required fields: `encounter.identifier` (FHIR encounter id / UUID = CKG `fhir_encounter_id`), `encounter.practitionerFhirId` (FHIR practitioner id = CKG `fhir_practitioner_id`), `encounter.patient`.
* Generation runs at login from the initialize options, not from `setEncounter` or remounting. Pass `encounter` at initialize even if your editor does not list it on `InitOptions`.

<Tabs>
  <Tab title="JavaScript">
    ```js JavaScript expandable theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
    import { SukiAuthManager } from "@suki-sdk/core";
    import { initialize } from "@suki-sdk/js";

    // Replace with values from your EHR / FHIR resources.
    // encounter.identifier = FHIR encounter id = CKG fhir_encounter_id
    // encounter.practitionerFhirId = FHIR practitioner id = CKG fhir_practitioner_id
    const encounterDetails = {
      identifier: "6ec3920f-b0b1-499d-a4e9-889bf788e5ab", // FHIR encounter id (UUID)
      practitionerFhirId: "a1b2c3d4-e5f6-7890-abcd-ef1234567890", // FHIR practitioner id
      patient: {
        identifier: "905c2521-25eb-4324-9978-724636df3436",
        name: {
          use: "official",
          family: "Doe",
          given: ["Jane"],
          suffix: [],
        },
        birthDate: "1985-04-12",
        gender: "Female",
      },
    };

    const authManager = new SukiAuthManager({
      partnerId: "f80c8db8-a4d0-4b75-8d63-56c82b5413f0", // Replace with your Partner ID
      partnerToken: "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...", // Replace with your Partner Token
      providerName: "John Doe",
      providerOrgId: "1234",
      providerSpecialty: "FAMILY_MEDICINE",
      environment: "production", // Replace with "staging" while testing
      loginOnInitialize: true,
      providerId: "1234567890", // Replace with your practitioner id. Authentication only. Do not reuse as practitionerFhirId
    });

    // Pass encounter at initialize so generation can run at login.
    const sdkClient = initialize({
      authManager,
      encounter: encounterDetails,
    });

    const unsubscribeInit = sdkClient.on("init:change", (isInitialized) => {
      if (!isInitialized) {
        return;
      }

      const rootElement = document.getElementById("suki-root");
      if (!rootElement) {
        console.error("Missing #suki-root mount element");
        return;
      }

      // Pass encounter again at mount so the profile can load the summary.
      // A new object is fine. Keep identifier, practitionerFhirId, and patient
      // the same as at initialize.
      void sdkClient.mount({
        rootElement,
        encounter: encounterDetails,
      });
    });

    const unsubscribeReady = sdkClient.on("ready", () => {
      console.log("Web SDK ready");
    });

    // Same practitioner: switch the active encounter when the clinician
    // selects another appointment. setEncounter loads that encounter's
    // summary. It does not generate again.
    async function openEncounter(nextEncounter) {
      await sdkClient.setEncounter({
        identifier: nextEncounter.fhirEncounterId,
        practitionerFhirId: encounterDetails.practitionerFhirId,
        patient: {
          identifier: nextEncounter.patientId,
          name: {
            use: "official",
            family: nextEncounter.familyName,
            given: [nextEncounter.givenName],
            suffix: [],
          },
          birthDate: nextEncounter.birthDate,
          gender: nextEncounter.gender,
        },
      });
    }

    // Different practitioner: initialize again with the new
    // encounter.practitionerFhirId. Remounting does not generate again.
    async function openPractitioner(nextEncounter) {
      sdkClient.destroy();
      // Then run the same initialize({ authManager, encounter }) + mount flow
      // with nextEncounter.fhirPractitionerId on encounter.practitionerFhirId.
    }

    window.addEventListener("beforeunload", () => {
      unsubscribeInit();
      unsubscribeReady();
      sdkClient.destroy();
    });
    ```
  </Tab>

  <Tab title="React">
    ```jsx React expandable theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
    import { useEffect, useMemo, useState } from "react";
    import { SukiAuthManager } from "@suki-sdk/core";
    import { SukiAssistant, SukiProvider, useSuki } from "@suki-sdk/react";

    function PatientChart({ visit }) {
      const authManager = useMemo(
        () =>
          new SukiAuthManager({
            partnerId: "f80c8db8-a4d0-4b75-8d63-56c82b5413f0", // Replace with your Partner ID
            partnerToken: "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...", // Replace with your Partner Token
            providerName: "John Doe",
            providerOrgId: "1234",
            providerSpecialty: "FAMILY_MEDICINE",
            environment: "production", // Use "staging" while testing
            loginOnInitialize: true,
            providerId: "1234567890",
          }),
        [],
      );

      const { init, isInitialized, on } = useSuki();

      // Build the encounter from the active visit in your EHR.
      // encounter.identifier = FHIR encounter id = CKG fhir_encounter_id
      // encounter.practitionerFhirId = FHIR practitioner id = CKG fhir_practitioner_id
      const [encounter, setEncounter] = useState(() => ({
        identifier: visit.fhirEncounterId, // FHIR encounter id (UUID)
        practitionerFhirId: visit.fhirPractitionerId, // FHIR practitioner id
        patient: {
          identifier: visit.patientId,
          name: {
            use: "official",
            family: visit.familyName,
            given: [visit.givenName],
            suffix: [],
          },
          birthDate: visit.birthDate,
          gender: visit.gender,
        },
      }));

      useEffect(() => {
        if (!isInitialized) {
      // Pass encounter at init so generation can run at login.
          init({
            authManager,
            encounter,
          });
        }
      }, [authManager, encounter, init, isInitialized]);

      useEffect(() => {
        const unsubscribeReady = on("ready", () => {
          console.log("Web SDK ready");
        });

        return () => {
          unsubscribeReady();
        };
      }, [on]);

      // Same practitioner: update the encounter when the clinician opens
      // another appointment. SukiAssistant calls setEncounter for you.
      // Keep practitionerFhirId from initialize. Do not change the encounter
      // while an ambient session is in progress.
      useEffect(() => {
        if (!isInitialized) return;
        setEncounter((current) => ({
          identifier: visit.fhirEncounterId,
          practitionerFhirId: current.practitionerFhirId,
          patient: {
            identifier: visit.patientId,
            name: {
              use: "official",
              family: visit.familyName,
              given: [visit.givenName],
              suffix: [],
            },
            birthDate: visit.birthDate,
            gender: visit.gender,
          },
        }));
      }, [isInitialized, visit]);

      if (!isInitialized) {
        return <div>Initializing Suki...</div>;
      }

      // Pass encounter on SukiAssistant so the profile can load the summary.
      // A new object is fine. Keep identifier, practitionerFhirId, and patient
      // the same as at init.
      return <SukiAssistant encounter={encounter} />;
    }

    export function App({ visit }) {
      // Different practitioner: remount the provider so init runs again with
      // the new practitionerFhirId. A key on SukiAssistant alone does not
      // generate again.
      return (
        <SukiProvider key={visit.fhirPractitionerId}>
          <div id="suki-root" style={{ height: 640, width: 360 }}>
            <PatientChart visit={visit} />
          </div>
        </SukiProvider>
      );
    }
    ```
  </Tab>
</Tabs>

For the complete `Encounter` type, including `practitionerFhirId`, refer to [Encounter](/web-sdk/api-reference/types/encounter).

For authentication setup, refer to [Authentication](/web-sdk/authentication).

## Switching visits and summary generation

Generation and visit switching both use `encounter`, but they are not the same step.

Each logged-in practitioner has **one** FHIR practitioner id. Pass it as `encounter.practitionerFhirId` when you initialize so generation can run at login. Keep that same id on every mount and `setEncounter` call so the profile can load the summary.

| Partner action                                                   | When                                                | What the SDK does                                           |
| :--------------------------------------------------------------- | :-------------------------------------------------- | :---------------------------------------------------------- |
| `initialize` or `init` with `encounter.practitionerFhirId`       | At login, or when you start a new session with Suki | Triggers Patient Summary generation for that practitioner   |
| `mount` or `SukiAssistant` with the full `encounter`             | After initialize                                    | Opens the patient profile and loads the summary             |
| `setEncounter` (JavaScript) or update the React `encounter` prop | Same practitioner, different appointment            | Loads that encounter's summary. Does **not** generate again |
| Initialize the SDK again with a new `practitionerFhirId`         | Different practitioner                              | Triggers generation for that practitioner                   |

### Recommended practices for switching practitioners

* Keep the logged-in clinician's `encounter.practitionerFhirId` on every `setEncounter` call or React `encounter` prop update. The profile uses that id to load the summary.
* `setEncounter` and the React `encounter` prop do not generate again. If a different clinician logs in, initialize the SDK again with their `practitionerFhirId`.

<Warning>
  The SDK **rejects** `setEncounter` and React `encounter` prop updates while an ambient session is in progress. Wait until the session ends, then switch visits with a new `encounter.practitionerFhirId`.
</Warning>

## What clinicians see on the patient profile

When a clinician logs in and opens a patient record, the patient profile shows a Patient Summary snippet. Expanding the snippet opens the full summary.
The full summary includes **about this visit**, **summary**, **previous visits**, and **problems**. Refer to [Patient Summary overview](/documentation/concepts/patient-summary/overview#what-patient-summary-includes) for more details.

The snippet appears only when Patient Summary is enabled for the organization, matching FHIR data is in CKG, and `encounter.identifier` plus `encounter.practitionerFhirId` are present when you initialize and when you mount.

<Tip>
  Summary quality depends on how complete and current the FHIR data in CKG is. Outdated or incomplete ingestion produces outdated or poor summary sections.
</Tip>

## Verify the integration

Use the **Web SDK** to verify your integration before making production mounts.

<Steps>
  <Step title="Confirm Org Enablement and CKG Data">
    Confirm that the test organization has Patient Summary enabled, and that matching FHIR data is already in CKG for the encounter you will use.
  </Step>

  <Step title="Configure Encounter in the Web SDK">
    Open the Web SDK encounter configuration.

    * Set **Encounter ID** to your FHIR encounter id (`encounter.identifier` / CKG `fhir_encounter_id`).
    * Set **Practitioner FHIR ID** to your FHIR practitioner id (`encounter.practitionerFhirId` / CKG `fhir_practitioner_id`).
    * Keep the patient fields consistent with your test patient.
  </Step>

  <Step title="Launch and Confirm the Snippet">
    Launch the SDK, open the patient profile, and confirm that the Patient Summary snippet appears.
  </Step>
</Steps>

<Note>
  The Web SDK sends the encounter when you launch the SDK, including the Practitioner FHIR ID, so generation can run at login. For Patient Summary, use a non-empty FHIR practitioner id. Leave it blank only when you skip Patient Summary.
</Note>

## Keep CKG data up to date

This step is critical to control the quality of the summary sections and meet your SLA expectations with your clinicians.

The Web SDK does not ingest FHIR data for you. Your backend **remains responsible for keeping CKG current** so summaries resolve on the patient profile and quality meets your SLA expectations.

| Partner responsibility                                                                            | Why it matters                                                                          |
| :------------------------------------------------------------------------------------------------ | :-------------------------------------------------------------------------------------- |
| Upload FHIR R4 data using [CKG data ingestion](/patient-summary-api-reference/ckg-data-ingestion) | Patient Summary uses only data stored in CKG                                            |
| Poll ingestion until it completes                                                                 | A useful summary is not expected while ingestion is still running                       |
| Keep `fhir_encounter_id` and `fhir_practitioner_id` stable                                        | These must match Web SDK `encounter.identifier` and `encounter.practitionerFhirId`      |
| Refresh schedule and clinical history                                                             | Stale CKG data can produce thin or empty summary sections                               |
| Ingest ahead of the clinic day                                                                    | Gives ingestion and summary generation time to complete before clinicians open profiles |

For number of ingestions, polling, retries, logging, and empty-state guidance, refer to [Patient Summary best practices](/documentation/how-to/patient-summary/best-practices).

## When to use the API-only integration

Use the **Headed Web SDK** path when:

* Clinicians already use the headed Web SDK patient profile.
* You want to provide pre-visit context without building Patient Summary screens in your EHR.
* Your backend can ingest FHIR into CKG using the Patient Summary CKG Data Ingestion APIs.
* Patient Summary can be enabled for your organization.

Use the **API-only** path when your application owns the schedule, chart, or UI.

Refer to the [Patient Summary integration decision guide](/documentation/get-started/patient-summary-integration-decision-guide) for more details.

## Troubleshooting

If Patient Summary does not appear as expected on the patient profile, work through these checks.

<AccordionGroup>
  <Accordion title="Patient Summary UI Stays Hidden">
    **Cause:** `encounter.identifier` or `encounter.practitionerFhirId` is missing from encounter context, or Patient Summary is not enabled for the organization.

    **Resolution:**

    * Confirm Technical Support enabled Patient Summary for your organization.
    * Pass both `encounter.identifier` and `encounter.practitionerFhirId` when you initialize and when you mount.
    * Confirm `encounter.patient` is present.
  </Accordion>

  <Accordion title="SDK Version Is Too Old">
    **Cause:** The app is running `@suki-sdk/js` or `@suki-sdk/react` earlier than **v3.3.0**.

    **Resolution:** Upgrade to **v3.3.0** or later. Patient Summary in the headed iframe is not supported in earlier versions.
  </Accordion>

  <Accordion title="Organization Not Enabled">
    **Cause:** Patient Summary is off for the organization.

    **Resolution:** Contact **Suki Technical Support** (`support@suki.ai`) and ask them to enable Patient Summary. The UI stays hidden until enablement is complete, even when SDK fields and CKG data are correct.
  </Accordion>

  <Accordion title="CKG Data Missing or Stale">
    **Cause:** Matching FHIR data was not ingested, ingestion is still running, or clinical history is thin.

    **Resolution:**

    * Complete CKG ingestion and wait until status is `COMPLETED`.
    * Confirm schedule, encounter, practitioner, and clinical history are in CKG for the visit.
    * Refer to [Integrate CKG](/documentation/concepts/patient-summary/integrate-ckg) and [CKG data ingestion](/patient-summary-api-reference/ckg-data-ingestion).
  </Accordion>

  <Accordion title="FHIR Encounter Id Does Not Match">
    **Cause:** Web SDK `encounter.identifier` does not equal CKG `fhir_encounter_id`, or the value is not a UUID. The platform field is a UUID today.

    **Resolution:**

    * Use the same FHIR encounter id in your FHIR Encounter resource, CKG ingestion (`fhir_encounter_id`), and `encounter.identifier`.
    * From Web SDK **v3.2.0+**, prefer a **UUID** when `encounter.identifier` is present. The Web SDK does not validate UUID format. Non-UUID values can break ambient note retrieval.
  </Accordion>

  <Accordion title="FHIR Practitioner Id Missing or Mismatched">
    **Cause:** `encounter.practitionerFhirId` is empty, or it does not equal CKG `fhir_practitioner_id`. Auth `providerId` was reused by mistake.

    **Resolution:**

    * Pass the FHIR practitioner id as `encounter.practitionerFhirId` when you initialize and when you mount.
    * Match CKG `fhir_practitioner_id`.
    * Do not use `SukiAuthManager` `providerId` as `encounter.practitionerFhirId`.
  </Accordion>

  <Accordion title="Patient Summary Missing after Mount Only">
    **Cause:** You passed `practitionerFhirId` only when you mounted the SDK. Generation runs at login from the initialize options, so mount-only setup does not trigger generation.

    **Resolution:** Pass `encounter`, including `practitionerFhirId`, when you initialize and when you mount.
  </Accordion>

  <Accordion title="Generation Did Not Run after Remount">
    **Cause:** Remounting the iframe or `SukiAssistant` does not run login setup again.

    **Resolution:** Initialize the SDK again with the new `encounter.practitionerFhirId`.
  </Accordion>

  <Accordion title="Generation Did Not Run">
    **Cause:** Login or a new Suki session completed without `encounter.practitionerFhirId` when you initialized. Later `setEncounter` calls do not trigger generation, even if they pass a practitioner id.

    **Resolution:** Include `encounter.practitionerFhirId` when you call `initialize` or `init`. Generation runs at login, or when you start a new session with Suki. It does not run when you only switch encounters with `setEncounter` or remount the iframe.
  </Accordion>

  <Accordion title="Empty Snippet after Generation">
    **Cause:** Generation finished, but CKG has little or no prior clinical history for the patient.

    **Resolution:** Treat an empty snippet as a clinical empty state, not a Web SDK mount failure. Keep the rest of the patient profile usable. For empty-state guidance, refer to [Retrieve patient summaries](/documentation/how-to/patient-summary/retrieve-patient-summaries) and [Patient Summary best practices](/documentation/how-to/patient-summary/best-practices).
  </Accordion>

  <Accordion title="Wrong Visit Summary Showing">
    **Cause:** The SDK is still on a previous encounter after the clinician opened another appointment for the same practitioner.

    **Resolution:** Call `setEncounter` (JavaScript) or update the React `encounter` prop with the new `encounter.identifier` and `encounter.patient`. Keep the mounted `encounter.practitionerFhirId`. Do not change the encounter while an ambient session is in progress.
  </Accordion>

  <Accordion title="Need Summaries for a Different Practitioner">
    **Cause:** `setEncounter` (or the React `encounter` prop) was used to pass a different `encounter.practitionerFhirId`. That call loads another encounter so the profile can display that summary. It does not generate again.

    **Resolution:** Initialize the SDK again with the new `encounter.practitionerFhirId`. In React, remount `SukiProvider` (for example, set `key` to the FHIR practitioner id). Remounting `SukiAssistant` alone is not enough.
  </Accordion>
</AccordionGroup>

## Next steps

* [Integrate CKG](/documentation/concepts/patient-summary/integrate-ckg) to keep FHIR data in CKG current.
* [Patient Summary best practices](/documentation/how-to/patient-summary/best-practices) for ingestion cadence, polling, retries, logging, and empty states.
* [Patient Summary basic usage](/documentation/how-to/patient-summary/basic-usage) for the end-to-end API workflow.
* [Encounter](/web-sdk/api-reference/types/encounter) for `encounter.identifier` and `encounter.practitionerFhirId` field details.
* [Patient Summary overview](/documentation/concepts/patient-summary/overview) for product capabilities beyond the headed Web SDK.
* [Web SDK changelog](/web-sdk/product-updates/changelog) for the v3.3.0 release notes.