> ## 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 - Integration Decision Guide

> Decide how to integrate Patient Summary APIs for pre-visit workflows in your healthcare application

Suki for Partners provides Patient Summary for generating concise pre-visit summaries from FHIR data ingested into the Clinical Knowledge Graph (CKG).

You can integrate in two ways:

* **Patient Summary APIs:** Your application owns the clinician UI, when generation runs, and how completed summaries are displayed.
* **Headed Web SDK (v3.3.0 and later):** The patient profile UI inside the iframe shows a pre-visit snippet and full summary when Suki enables the capability for your organization and you pass matching FHIR encounter and practitioner identifiers. You can embed the experience without building the summary screens or calling Patient Summary generate, status, or retrieve APIs yourself.

This guide explains how Patient Summary fits into your product and helps you select the integration approach that best matches your application architecture, clinic-day workflow, and user experience goals.

For Ambient clinical documentation and Dictation workflows, refer to the [Ambient & Dictation integration decision guide](/documentation/get-started/integration-decision-guide).
For Form filling workflows, refer to the [Form filling integration decision guide](/documentation/get-started/form-filling-integration-decision-guide).

## Integration options

### Headed Web SDK

Use the Headed Web SDK when clinicians already work in the Suki iframe and you want pre-visit context on the patient profile without building summary screens yourself.

<CardGroup cols={2}>
  <Card title="Recommended For:" icon="cube">
    * Partners already embedding `@suki-sdk/js` or `@suki-sdk/react`.
    * Web apps that want hosted snippet and full summary UI.
    * Organizations with CKG ingestion already running for Patient Summary.
  </Card>

  <Card title="What You Build:" icon="gear">
    * Web SDK upgrade to **v3.3.0** or later.
    * FHIR encounter id and FHIR practitioner id on `encounter`.
    * Continued CKG FHIR ingestion (same as the API path).
  </Card>
</CardGroup>

Refer to [Patient Summary in the Web SDK](/web-sdk/guides/patient-summary).

### Patient Summary APIs

Patient Summary APIs remain the path when you own schedule cards, chart layouts, or multi-platform UIs outside the headed Web SDK. You build your own user interface and authentication flow, then call Suki REST endpoints from your backend to ingest FHIR data, generate summaries, monitor jobs, and retrieve completed content.

<CardGroup cols={2}>
  <Card title="Recommended For:" icon="server">
    * Backend systems and server integrations.
    * Custom schedule, chart, and patient-profile UIs.
    * Multi-platform applications that share the same APIs.
  </Card>

  <Card title="What You Build:" icon="gear">
    * Complete user interface for schedule and chart review.
    * Authentication and token handling on your backend.
    * CKG ingestion, generation triggers, polling, and retrieval.
  </Card>
</CardGroup>

<Note>
  CKG ingestion is required for both paths. The Headed Web SDK hosts the clinician summary UI. Custom applications still integrate through the [Patient Summary APIs](/patient-summary-api-reference/overview) and render summary sections themselves.
</Note>

## Designing Patient Summary into your clinical UX

Patient Summary is pre-visit preparation. It is not Ambient note generation during an encounter, and it is not Dictation. Use it when clinicians need concise prior-visit context before an upcoming appointment.

### Where will clinicians see the summary

| Surface                            | Typical fit                               | Why                                                                                 |
| :--------------------------------- | :---------------------------------------- | :---------------------------------------------------------------------------------- |
| **Provider schedule**              | Pre-visit summary                         | Short preview for appointment cards and morning prep.                               |
| **Patient chart**                  | Full Patient Summary                      | Complete sections for chart review before the visit.                                |
| **Appointment details**            | Full or pre-visit                         | Use full review when clinicians need more context, pre-visit when space is limited. |
| **Headed Web SDK patient profile** | Snippet, then full summary                | Hosted UI when you embed the Web SDK and pass FHIR ids.                             |
| **Mobile web or native clients**   | Patient Summary APIs through your backend | Keep credentials off the client and share the same APIs across platforms.           |

### When should your application generate summaries

