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

# Integrate CKG

> Learn why the Clinical Knowledge Graph is required for Patient Summary, what FHIR data to ingest, and how to monitor ingestion

<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">
    Before generating Patient Summaries, ingest patient FHIR data into the Clinical Knowledge Graph (CKG). Patient Summary uses only the data available in CKG. Wait for ingestion to complete before triggering summary generation.
  </div>
</div>

Summaries for patients are generated from clinical data stored in the Clinical Knowledge Graph (CKG). Before you generate or retrieve summaries, upload the required <Tooltip tip="Fast Healthcare Interoperability Resources. An HL7 standard for exchanging healthcare data as structured resources (for example Patient or Encounter)." cta="View in Glossary" href="/Glossary/f">FHIR</Tooltip> data into CKG and confirm that ingestion has completed.

A typical integration follows this workflow:

* Collect FHIR data from your EMR or interoperability layer.
* Upload the data to CKG.
* Monitor ingestion until processing completes.
* Generate Patient Summaries.

## Why CKG is required

Patient Summary generates summaries only from data stored in CKG. It does not retrieve clinical data directly from your EMR during summary generation.

Using CKG enables Suki to:

* Generate summaries from a consistent clinical dataset.
* Use the same patient, practitioner, and encounter identifiers throughout the workflow.
* Process summary generation independently of your EMR.
* Generate structured summary sections such as Summary, Previous visits, and Problems.

<Note>
  If the ingested data is incomplete, outdated, or uses inconsistent identifiers, the generated summary quality is impacted.
</Note>

## What data to ingest

Before ingesting data, review the following FHIR resources and determine which ones are required to generate summaries. Upload **FHIR R4 bundles** that contain the clinical data required to generate summaries.

| Data                            | Purpose                                                                                    |
| :------------------------------ | :----------------------------------------------------------------------------------------- |
| **Patient**                     | Identifies the patient.                                                                    |
| **Practitioner**                | Associates the summary with the correct provider.                                          |
| **Encounter / Appointment**     | Associates the summary with an upcoming visit.                                             |
| **Provider schedule**           | Supports scheduled summary generation.                                                     |
| **Prior visit history**         | Generates the Summary and Previous visits sections.                                        |
| **Active problems**             | Generates the Problems section.                                                            |
| **Additional clinical history** | Improves summary quality, including medications, observations, and other relevant records. |

### FHIR bundle requirements

During CKG data ingestion, your FHIR bundle must meet the following requirements before you upload it:

| Requirement          | Description                                           |
| :------------------- | :---------------------------------------------------- |
| Valid JSON           | Must parse without syntax errors.                     |
| Maximum size         | You can upload a bundle up to **500 MB** in size.     |
| Resource size        | Each FHIR resource can be up to **10 MB** in size.    |
| Binary resource size | Binary resources can be up to **40 MB** in size.      |
| Multiple patients    | Bundles can include resources from multiple patients. |
| No DELETE operations | Bundle entries must not use the **DELETE** method.    |

### Required identifiers

Keep patient, practitioner, and encounter identifiers consistent between the FHIR data you ingest into CKG and the generation or retrieval requests you send later.

When you generate or retrieve a summary by partner identifiers, use:

* `fhir_encounter_id` - Encounter identifier. Must match the identifier in the ingested FHIR data.
* `fhir_practitioner_id` - Practitioner identifier. Must match the identifier in the ingested FHIR data.

Refer to the following endpoints to learn more:

<div className="doc-guide-btn-row">
  <a href="/patient-summary-api-reference/summary-generation/encounter-summary" className="doc-guide-btn">
    Generate Patient Summary for an Encounter
  </a>

  <a href="/patient-summary-api-reference/summaries/encounter-practitioner" className="doc-guide-btn">
    Patient Summary by Encounter & Practitioner IDs
  </a>
</div>

## Ingestion workflow

The following diagram shows the ingestion workflow.

