Skip to main content
Quick summary
Patient Summary shows a concise pre-visit overview of a patient’s recent history on the Headed Web SDK patient profile (v3.3.0+). Ingest FHIR into CKG, ask Technical Support to enable Patient Summary for your organization, then pass matching encounter.identifier, encounter.practitionerFhirId, and encounter.patient when you initialize and when you mount.

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 not call Patient Summary generate, status, or retrieve APIs, and you do not control how the summary sections are rendered in your app.
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.
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.

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. Your backend owns this step.
  • Patient Summary enabled for your organization. You must ask Suki Technical Support to enable it.
Workflow:

Steps to integrate Patient Summary

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

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

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.
The Web SDK does not upload FHIR bundles. Your backend is responsible for keeping CKG data up to date.
3

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 (support@suki.ai) for help.
4

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:
Pass encounter when you initialize, not only when you mount. Patient Summary generation runs at login and needs practitionerFhirId when you initialize.
5

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.

Required encounter fields

The Patient Summary integration requires two FHIR ids in addition to your existing Patient context. Use these names consistently:
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.

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

Identifier mapping

One value per concept across your EMR, CKG, and Web SDK:
If encounter.identifier or encounter.practitionerFhirId is missing from encounter context, the Patient Summary UI stays hidden on the patient profile.

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

Code examples

The following code examples show how to integrate Patient Summary into the headed Web SDK.
JavaScript
For the complete Encounter type, including practitionerFhirId, refer to Encounter. For authentication setup, refer to 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.
  • 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.
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.

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 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.
Summary quality depends on how complete and current the FHIR data in CKG is. Outdated or incomplete ingestion produces outdated or poor summary sections.

Verify the integration

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

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

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

Launch and Confirm the Snippet

Launch the SDK, open the patient profile, and confirm that the Patient Summary snippet appears.
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.

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. For number of ingestions, polling, retries, logging, and empty-state guidance, refer 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 for more details.

Troubleshooting

If Patient Summary does not appear as expected on the patient profile, work through these checks.
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.
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.
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.
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 and CKG data ingestion.
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.
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.
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.
Cause: Remounting the iframe or SukiAssistant does not run login setup again.Resolution: Initialize the SDK again with the new encounter.practitionerFhirId.
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.
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 and Patient Summary best practices.
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.
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.

Next steps

Last modified on August 20, 2026