| Trigger                        | Typical fit                       | Why                                                               |
| :----------------------------- | :-------------------------------- | :---------------------------------------------------------------- |
| **Morning clinic preparation** | Scheduled appointments generation | Prepare summaries for every appointment on a provider's schedule. |
| **Provider sign-in**           | Scheduled appointments generation | Ready summaries before the clinic day begins.                     |
| **Clinician opens one chart**  | Single encounter generation       | Generate or refresh one summary on demand.                        |
| **Late schedule addition**     | Single encounter generation       | Handle patients added after the morning run.                      |
| **New FHIR data available**    | Single encounter generation       | Refresh a summary after meaningful CKG updates.                   |

### What your application owns in the workflow

| Step                | What you decide                                                                                   |
| :------------------ | :------------------------------------------------------------------------------------------------ |
| **Ingest into CKG** | Which patients, schedules, and clinical history to upload, and when ingestion is complete.        |
| **Generate**        | Whether to use scheduled appointments, single encounter, or both.                                 |
| **Monitor**         | How often to poll, how long to wait, and what users see while generation runs.                    |
| **Retrieve**        | Whether to load the full summary or the pre-visit section.                                        |
| **Display**         | How to map **About this visit**, **Summary**, **Previous visits**, and **Problems** into your UI. |
| **Empty states**    | What to show for no upcoming appointment or limited prior history.                                |

<Tip>
  Generate summaries from your backend before the clinic day begins whenever possible. Reuse an existing summary when one is already available for the appointment, and regenerate only after meaningful CKG updates.
</Tip>

## How to choose

Choose the **Headed Web SDK** when you already embed the Web SDK and want Patient Summary on the patient profile. Choose the **Patient Summary APIs** when you own the clinician UI or need multi-platform retrieval outside the headed iframe. In both cases you still need CKG ingestion. For the API path, the decisions that matter most are **when to generate**, **which generation workflow to use**, and **what content to retrieve**.

**Tabs (agents):** Patient Summary supports Headed Web SDK and Patient Summary APIs. Humans see one tab.

* **By Project Type / By Team Skills / By Requirements:** when to use the headed Web SDK versus Patient Summary REST APIs while your app owns a custom UI.

A later tab group covers **Web Applications**, **Mobile Applications**, and **Backend Systems** scenarios.

<Tabs>
  <Tab title="By Project Type">
    <AccordionGroup>
      <Accordion title="Web Application">
        **Choose the Headed Web SDK if:**

        * You already embed `@suki-sdk/js` or `@suki-sdk/react`.
        * Clinicians use the Suki patient profile and you want hosted snippet and full summary UI.
        * You can pass matching FHIR encounter and practitioner ids on `encounter`.

        **Choose Patient Summary APIs if:**

        * You need pre-visit summaries in a custom web EHR, schedule view, or patient profile.
        * Your backend can ingest FHIR data into CKG and trigger generation.
        * You will render summary sections in your own browser UI.

        Keep Partner credentials and CKG or generation calls on your server for the API path. For the headed Web SDK path, refer to [Patient Summary in the Web SDK](/web-sdk/guides/patient-summary).
      </Accordion>

      <Accordion title="Mobile Healthcare Application">
        **For iOS Applications:**

        * **Choose Patient Summary APIs** through your backend, then display completed summaries in the native UI.

        **For Android Applications:**

        * **Choose Patient Summary APIs** through your backend with the same ingest, generate, poll, and retrieve workflow.
      </Accordion>

      <Accordion title="Backend System or Server Integration">
        **Choose Patient Summary APIs**

        * This is the primary integration path.
        * Provides complete control over CKG ingestion, generation timing, polling, and EHR handoff.
      </Accordion>
    </AccordionGroup>
  </Tab>

  <Tab title="By Team Skills">
    <CardGroup cols={2}>
      <Card title="Frontend Experience">
        **Recommended: Patient Summary APIs with your own UI**

        Your frontend renders schedule previews and chart review. Your backend calls the Patient Summary APIs for generation, status, and retrieval.
      </Card>

      <Card title="Backend/API Experience">
        **Recommended: Patient Summary APIs**

        Full control over CKG ingestion, asynchronous generation, polling, and system integration.
      </Card>

      <Card title="iOS/Swift or Android Experience">
        **Recommended: Patient Summary APIs through your backend**

        Native clients display completed summaries while your backend owns authentication and API calls.
      </Card>

      <Card title="Limited Development Resources">
        **Recommended: Start with one product**

        Begin with schedule preview or patient-profile review, use scheduled generation for the clinic day, and add on-demand encounter generation later.
      </Card>
    </CardGroup>
  </Tab>

  <Tab title="By Requirements">
    | Your Need                                   | Recommended Choice                | Why                                                          |
    | ------------------------------------------- | --------------------------------- | ------------------------------------------------------------ |
    | **Pre-visit context before appointments**   | Patient Summary APIs              | Concise clinical overview from CKG data                      |
    | **Morning preparation for a full schedule** | Scheduled appointments generation | One request can prepare summaries for the provider's day     |
    | **One patient chart or late add**           | Single encounter generation       | Generate or refresh one summary on demand                    |
    | **Schedule list preview**                   | Pre-visit summary retrieval       | Short section for dense appointment UIs                      |
    | **Detailed chart review**                   | Full Patient Summary retrieval    | Complete sections for clinician review                       |
    | **Custom UI on web or mobile**              | Patient Summary APIs              | You own layout, branding, and empty states                   |
    | **Multi-platform support**                  | Patient Summary APIs              | Same APIs across web, mobile, and backend                    |
    | **Server-owned clinic-day orchestration**   | Patient Summary APIs              | Backend controls ingestion, generation, polling, and caching |
  </Tab>