```mermaid actions={false} theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
flowchart LR
  A["Partner application"] --> B["Request upload URL"]
  B --> C["Upload FHIR bundle"]
  C --> D["Monitor ingestion"]
  D --> E["CKG updated"]

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

The workflow consists of four steps:

<Steps>
  <Step title="Collect FHIR Data">
    Collect FHIR data for the patients and appointments you plan to generate summaries for.
  </Step>

  <Step title="Upload the FHIR Bundle">
    Request an upload URL and upload the FHIR bundle.

    Refer to [Request upload URL](/patient-summary-api-reference/ckg-data-ingestion/upload) and [Upload FHIR bundle](/patient-summary-api-reference/ckg-data-ingestion/fhir-data) APIs.
  </Step>

  <Step title="Monitor Ingestion">
    Monitor ingestion until processing completes. Refer to [Check ingestion status](/patient-summary-api-reference/ckg-data-ingestion/ingestion-status) API.
  </Step>

  <Step title="Generate Patient Summaries">
    After ingestion completes, generate Patient Summaries.
  </Step>
</Steps>

<Warning>
  Uploading a FHIR bundle only stores the data. Wait for ingestion to complete before generating summaries.
</Warning>

## Monitor ingestion

Monitor ingestion using the `transaction_id` returned when requesting the upload URL API. Continue polling until the transaction reaches a terminal status. Refer to [Check ingestion status](/patient-summary-api-reference/ckg-data-ingestion/ingestion-status) API for implementation details.

Monitoring lets you confirm that:

* The data is ready for summary generation.
* Processing completed successfully.
* Uploads can be traced using the `organization_id`, `transaction_id`, and `correlation_id`.

### Status values

Use the status field to decide what your application should do next.

| Status      | What it means                                                                         |
| :---------- | :------------------------------------------------------------------------------------ |
| `CREATED`   | The ingestion job was created and is waiting for the FHIR bundle upload.              |
| `READY`     | The FHIR bundle was uploaded and is waiting to be processed.                          |
| `RUNNING`   | Suki is processing the uploaded FHIR bundle.                                          |
| `COMPLETED` | Ingestion finished successfully. The data is available in CKG.                        |
| `FAILED`    | Ingestion failed. Check the `error` field for details, then fix and retry.            |
| `ARCHIVED`  | The upload URL expired before the FHIR bundle was uploaded. Request a new upload URL. |

<Note>
  `COMPLETED`, `FAILED`, and `ARCHIVED` are **terminal statuses**. Stop polling when you receive one of them.
</Note>

<Tip>
  Keep the following in mind:

  * Poll about every **5 seconds**.
  * Ingestion status is available for **7 days** after the last status update.
  * Start summary generation only after status is `COMPLETED`.
</Tip>

## Common issues

<AccordionGroup>
  <Accordion title="Upload URL Expired">
    **Cause:** Upload started after the URL expired.

    **Resolution:** Request a new upload URL.
  </Accordion>

  <Accordion title="Ingestion Incomplete">
    **Cause:** Summary generation started before ingestion completed.

    **Resolution:** Wait for ingestion to complete before generating summaries.
  </Accordion>

  <Accordion title="Missing Summary Content">
    **Cause:** Required clinical history was not ingested.

    **Resolution:** Upload the missing FHIR resources and generate the summary again.
  </Accordion>

  <Accordion title="Summary Not Found">
    **Cause:** Identifiers differ between ingestion and generation.

    **Resolution:** Keep identifiers consistent across the workflow.
  </Accordion>

  <Accordion title="Scheduled Generation Misses Appointments">
    **Cause:** Provider schedule was not ingested.

    **Resolution:** Upload schedule data before generating summaries.
  </Accordion>
</AccordionGroup>

## Best practices

For optimal summary generation, follow these best practices:

<Tip>
  * Ingest clinical data before generating Patient Summaries.
  * Wait for ingestion to complete before starting summary generation.
  * Keep patient, practitioner, and encounter identifiers consistent across ingestion, generation, and retrieval.
  * Upload updated clinical data whenever patient history changes.
  * Log `organization_id`, `transaction_id`, and `correlation_id` for troubleshooting.
</Tip>

## Next steps

Continue with the following guides:

* [CKG Data Ingestion APIs](/patient-summary-api-reference/ckg-data-ingestion) to upload FHIR bundles and monitor ingestion.
* [Generate patient summaries](/documentation/how-to/patient-summary/generate-patient-summaries) to start summary generation.
* [Retrieve patient summaries](/documentation/how-to/patient-summary/retrieve-patient-summaries) to display completed summaries.
* [Patient Summary architecture](/documentation/concepts/patient-summary/architecture) to understand the overall architecture.