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.
@suki-sdk/js or @suki-sdk/react to integrate Patient Summary into the headed Web SDK experience.
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.
Steps to integrate Patient Summary
Follow these steps to integrate Patient Summary into the headed Web SDK:Upgrade the Web SDK
@suki-sdk/js or @suki-sdk/react version 3.3.0 or later. Patient Summary is not supported in earlier versions.Ingest FHIR Data into CKG
- Schedule
- Encounter
- Practitioner
- Clinical history
Enable Patient Summary
encounter.identifier / encounter.practitionerFhirId are configured correctly.Refer to Partner support (support@suki.ai) for help.Pass Encounter Context
encounter object that contains:encounter.identifier: FHIR encounter id (must match CKGfhir_encounter_id)encounter.practitionerFhirId: FHIR practitioner id (must match CKGfhir_practitioner_id)encounter.patient: your existing patient object
encounter object in both places:encounter when you initialize, not only when you mount. Patient Summary generation runs at login and needs practitionerFhirId when you initialize.Open the Patient Profile
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:encounter.identifier
Pass your FHIR encounter id asencounter.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_idfor that visit. - Pass the id on
encounter.identifier. Patient Summary does not readambientOptions.emrEncounterId. That option is not a supported partner setting.
encounter.practitionerFhirId
Pass your FHIR practitioner id asencounter.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_idfrom your EMR or FHIR Practitioner resource.
-
Each logged-in practitioner has one FHIR practitioner id. Pass it as
encounter.practitionerFhirIdwhen you initialize the Web SDK so generation can run at login. Pass it again when you mount, and keep it on everysetEncountercall or Reactencounterprop update so the headed UI can load the summary. -
setEncounterupdates 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.
Identifier mapping
One value per concept across your EMR, CKG, and Web SDK:Pass encounter context
Authenticate and initialize the Web SDK, then passencounter 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
encountertoinitializeand tomount. - React: Pass
encountertoinitand toSukiAssistant.
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
- React
Encounter type, including practitionerFhirId, refer to Encounter.
For authentication setup, refer to Authentication.
Switching visits and summary generation
Generation and visit switching both useencounter, 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.
Recommended practices for switching practitioners
- Keep the logged-in clinician’s
encounter.practitionerFhirIdon everysetEncountercall or Reactencounterprop update. The profile uses that id to load the summary. setEncounterand the Reactencounterprop do not generate again. If a different clinician logs in, initialize the SDK again with theirpractitionerFhirId.
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, andencounter.identifier plus encounter.practitionerFhirId are present when you initialize and when you mount.
Verify the integration
Use the Web SDK to verify your integration before making production mounts.Confirm Org Enablement and CKG Data
Configure Encounter in the Web SDK
- Set Encounter ID to your FHIR encounter id (
encounter.identifier/ CKGfhir_encounter_id). - Set Practitioner FHIR ID to your FHIR practitioner id (
encounter.practitionerFhirId/ CKGfhir_practitioner_id). - Keep the patient fields consistent with your test patient.
Launch and Confirm the Snippet
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.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.
Troubleshooting
If Patient Summary does not appear as expected on the patient profile, work through these checks.SDK Version Is Too Old
SDK Version Is Too Old
@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.Organization Not Enabled
Organization Not Enabled
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.CKG Data Missing or Stale
CKG Data Missing or Stale
- 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.
FHIR Encounter Id Does Not Match
FHIR Encounter Id Does Not Match
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), andencounter.identifier. - From Web SDK v3.2.0+, prefer a UUID when
encounter.identifieris present. The Web SDK does not validate UUID format. Non-UUID values can break ambient note retrieval.
FHIR Practitioner Id Missing or Mismatched
FHIR Practitioner Id Missing or Mismatched
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.practitionerFhirIdwhen you initialize and when you mount. - Match CKG
fhir_practitioner_id. - Do not use
SukiAuthManagerproviderIdasencounter.practitionerFhirId.
Patient Summary Missing after Mount Only
Patient Summary Missing after Mount Only
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.Generation Did Not Run after Remount
Generation Did Not Run after Remount
SukiAssistant does not run login setup again.Resolution: Initialize the SDK again with the new encounter.practitionerFhirId.Generation Did Not Run
Generation Did Not Run
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.Empty Snippet after Generation
Empty Snippet after Generation
Wrong Visit Summary Showing
Wrong Visit Summary Showing
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.Need Summaries for a Different Practitioner
Need Summaries for a Different Practitioner
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
- Integrate CKG to keep FHIR data in CKG current.
- Patient Summary best practices for ingestion cadence, polling, retries, logging, and empty states.
- Patient Summary basic usage for the end-to-end API workflow.
- Encounter for
encounter.identifierandencounter.practitionerFhirIdfield details. - Patient Summary overview for product capabilities beyond the headed Web SDK.
- Web SDK changelog for the v3.3.0 release notes.