</Tabs>

<Note>
  **HIPAA Compliance**: Patient Summary APIs can be implemented in a HIPAA-compliant manner. Compliance depends on your implementation practices and security measures.
</Note>

## Prerequisites for Patient Summary

Before integrating Patient Summary, you must complete the partner onboarding process:

### Required for Patient Summary

**Partner Registration:**

* Complete the [Partner onboarding process](/documentation/get-started/partner-onboarding).
* Receive your unique `partner_id` from Suki.
* Provide your JWKS endpoint URL to Suki for token validation.

**Authentication System:**

* OAuth 2.0 compliant authentication system.
* JWT token generation with consistent user identifier.
* Publicly accessible JWKS endpoint for token verification.
* Ability to obtain `sdp_suki_token` for Patient Summary generation, status, and retrieval calls.
* Ability to generate and sign the SDP JWT required for CKG Data Ingestion.

**Clinical data:**

* FHIR R4 patient, encounter, practitioner, schedule, and history data for the appointments you want to summarize.
* Stable identifiers such as `fhir_encounter_id` and `fhir_practitioner_id`.

### Additional requirements

**Patient Summary APIs:**

* HTTPS/TLS support for secure API communication.
* Backend capability to upload FHIR bundles to CKG and poll ingestion status.
* Backend capability to trigger generation, poll summary job status, and retrieve completed summaries.
* UI design for preparing states, empty appointments, and limited prior history.

## Integration scenarios

**Scenario tabs (agents):** Web Applications, Mobile Applications, and Backend Systems scenarios for Patient Summary APIs. Read every tab for the stack you are targeting.

