> ## 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.
# Upload FHIR to CKG and Poll Ingestion
> Request a pre-signed upload URL, PUT a FHIR bundle, then poll ingestion until COMPLETED
export const CbRecipeMeta = ({items = []}) =>
;
};
}
sidebar={{
apiHref: "/patient-summary-api-reference/ckg-data-ingestion/upload",
authSections: [
{
title: "Partner API",
text: "Authenticate every REST call with Partner Token headers on each request. See",
href: "/documentation/get-started/partner-authentication",
linkLabel: "Partner authentication",
scopes: ["sdp_suki_token", "sdp_provider_id"],
},
],
glance: [
{ label: "Product", value: "Patient Summary" },
{ label: "Surface", value: "Partner API" },
{ label: "Time", value: "~5 min" },
{ label: "Level", value: "Beginner" },
],
}}
>
## Problem
Patient Summary generation starts before Clinical Knowledge Graph (CKG) ingestion finishes, so summaries are empty or fail. The generate endpoint expects patient, encounter, and practitioner data to already exist in CKG.
CKG ingestion is asynchronous. You must request a pre-signed upload URL, PUT the FHIR R4 bundle, then poll ingestion status until `COMPLETED` before triggering Patient Summary generation.
## Architecture
```mermaid actions={false} theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
%%{init: {'theme':'base', 'themeVariables': { 'primaryColor':'#FFFBDE','primaryTextColor':'#1C1C1C','primaryBorderColor':'#FFD147','lineColor':'#6F5410','secondaryColor':'#FFFDF5','tertiaryColor':'#FFEB94','fontSize':'13px'}}}%%
flowchart LR
A[Request upload URL] --> B[PUT FHIR bundle]
B --> C[Poll status]
C --> D[COMPLETED]
D --> E[Generate summary]
```
## Prerequisites
Completed [Partner onboarding](/documentation/get-started/partner-onboarding) and can obtain an `sdp_suki_token` from Login for CKG upload endpoints.`organization_id` and a valid FHIR R4 bundle JSON file with patient, encounter, and practitioner resources. You can use the [Example FHIR R4 bundle](/documentation/concepts/patient-summary/integrate-ckg#example-fhir-r4-bundle) if you need to understand the structure of the bundle.Matching `fhir_encounter_id` and `fhir_practitioner_id` values you will use later in Patient Summary generation.
## Solution
Request an upload URL with [Request upload URL](/patient-summary-api-reference/ckg-data-ingestion/upload), PUT the FHIR bundle, then poll [Check ingestion status](/patient-summary-api-reference/ckg-data-ingestion/ingestion-status) until `COMPLETED`. Treat `FAILED` and `ARCHIVED` as terminal.
```typescript theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
import fs from "fs";
const BASE_URL = "https://sdp.suki.ai";
async function uploadAndWaitForCkg(organizationId: string, bundlePath: string) {
const params = new URLSearchParams({
organization_id: organizationId,
correlation_id: "encounter-abc-123",
});
const urlRes = await fetch(`${BASE_URL}/api/v1/fhir-push/upload-url?${params}`, {
headers: { Authorization: `Bearer ${sdpSukiToken}` },
});
if (!urlRes.ok) {
throw new Error(`Request upload URL failed: ${urlRes.status}`);
}
const { transaction_id: transactionId, upload_url: uploadUrl } = await urlRes.json();
const bundle = fs.readFileSync(bundlePath, "utf-8");
const uploadRes = await fetch(uploadUrl, {
method: "PUT",
headers: {
"Content-Type": "application/json",
"x-goog-content-length-range": "0,524288000",
},
body: bundle,
});
if (!uploadRes.ok) {
throw new Error(`FHIR upload failed: ${uploadRes.status}`);
}
for (let i = 0; i < 120; i++) {
const statusRes = await fetch(
`${BASE_URL}/api/v1/fhir-push/status/${transactionId}`,
{ headers: { Authorization: `Bearer ${sdpSukiToken}` } }
);
if (!statusRes.ok) {
throw new Error(`Get ingestion status failed: ${statusRes.status}`);
}
const { status } = await statusRes.json();
if (status === "COMPLETED") return "COMPLETED";
if (status === "FAILED" || status === "ARCHIVED") return status;
await new Promise((r) => setTimeout(r, 5000));
}
throw new Error("Timed out waiting for CKG ingestion");
}
const outcome = await uploadAndWaitForCkg(organizationId, "my-fhir-bundle.json");
if (outcome === "COMPLETED") {
// Generate Patient Summaries
}
```
```python theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
import time
import requests
BASE_URL = "https://sdp.suki.ai"
def upload_and_wait_for_ckg(organization_id: str, bundle_path: str) -> str:
url_res = requests.get(
f"{BASE_URL}/api/v1/fhir-push/upload-url",
params={
"organization_id": organization_id,
"correlation_id": "encounter-abc-123",
},
headers={"Authorization": f"Bearer {sdp_suki_token}"},
timeout=30,
)
url_res.raise_for_status()
data = url_res.json()
transaction_id = data["transaction_id"]
upload_url = data["upload_url"]
with open(bundle_path, "rb") as f:
upload_res = requests.put(
upload_url,
headers={
"Content-Type": "application/json",
"x-goog-content-length-range": "0,524288000",
},
data=f,
timeout=300,
)
upload_res.raise_for_status()
for _ in range(120):
status_res = requests.get(
f"{BASE_URL}/api/v1/fhir-push/status/{transaction_id}",
headers={"Authorization": f"Bearer {sdp_suki_token}"},
timeout=30,
)
status_res.raise_for_status()
status = status_res.json().get("status")
if status == "COMPLETED":
return "COMPLETED"
if status in ("FAILED", "ARCHIVED"):
return status
time.sleep(5)
raise TimeoutError("Timed out waiting for CKG ingestion")
outcome = upload_and_wait_for_ckg(organization_id, "my-fhir-bundle.json")
if outcome == "COMPLETED":
# Generate Patient Summaries
pass
```
Call [Request upload URL](/patient-summary-api-reference/ckg-data-ingestion/upload) with your `organization_id` (your partner organization ID for that org. It can be a UUID or non-UUID string. But not a Suki UUID.) and a `correlation_id`. Authenticate with the same `sdp_suki_token` from Login.
Upload the bundle JSON to the pre-signed URL within **15 minutes**. Include `Content-Type: application/json` and the required content-length header. Refer to [Example FHIR R4 bundle](/documentation/concepts/patient-summary/integrate-ckg#example-fhir-r4-bundle) if you need sample data.
Poll [Check ingestion status](/patient-summary-api-reference/ckg-data-ingestion/ingestion-status) with the returned `transaction_id` until status is `COMPLETED`, `FAILED`, or `ARCHIVED`.
Only after `COMPLETED`, call [Generate a Patient Summary for one encounter](/documentation/cookbooks/generate-patient-summary-for-encounter).
## Try it
* **Status reaches COMPLETED**
After a successful PUT, polling should eventually return `COMPLETED`. If status stays pending, confirm the bundle uploaded before the URL expired.
* **Terminal failures stop the loop**
`FAILED` and `ARCHIVED` are terminal. Do not retry generation until you fix the bundle or re-upload.
* **Identifiers match downstream calls**
Patient, encounter, and practitioner IDs in the FHIR bundle must match the `fhir_encounter_id` and `fhir_practitioner_id` you pass to generate.
## Common mistakes
* Starting generation before ingestion status is `COMPLETED`.
* Letting the upload URL expire (**15 minutes**) before the PUT.
* Using different identifiers in the FHIR bundle than later `fhir_encounter_id` / `fhir_practitioner_id` values.
* Using a different token for CKG upload than the `sdp_suki_token` from Login.
## Related cookbooks
Trigger generation and save the ID.
Poll until status is COMPLETED.