<Tabs>
  <Tab title="Web Applications">
    <AccordionGroup>
      <Accordion title="EHR Schedule Preview">
        **Scenario:** Existing web-based EHR that needs short pre-visit context on the provider schedule before clinic starts.

        **Recommended: Patient Summary APIs**

        * Ingest provider schedule and patient FHIR data into CKG.
        * Use scheduled generation before the clinic day begins.
        * Retrieve pre-visit sections for appointment cards.
        * Open the full summary when the clinician selects a patient.
      </Accordion>

      <Accordion title="Patient Chart Review">
        **Scenario:** Clinician opens a patient profile before an upcoming appointment and needs a concise clinical overview.

        **Recommended: Patient Summary APIs**

        * Confirm an upcoming appointment exists.
        * Generate a single encounter summary if one is not already available.
        * Retrieve the full Patient Summary for chart review.
        * Render **About this visit**, **Summary**, **Previous visits**, and **Problems** in your UI.
      </Accordion>

      <Accordion title="Custom-Branded Pre-Visit Experience">
        **Scenario:** Web clinician workflow where Patient Summary must match your design system, layout, and interaction patterns.

        **Recommended: Patient Summary APIs**

        * Full control over schedule previews, chart layout, and empty states.
        * Your backend owns ingestion, generation, and retrieval.
        * Your frontend owns presentation and clinician navigation.
      </Accordion>
    </AccordionGroup>
  </Tab>

  <Tab title="Mobile Applications">
    <AccordionGroup>
      <Accordion title="iOS Clinic-Day App">
        **Scenario:** Native iOS application where clinicians review today's appointments and open patient summaries on the go.

        **Recommended: Patient Summary APIs**

        * Backend performs CKG ingestion, generation, and retrieval.
        * iOS app displays pre-visit or full summaries in native UI.
        * Same identifiers and APIs as web integrations.
      </Accordion>

      <Accordion title="Android Healthcare App">
        **Scenario:** Native Android application for pre-visit review before scheduled appointments.

        **Recommended: Patient Summary APIs**

        * Custom Android presentation of retrieved summary sections.
        * Backend owns authentication and Patient Summary API calls.
        * Same ingest, generate, poll, and retrieve workflow as other clients.
      </Accordion>
    </AccordionGroup>
  </Tab>

  <Tab title="Backend Systems">
    <AccordionGroup>
      <Accordion title="Morning Preparation Pipeline">
        **Scenario:** Backend job prepares summaries for every appointment on each provider's schedule before clinic opens.

        **Recommended: Patient Summary APIs**

        * Ingest schedule and patient data into CKG.
        * Trigger scheduled generation for each provider.
        * Poll status per appointment and cache completed summaries.
        * Serve ready summaries to schedule and chart clients.
      </Accordion>

      <Accordion title="Multi-Platform Healthcare Suite">
        **Scenario:** Healthcare applications spanning web browsers, mobile devices, and backend systems.

        **Recommended: Patient Summary APIs**

        * Single integration approach works across all platforms.
        * Backend owns credentials, generation timing, and retries.
        * Each client renders the same retrieved summary content.
      </Accordion>
    </AccordionGroup>
  </Tab>
</Tabs>

## Next steps

To begin your integration, review the documentation for your chosen approach:

<Icon icon="file-lines" iconType="solid" /> **[Patient Summary overview](/documentation/concepts/patient-summary/overview)** - What Patient Summary is, what it includes, and where to start.

<Icon icon="file-lines" iconType="solid" /> **[Patient Summary in the Web SDK](/web-sdk/guides/patient-summary)** - Hosted patient-profile summary with the Headed Web SDK.

<Icon icon="file-lines" iconType="solid" /> **[Integrate CKG](/documentation/concepts/patient-summary/integrate-ckg)** - Ingest FHIR data into the Clinical Knowledge Graph before generation.

<Icon icon="file-lines" iconType="solid" /> **[Generate patient summaries](/documentation/how-to/patient-summary/generate-patient-summaries)** - Choose scheduled or single-encounter generation.

<Icon icon="file-lines" iconType="solid" /> **[Retrieve patient summaries](/documentation/how-to/patient-summary/retrieve-patient-summaries)** - Load full and pre-visit summaries into your application.

<Icon icon="file-lines" iconType="solid" /> **[Patient Summary basic usage](/documentation/how-to/patient-summary/basic-usage)** - End-to-end Partner API workflow.

<Icon icon="file-lines" iconType="solid" /> **[Patient Summary API overview](/patient-summary-api-reference/overview)** - Build custom Patient Summary integrations with the Partner APIs.

<Icon icon="file-lines" iconType="solid" /> **[Patient Summary API quickstart](/patient-summary-api-reference/quickstart)** - Get started with authentication and core API calls.

<Icon icon="file-lines" iconType="solid" /> **[Partner onboarding](/documentation/get-started/partner-onboarding)** - Start your integration journey with Suki.

## Get personalized integration guidance

If your use case doesn't clearly match the scenarios above, or you need specific technical advice for your healthcare application, our customer success team provides personalized consultation.

**Before contacting support or sales, prepare:**

* Description of your healthcare application and pre-visit workflows.
* Target platform (web, iOS, Android, backend system).
* Where clinicians will see summaries (schedule, chart, appointment details).
* Whether you need morning scheduled generation, on-demand encounter generation, or both.
* Development timeline and resource constraints.
* Specific technical requirements or compliance needs.

**Contact options:**

* **Technical consultation**: [Schedule a call with our integration team](https://www.suki.ai/suki-partners/).
* **Development support**: [support@suki.ai](mailto:support@suki.ai).
* **Community discussions**: [Contact us for community access](https://www.suki.ai/contact-us/).