Patient Summary API Quickstart

This quickstart walks you through one successful Patient Summary workflow on staging: upload FHIR data to CKG, authenticate, trigger summary generation for an encounter, poll job status, and retrieve the Patient Summary. Your application owns FHIR upload data orchestration, summary generation triggers, job status polling, and how retrieved summaries are presented or integrated into your product. What you will do

Upload FHIR data to CKG with an SDP JWT bearer token and poll ingestion status.
Authenticate to get an sdp_suki_token (and register the user if needed).
Trigger summary generation for an encounter.
Poll job status until complete and retrieve the full summary or pre-visit summary.

Prefer one paste-ready file? Use the Complete staging script in the preferred language below, then follow the numbered steps for the same flow with full explanations.

Using an AI coding tool?Copy the prompt below to point your agent at the Patient Summary skill and Documentation MCP. For every task skill, refer to AI coding tools.

Fetch the Patient Summary skill and connect the documentation MCP.

Open in Cursor

Access and credentials

You need partner credentials to use the Suki Patient Summary APIs. Contact our Partnership team to get your credentials. They will guide you through the Onboarding process and provide what you need to get started.

Prerequisites

To use the Suki Patient Summary APIs, you must have the following:

Partner credentials for Suki authentication endpoints (partner_id and partner_token).
Ability to generate and sign RS256 SDP JWT bearer tokens for CKG Data Ingestion endpoints.
FHIR R4 bundles containing patient clinical data (conditions, medications, encounters, observations).
A publicly accessible endpoint (or Okta authorization server) for token validation.

Environments to use for development and testing

This guide uses https://sdp.suki-stage.com for API examples (staging).

Important:

The production environment is https://sdp.suki.ai.
The staging environment is https://sdp.suki-stage.com.
Your partnership team will confirm which environment, base URL, and credentials apply for your integration.

Complete staging script

Replace the credential placeholders, put a FHIR R4 bundle at patient-fhir-bundle.json, then run. For detailed explanations of each step, refer to the numbered steps below.

Python: pip install requests then python patient_summary_staging.py.
TypeScript (Node): npx tsx patient_summary_staging.ts (Node 18+).

# patient_summary_staging.py
# Flow: upload FHIR → login (register once if needed) → trigger generation → poll → retrieve summary
# pip install requests

import json
import time
from typing import Any, Optional

import requests

BASE_URL = "https://sdp.suki-stage.com"

# Replace these with your credentials
SDP_TOKEN = "YOUR_SDP_JWT_BEARER_TOKEN"  # RS256 signed, includes sdp_partner_id claim
PARTNER_ID = "your-partner-id"
PARTNER_TOKEN = "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..."  # Keep on your backend only
PROVIDER_ID = "provider-123"  # Optional; required for some auth flows
SDP_PROVIDER_ID = ""  # Leave empty unless your partnership requires sdp_provider_id

# CKG identifiers
ORG_ID = "your-organization-id"
CORRELATION_ID = "encounter-abc-123"

# FHIR identifiers (must match IDs in your FHIR bundle)
FHIR_ENCOUNTER_ID = "encounter-123"
FHIR_PRACTITIONER_ID = "practitioner-456"
FHIR_BUNDLE_PATH = "patient-fhir-bundle.json"


def expect_status(response: requests.Response, url: str, want: int) -> None:
    if response.status_code == want:
        return
    detail = (response.text or "")[:500]
    try:
        body = response.json()
        if isinstance(body, dict) and body.get("message"):
            detail = str(body["message"])
    except ValueError:
        pass
    raise RuntimeError(f"HTTP {response.status_code} {url}: {detail}")


def ckg_headers() -> dict[str, str]:
    return {"Authorization": f"Bearer {SDP_TOKEN}"}


def rest_headers(suki_token: str) -> dict[str, str]:
    headers = {
        "sdp_suki_token": suki_token,
        "Content-Type": "application/json",
    }
    if SDP_PROVIDER_ID:
        headers["sdp_provider_id"] = SDP_PROVIDER_ID
    return headers


def request_upload_url(org_id: str, correlation_id: str) -> dict[str, str]:
    url = f"{BASE_URL}/api/v1/fhir-push/upload-url"
    r = requests.get(
        url,
        params={"organization_id": org_id, "correlation_id": correlation_id},
        headers=ckg_headers(),
        timeout=60,
    )
    expect_status(r, url, 200)
    data = r.json()
    return {"transaction_id": data["transaction_id"], "upload_url": data["upload_url"]}


def upload_fhir_bundle(upload_url: str, bundle_path: str) -> None:
    with open(bundle_path, "rb") as f:
        bundle_data = f.read()
    r = requests.put(
        upload_url,
        data=bundle_data,
        headers={
            "Content-Type": "application/json",
            "x-goog-content-length-range": "0,524288000",
        },
        timeout=300,
    )
    if r.status_code not in (200, 204):
        raise RuntimeError(f"Upload failed: {r.status_code} {r.text}")


def poll_ingestion_status(transaction_id: str) -> str:
    url = f"{BASE_URL}/api/v1/fhir-push/status/{transaction_id}"
    while True:
        r = requests.get(url, headers=ckg_headers(), timeout=60)
        expect_status(r, url, 200)
        status = r.json()["status"]
        print("CKG ingestion status:", status)
        if status == "COMPLETED":
            return status
        if status in ("FAILED", "ARCHIVED"):
            raise RuntimeError(f"Ingestion failed: {status}")
        time.sleep(5)


def login(partner_id: str, partner_token: str, provider_id: Optional[str] = None) -> str:
    url = f"{BASE_URL}/api/v1/auth/login"
    payload: dict[str, Any] = {"partner_id": partner_id, "partner_token": partner_token}
    if provider_id:
        payload["provider_id"] = provider_id
    r = requests.post(url, json=payload, timeout=60)
    expect_status(r, url, 200)
    token = r.json().get("suki_token")
    if not token:
        raise RuntimeError("login response missing suki_token")
    return token


def register_provider(
    partner_id: str,
    partner_token: str,
    provider_name: str,
    provider_org_id: str,
    provider_id: Optional[str] = None,
) -> None:
    url = f"{BASE_URL}/api/v1/auth/register"
    payload: dict[str, Any] = {
        "partner_id": partner_id,
        "partner_token": partner_token,
        "provider_name": provider_name,
        "provider_org_id": provider_org_id,
    }
    if provider_id:
        payload["provider_id"] = provider_id
    r = requests.post(url, json=payload, timeout=60)
    if r.status_code not in (201, 409):
        expect_status(r, url, 201)


def login_with_register_fallback(
    partner_id: str,
    partner_token: str,
    provider_id: Optional[str],
    provider_name: str,
    provider_org_id: str,
) -> str:
    try:
        return login(partner_id, partner_token, provider_id)
    except RuntimeError as err:
        if "provider_not_registered" not in str(err):
            raise
        register_provider(
            partner_id, partner_token, provider_name, provider_org_id, provider_id
        )
        return login(partner_id, partner_token, provider_id)


def trigger_summary_generation(
    suki_token: str, fhir_encounter_id: str, fhir_practitioner_id: str
) -> None:
    url = f"{BASE_URL}/api/v1/patient-summary/generate/encounter"
    payload = {
        "fhir_encounter_id": fhir_encounter_id,
        "fhir_practitioner_id": fhir_practitioner_id,
    }
    r = requests.post(url, headers=rest_headers(suki_token), json=payload, timeout=60)
    expect_status(r, url, 202)


def poll_summary_status(
    suki_token: str, fhir_encounter_id: str, fhir_practitioner_id: str
) -> str:
    url = f"{BASE_URL}/api/v1/patient-summary/encounter/{fhir_encounter_id}/practitioner/{fhir_practitioner_id}/status"
    while True:
        r = requests.get(url, headers=rest_headers(suki_token), timeout=60)
        expect_status(r, url, 200)
        status = r.json()["status"]
        print("Summary generation status:", status)
        if status == "COMPLETED":
            return status
        if status == "FAILED":
            raise RuntimeError(f"Generation failed: {status}")
        time.sleep(5)


def get_patient_summary(
    suki_token: str, fhir_encounter_id: str, fhir_practitioner_id: str
) -> Any:
    url = f"{BASE_URL}/api/v1/patient-summary/encounter/{fhir_encounter_id}/practitioner/{fhir_practitioner_id}"
    r = requests.get(url, headers=rest_headers(suki_token), timeout=60)
    expect_status(r, url, 200)
    return r.json()


if __name__ == "__main__":
    print("Step 1: Upload FHIR data to CKG")
    upload_info = request_upload_url(ORG_ID, CORRELATION_ID)
    transaction_id = upload_info["transaction_id"]
    print("Transaction ID:", transaction_id)

    upload_fhir_bundle(upload_info["upload_url"], FHIR_BUNDLE_PATH)
    print("FHIR bundle uploaded")

    poll_ingestion_status(transaction_id)
    print("Ingestion completed")

    print("Step 2: Authenticate")
    suki_token = login_with_register_fallback(
        PARTNER_ID,
        PARTNER_TOKEN,
        PROVIDER_ID,
        provider_name="Dr. Jane Smith",
        provider_org_id="org-456",
    )
    print("Authenticated")

    print("Step 3: Trigger summary generation")
    trigger_summary_generation(suki_token, FHIR_ENCOUNTER_ID, FHIR_PRACTITIONER_ID)
    print("Generation triggered")

    print("Step 4: Poll generation status")
    poll_summary_status(suki_token, FHIR_ENCOUNTER_ID, FHIR_PRACTITIONER_ID)
    print("Generation completed")

    print("Step 5: Retrieve Patient Summary")
    summary = get_patient_summary(suki_token, FHIR_ENCOUNTER_ID, FHIR_PRACTITIONER_ID)
    print(json.dumps(summary, indent=2))

// patient_summary_staging.ts
// Flow: upload FHIR → login (register once if needed) → trigger generation → poll → retrieve summary
// Node 18+: npx tsx patient_summary_staging.ts

import fs from "node:fs";

const BASE_URL = "https://sdp.suki-stage.com";

// Replace these with your credentials
const SDP_TOKEN = "YOUR_SDP_JWT_BEARER_TOKEN"; // RS256 signed, includes sdp_partner_id claim
const PARTNER_ID = "your-partner-id";
const PARTNER_TOKEN = "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..."; // Keep on your backend only
const PROVIDER_ID = "provider-123"; // Optional; required for some auth flows
const SDP_PROVIDER_ID = ""; // Leave empty unless your partnership requires sdp_provider_id

// CKG identifiers
const ORG_ID = "your-organization-id";
const CORRELATION_ID = "encounter-abc-123";

// FHIR identifiers (must match IDs in your FHIR bundle)
const FHIR_ENCOUNTER_ID = "encounter-123";
const FHIR_PRACTITIONER_ID = "practitioner-456";
const FHIR_BUNDLE_PATH = "patient-fhir-bundle.json";

function ckgHeaders(): Record<string, string> {
  return { Authorization: `Bearer ${SDP_TOKEN}` };
}

function restHeaders(sukiToken: string): Record<string, string> {
  const headers: Record<string, string> = {
    sdp_suki_token: sukiToken,
    "Content-Type": "application/json",
  };
  if (SDP_PROVIDER_ID) headers.sdp_provider_id = SDP_PROVIDER_ID;
  return headers;
}

async function expectStatus(response: Response, url: string, want: number): Promise<void> {
  if (response.status === want) return;
  const raw = await response.text();
  let detail = raw.slice(0, 500);
  try {
    const body = JSON.parse(raw);
    if (body?.message) detail = String(body.message);
  } catch {
    // keep raw text
  }
  throw new Error(`HTTP ${response.status} ${url}: ${detail}`);
}

async function requestUploadUrl(
  orgId: string,
  correlationId: string,
): Promise<{ transactionId: string; uploadUrl: string }> {
  const url = `${BASE_URL}/api/v1/fhir-push/upload-url?organization_id=${encodeURIComponent(orgId)}&correlation_id=${encodeURIComponent(correlationId)}`;
  const response = await fetch(url, { headers: ckgHeaders() });
  await expectStatus(response, url, 200);
  const data = (await response.json()) as {
    transaction_id: string;
    upload_url: string;
  };
  return { transactionId: data.transaction_id, uploadUrl: data.upload_url };
}

async function uploadFhirBundle(uploadUrl: string, bundlePath: string): Promise<void> {
  const bundleData = fs.readFileSync(bundlePath);
  const response = await fetch(uploadUrl, {
    method: "PUT",
    headers: {
      "Content-Type": "application/json",
      "x-goog-content-length-range": "0,524288000",
    },
    body: bundleData,
  });
  if (response.status !== 200 && response.status !== 204) {
    throw new Error(`Upload failed: ${response.status} ${await response.text()}`);
  }
}

async function pollIngestionStatus(transactionId: string): Promise<string> {
  const url = `${BASE_URL}/api/v1/fhir-push/status/${transactionId}`;
  for (;;) {
    const response = await fetch(url, { headers: ckgHeaders() });
    await expectStatus(response, url, 200);
    const data = (await response.json()) as { status: string };
    console.log("CKG ingestion status:", data.status);
    if (data.status === "COMPLETED") return data.status;
    if (data.status === "FAILED" || data.status === "ARCHIVED") {
      throw new Error(`Ingestion failed: ${data.status}`);
    }
    await new Promise((r) => setTimeout(r, 5000));
  }
}

async function login(
  partnerId: string,
  partnerToken: string,
  providerId?: string,
): Promise<string> {
  const url = `${BASE_URL}/api/v1/auth/login`;
  const body: Record<string, string> = {
    partner_id: partnerId,
    partner_token: partnerToken,
  };
  if (providerId) body.provider_id = providerId;

  const response = await fetch(url, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify(body),
  });
  await expectStatus(response, url, 200);
  const data = (await response.json()) as { suki_token?: string };
  if (!data.suki_token) throw new Error("login response missing suki_token");
  return data.suki_token;
}

async function registerProvider(input: {
  partnerId: string;
  partnerToken: string;
  providerName: string;
  providerOrgId: string;
  providerId?: string;
}): Promise<void> {
  const url = `${BASE_URL}/api/v1/auth/register`;
  const body: Record<string, string> = {
    partner_id: input.partnerId,
    partner_token: input.partnerToken,
    provider_name: input.providerName,
    provider_org_id: input.providerOrgId,
  };
  if (input.providerId) body.provider_id = input.providerId;

  const response = await fetch(url, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify(body),
  });
  if (response.status !== 201 && response.status !== 409) {
    await expectStatus(response, url, 201);
  }
}

async function loginWithRegisterFallback(
  partnerId: string,
  partnerToken: string,
  providerId: string | undefined,
  providerName: string,
  providerOrgId: string,
): Promise<string> {
  try {
    return await login(partnerId, partnerToken, providerId);
  } catch (err) {
    if (!String(err).includes("provider_not_registered")) throw err;
    await registerProvider({
      partnerId,
      partnerToken,
      providerName,
      providerOrgId,
      providerId,
    });
    return login(partnerId, partnerToken, providerId);
  }
}

async function triggerSummaryGeneration(
  sukiToken: string,
  fhirEncounterId: string,
  fhirPractitionerId: string,
): Promise<void> {
  const url = `${BASE_URL}/api/v1/patient-summary/generate/encounter`;
  const response = await fetch(url, {
    method: "POST",
    headers: restHeaders(sukiToken),
    body: JSON.stringify({
      fhir_encounter_id: fhirEncounterId,
      fhir_practitioner_id: fhirPractitionerId,
    }),
  });
  await expectStatus(response, url, 202);
}

async function pollSummaryStatus(
  sukiToken: string,
  fhirEncounterId: string,
  fhirPractitionerId: string,
): Promise<string> {
  const url = `${BASE_URL}/api/v1/patient-summary/encounter/${fhirEncounterId}/practitioner/${fhirPractitionerId}/status`;
  for (;;) {
    const response = await fetch(url, { headers: restHeaders(sukiToken) });
    await expectStatus(response, url, 200);
    const data = (await response.json()) as { status: string };
    console.log("Summary generation status:", data.status);
    if (data.status === "COMPLETED") return data.status;
    if (data.status === "FAILED") {
      throw new Error(`Generation failed: ${data.status}`);
    }
    await new Promise((r) => setTimeout(r, 5000));
  }
}

async function getPatientSummary(
  sukiToken: string,
  fhirEncounterId: string,
  fhirPractitionerId: string,
): Promise<unknown> {
  const url = `${BASE_URL}/api/v1/patient-summary/encounter/${fhirEncounterId}/practitioner/${fhirPractitionerId}`;
  const response = await fetch(url, { headers: restHeaders(sukiToken) });
  await expectStatus(response, url, 200);
  return response.json();
}

async function main() {
  console.log("Step 1: Upload FHIR data to CKG");
  const uploadInfo = await requestUploadUrl(ORG_ID, CORRELATION_ID);
  console.log("Transaction ID:", uploadInfo.transactionId);

  await uploadFhirBundle(uploadInfo.uploadUrl, FHIR_BUNDLE_PATH);
  console.log("FHIR bundle uploaded");

  await pollIngestionStatus(uploadInfo.transactionId);
  console.log("Ingestion completed");

  console.log("Step 2: Authenticate");
  const sukiToken = await loginWithRegisterFallback(
    PARTNER_ID,
    PARTNER_TOKEN,
    PROVIDER_ID,
    "Dr. Jane Smith",
    "org-456",
  );
  console.log("Authenticated");

  console.log("Step 3: Trigger summary generation");
  await triggerSummaryGeneration(sukiToken, FHIR_ENCOUNTER_ID, FHIR_PRACTITIONER_ID);
  console.log("Generation triggered");

  console.log("Step 4: Poll generation status");
  await pollSummaryStatus(sukiToken, FHIR_ENCOUNTER_ID, FHIR_PRACTITIONER_ID);
  console.log("Generation completed");

  console.log("Step 5: Retrieve Patient Summary");
  const summary = await getPatientSummary(
    sukiToken,
    FHIR_ENCOUNTER_ID,
    FHIR_PRACTITIONER_ID,
  );
  console.log(JSON.stringify(summary, null, 2));
}

main().catch((err) => {
  console.error(err);
  process.exit(1);
});

Steps

Upload FHIR data to CKG

Step 1:Before you can generate Patient Summaries, you must upload FHIR data to Suki’s Clinical Knowledge Graph (CKG). Call Request upload URL API with the following query parameters:

organization_id (required): Your organization identifier.
correlation_id (optional): Client-supplied identifier for tracing (max 128 characters).

Step 2:Upload your FHIR R4 bundle JSON to the upload_url using HTTP PUT with Content-Type: application/json and x-goog-content-length-range: 0,524288000.

You can upload a bundle up to 500 MB in size.

Step 3:Poll Poll ingestion status API to know the status of the ingestion job.

Your FHIR bundle must include patient, encounter, and practitioner identifiers that match what you will use when triggering summary generation in Step 3.

Code example:

const BASE_URL = "https://sdp.suki-stage.com";
const SDP_TOKEN = "<YOUR_SDP_JWT_BEARER_TOKEN>";
const ORG_ID = "your-organization-id";
const CORRELATION_ID = "encounter-abc-123";

// Step 1a: Request upload URL
const uploadUrlResponse = await fetch(
  `${BASE_URL}/api/v1/fhir-push/upload-url?organization_id=${encodeURIComponent(ORG_ID)}&correlation_id=${encodeURIComponent(CORRELATION_ID)}`,
  { headers: { Authorization: `Bearer ${SDP_TOKEN}` } },
);
const uploadData = await uploadUrlResponse.json();
if (!uploadUrlResponse.ok) {
  throw new Error(`Upload URL request failed: ${uploadUrlResponse.status}`);
}
const transactionId = uploadData.transaction_id as string;
const uploadUrl = uploadData.upload_url as string;
console.log("Transaction ID:", transactionId);

// Step 1b: Upload FHIR bundle
// Guard: ensure we received a transaction ID and upload URL before uploading.
if (!transactionId || !uploadUrl) {
  throw new Error(`Upload URL response missing transaction_id or upload_url: ${JSON.stringify(uploadData)}`);
}

// For large bundles (hundreds of MB), prefer streaming the file to the upload URL
// instead of readFileSync to avoid high memory usage in production.
const fhirBundle = fs.readFileSync("patient-fhir-bundle.json");
const uploadResponse = await fetch(uploadUrl, {
  method: "PUT",
  headers: {
    "Content-Type": "application/json",
    "x-goog-content-length-range": "0,524288000",
  },
  body: fhirBundle,
});
if (uploadResponse.status !== 200 && uploadResponse.status !== 204) {
  throw new Error(`Upload failed: ${uploadResponse.status}`);
}
console.log("FHIR bundle uploaded");

// Step 1c: Poll ingestion status
for (;;) {
  const statusResponse = await fetch(
    `${BASE_URL}/api/v1/fhir-push/status/${transactionId}`,
    { headers: { Authorization: `Bearer ${SDP_TOKEN}` } },
  );
  const statusData = (await statusResponse.json()) as { status: string };
  console.log("CKG ingestion status:", statusData.status);
  if (statusData.status === "COMPLETED") break;
  if (statusData.status === "FAILED" || statusData.status === "ARCHIVED") {
    throw new Error(`Ingestion failed: ${statusData.status}`);
  }
  await new Promise((r) => setTimeout(r, 5000));
}

import requests
import time

BASE_URL = "https://sdp.suki-stage.com"
SDP_TOKEN = "<YOUR_SDP_JWT_BEARER_TOKEN>"
ORG_ID = "your-organization-id"
CORRELATION_ID = "encounter-abc-123"

# Step 1a: Request upload URL
upload_url_response = requests.get(
    f"{BASE_URL}/api/v1/fhir-push/upload-url",
    params={"organization_id": ORG_ID, "correlation_id": CORRELATION_ID},
    headers={"Authorization": f"Bearer {SDP_TOKEN}"},
    timeout=60,
)
if upload_url_response.status_code != 200:
    raise RuntimeError(f"Upload URL request failed: {upload_url_response.status_code}")
upload_data = upload_url_response.json()
transaction_id = upload_data["transaction_id"]
upload_url = upload_data["upload_url"]
print("Transaction ID:", transaction_id)

# Step 1b: Upload FHIR bundle
with open("patient-fhir-bundle.json", "rb") as f:
    fhir_bundle = f.read()
upload_response = requests.put(
    upload_url,
    data=fhir_bundle,
    headers={
        "Content-Type": "application/json",
        "x-goog-content-length-range": "0,524288000",
    },
    timeout=300,
)
if upload_response.status_code not in (200, 204):
    raise RuntimeError(f"Upload failed: {upload_response.status_code}")
print("FHIR bundle uploaded")

# Step 1c: Poll ingestion status
while True:
    status_response = requests.get(
        f"{BASE_URL}/api/v1/fhir-push/status/{transaction_id}",
        headers={"Authorization": f"Bearer {SDP_TOKEN}"},
        timeout=60,
    )
    status_data = status_response.json()
    print("CKG ingestion status:", status_data["status"])
    if status_data["status"] == "COMPLETED":
        break
    if status_data["status"] in ("FAILED", "ARCHIVED"):
        raise RuntimeError(f"Ingestion failed: {status_data['status']}")
    time.sleep(5)

# Set your credentials
export SDP_TOKEN="<your-sdp-jwt>"
export ORG_ID="<your-organization-uuid>"
export BASE="https://sdp.suki-stage.com"

# Step 1: Request an upload URL
RESP=$(curl -s -G "${BASE}/api/v1/fhir-push/upload-url" \
  --data-urlencode "organization_id=${ORG_ID}" \
  --data-urlencode "correlation_id=encounter-abc-123" \
  -H "Authorization: Bearer ${SDP_TOKEN}")
echo "Raw response: $RESP"
TXN_ID=$(echo "$RESP" | jq -r '.transaction_id')
UPLOAD_URL=$(echo "$RESP" | jq -r '.upload_url')
echo "Transaction ID: $TXN_ID"
if [[ "$TXN_ID" == "null" || -z "$TXN_ID" ]]; then
  echo "ERROR: Failed to get upload URL. Response was:"
  echo "$RESP" | jq .
  exit 1
fi

# Step 2: Upload your FHIR bundle
curl -s -X PUT "$UPLOAD_URL" \
  -H "Content-Type: application/json" \
  -H "x-goog-content-length-range: 0,524288000" \
  --data-binary @patient-fhir-bundle.json
echo "Upload complete. Polling status..."

# Step 3: Poll until terminal status
while true; do
  STATUS=$(curl -s "${BASE}/api/v1/fhir-push/status/${TXN_ID}" \
    -H "Authorization: Bearer ${SDP_TOKEN}")
  STATE=$(echo "$STATUS" | jq -r '.status')
  echo "Current status: $STATE"
  if [[ "$STATE" == "COMPLETED" || "$STATE" == "FAILED" || "$STATE" == "ARCHIVED" ]]; then
    echo "Final result:"
    echo "$STATUS" | jq .
    break
  fi
  sleep 5
done

Authenticate to Get a Suki Token

Send a POST request to the Login API endpoint with the following parameters in the request body:

partner_id (required): Your unique , which we provide to you securely offline.
partner_token (required): The user’s OAuth 2.0 ID token () from your identity provider.
provider_id (optional): Unique identifier for the . Required for some authentication flows only.

Handling an unregistered user:

If the user is not yet registered in our system, the /login request will fail.
In this case, you must first call the Register API endpoint to create the user, then call /login again.
You only need to call the register endpoint once for each new user.
Refer to the Register API reference for the full specification.

Code example:

const BASE_URL = "https://sdp.suki-stage.com";

const response = await fetch(`${BASE_URL}/api/v1/auth/login`, {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    partner_id: "your-partner-id",
    partner_token: "your-jwt-token",
    provider_id: "provider-123", // Omit if your partnership does not require it
  }),
});

const data = await response.json();
if (!response.ok) {
  throw new Error(`Login failed: ${response.status} ${JSON.stringify(data)}`);
}
if (!data.suki_token) throw new Error("login response missing suki_token");

const sukiToken = data.suki_token as string;
console.log("suki_token:", sukiToken);

import requests

BASE_URL = "https://sdp.suki-stage.com"

response = requests.post(
    f"{BASE_URL}/api/v1/auth/login",
    json={
        "partner_id": "your-partner-id",
        "partner_token": "your-jwt-token",
        "provider_id": "provider-123",  # Omit if your partnership does not require it
    },
    timeout=60,
)
if response.status_code != 200:
    raise RuntimeError(f"Login failed: {response.status_code} {response.text}")

suki_token = response.json()["suki_token"]
print("suki_token:", suki_token)

curl -X POST https://sdp.suki-stage.com/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "partner_id": "your-partner-id",
    "partner_token": "your-jwt-token",
    "provider_id": "provider-123"
  }'

Save the suki_token from the response. This token is valid for 1 hour. When it is about to expire, you can get a new one by making the same POST request to /login with a valid partner_token.

Trigger Patient Summary Generation for an Encounter

Send a POST request to the Trigger Patient Summary Generation for an Encounter with the following parameters in the request body:

fhir_encounter_id (required): The FHIR encounter identifier from your uploaded FHIR bundle.
fhir_practitioner_id (required): The FHIR practitioner identifier from your uploaded FHIR bundle.

Code example:

const BASE_URL = "https://sdp.suki-stage.com";
const sukiToken = "<sdp_suki_token from login>";
const sdpProviderId = ""; // Set only if your partnership requires it
const FHIR_ENCOUNTER_ID = "encounter-123";
const FHIR_PRACTITIONER_ID = "practitioner-456";

const headers: Record<string, string> = {
  "Content-Type": "application/json",
  sdp_suki_token: sukiToken,
};
if (sdpProviderId) headers.sdp_provider_id = sdpProviderId;

const generateResponse = await fetch(
  `${BASE_URL}/api/v1/patient-summary/generate/encounter`,
  {
    method: "POST",
    headers,
    body: JSON.stringify({
      fhir_encounter_id: FHIR_ENCOUNTER_ID,
      fhir_practitioner_id: FHIR_PRACTITIONER_ID,
    }),
  },
);

if (generateResponse.status !== 202) {
  const err = await generateResponse.json();
  throw new Error(`Generate failed: ${generateResponse.status} ${JSON.stringify(err)}`);
}
console.log("Generation triggered");

import requests

BASE_URL = "https://sdp.suki-stage.com"
suki_token = "<sdp_suki_token from login>"
sdp_provider_id = ""  # Set only if your partnership requires it
FHIR_ENCOUNTER_ID = "encounter-123"
FHIR_PRACTITIONER_ID = "practitioner-456"

headers = {
    "sdp_suki_token": suki_token,
    "Content-Type": "application/json",
}
if sdp_provider_id:
    headers["sdp_provider_id"] = sdp_provider_id

generate_response = requests.post(
    f"{BASE_URL}/api/v1/patient-summary/generate/encounter",
    headers=headers,
    json={
        "fhir_encounter_id": FHIR_ENCOUNTER_ID,
        "fhir_practitioner_id": FHIR_PRACTITIONER_ID,
    },
    timeout=60,
)
if generate_response.status_code != 202:
    raise RuntimeError(
        f"Generate failed: {generate_response.status_code} {generate_response.text}"
    )
print("Generation triggered")

curl --request POST \
  --url https://sdp.suki-stage.com/api/v1/patient-summary/generate/encounter \
  --header 'Content-Type: application/json' \
  --header 'sdp_suki_token: <sdp_suki_token>' \
  --header 'sdp_provider_id: <sdp_provider_id>' \
  --data '{"fhir_encounter_id":"enc-123","fhir_practitioner_id":"pract-456"}'

Poll Summary Generation Status

Poll Summary Generation Status API for an Encounter until the status field reaches a terminal state. Terminal statuses include COMPLETED, FAILED, and others documented in the API reference.

Poll at reasonable intervals (for example every 5 seconds). Summary generation typically completes within a few seconds to a few minutes depending on the amount of FHIR data.

const BASE_URL = "https://sdp.suki-stage.com";
const sukiToken = "<sdp_suki_token from login>";
const sdpProviderId = ""; // Set only if your partnership requires it
const FHIR_ENCOUNTER_ID = "encounter-123";
const FHIR_PRACTITIONER_ID = "practitioner-456";

const headers: Record<string, string> = { sdp_suki_token: sukiToken };
if (sdpProviderId) headers.sdp_provider_id = sdpProviderId;

for (;;) {
  const statusResponse = await fetch(
    `${BASE_URL}/api/v1/patient-summary/encounter/${FHIR_ENCOUNTER_ID}/practitioner/${FHIR_PRACTITIONER_ID}/status`,
    { headers },
  );
  const statusData = (await statusResponse.json()) as { status: string };
  console.log("Summary generation status:", statusData.status);

  if (statusData.status === "COMPLETED") break;
  if (statusData.status === "FAILED") {
    throw new Error(`Generation failed: ${statusData.status}`);
  }
  await new Promise((r) => setTimeout(r, 5000));
}

import requests
import time

BASE_URL = "https://sdp.suki-stage.com"
suki_token = "<sdp_suki_token from login>"
sdp_provider_id = ""  # Set only if your partnership requires it
FHIR_ENCOUNTER_ID = "encounter-123"
FHIR_PRACTITIONER_ID = "practitioner-456"

headers = {"sdp_suki_token": suki_token}
if sdp_provider_id:
    headers["sdp_provider_id"] = sdp_provider_id

while True:
    status_response = requests.get(
        f"{BASE_URL}/api/v1/patient-summary/encounter/{FHIR_ENCOUNTER_ID}/practitioner/{FHIR_PRACTITIONER_ID}/status",
        headers=headers,
        timeout=60,
    )
    status_data = status_response.json()
    print("Summary generation status:", status_data["status"])

    if status_data["status"] == "COMPLETED":
        break
    if status_data["status"] == "FAILED":
        raise RuntimeError(f"Generation failed: {status_data['status']}")
    time.sleep(5)

curl --request GET \
  --url https://sdp.suki-stage.com/api/v1/patient-summary/encounter/enc-123/practitioner/pract-456/status \
  --header 'sdp_suki_token: <sdp_suki_token>' \
  --header 'sdp_provider_id: <sdp_provider_id>'

Retrieve Generated Summaries

Once generation completes, retrieve the generated summaries. The Patient Summary APIs provide two retrieval endpoints.

Full Patient Summary: Call Retrieve Patient Summary API to get a comprehensive, structured summary containing four specific sections: About Visit, Patient Summary, Previous Visit, and Problems.
Pre-visit summary: Call Retrieve pre-visit summary API to get the exact pre-visit section from inside the full patient summary, which was created specifically for the user interface (UI) to display a preview to the provider.

const BASE_URL = "https://sdp.suki-stage.com";
const sukiToken = "<sdp_suki_token from login>";
const sdpProviderId = ""; // Set only if your partnership requires it
const FHIR_ENCOUNTER_ID = "encounter-123";
const FHIR_PRACTITIONER_ID = "practitioner-456";

const headers: Record<string, string> = { sdp_suki_token: sukiToken };
if (sdpProviderId) headers.sdp_provider_id = sdpProviderId;

// Full Patient Summary
const summaryResponse = await fetch(
  `${BASE_URL}/api/v1/patient-summary/encounter/${FHIR_ENCOUNTER_ID}/practitioner/${FHIR_PRACTITIONER_ID}`,
  { headers },
);
const summary = await summaryResponse.json();
if (!summaryResponse.ok) {
  throw new Error(`Summary failed: ${summaryResponse.status} ${JSON.stringify(summary)}`);
}
console.log(JSON.stringify(summary, null, 2));

// Pre-visit summary (optional)
const preVisitResponse = await fetch(
  `${BASE_URL}/api/v1/patient-summary/encounter/${FHIR_ENCOUNTER_ID}/practitioner/${FHIR_PRACTITIONER_ID}/pre_visit`,
  { headers },
);
const preVisit = await preVisitResponse.json();
console.log(JSON.stringify(preVisit, null, 2));

import requests

BASE_URL = "https://sdp.suki-stage.com"
suki_token = "<sdp_suki_token from login>"
sdp_provider_id = ""  # Set only if your partnership requires it
FHIR_ENCOUNTER_ID = "encounter-123"
FHIR_PRACTITIONER_ID = "practitioner-456"

headers = {"sdp_suki_token": suki_token}
if sdp_provider_id:
    headers["sdp_provider_id"] = sdp_provider_id

# Full Patient Summary
summary_response = requests.get(
    f"{BASE_URL}/api/v1/patient-summary/encounter/{FHIR_ENCOUNTER_ID}/practitioner/{FHIR_PRACTITIONER_ID}",
    headers=headers,
    timeout=60,
)
if summary_response.status_code != 200:
    raise RuntimeError(
        f"Summary failed: {summary_response.status_code} {summary_response.text}"
    )
print(summary_response.json())

# Pre-visit summary (optional)
pre_visit_response = requests.get(
    f"{BASE_URL}/api/v1/patient-summary/encounter/{FHIR_ENCOUNTER_ID}/practitioner/{FHIR_PRACTITIONER_ID}/pre_visit",
    headers=headers,
    timeout=60,
)
print(pre_visit_response.json())

# Full Patient Summary
curl "https://sdp.suki-stage.com/api/v1/patient-summary/encounter/encounter-123/practitioner/practitioner-456" \
  -H "sdp_suki_token: YOUR_SUKI_TOKEN"

# Pre-visit summary (optional)
curl "https://sdp.suki-stage.com/api/v1/patient-summary/encounter/encounter-123/practitioner/practitioner-456/pre_visit" \
  -H "sdp_suki_token: YOUR_SUKI_TOKEN"

For complete technical specifications, refer to the relevant API Reference pages.

Verify your integration

Before you design the full production workflow, confirm that your staging integration can complete this path:

Upload FHIR data to CKG successfully and poll until ingestion completes.
Authenticate successfully and use the returned sdp_suki_token in follow-up requests.
Trigger summary generation for an encounter with matching FHIR identifiers from your uploaded bundle.
Poll job status until the generation completes.
Retrieve the full Patient Summary or pre-visit summary with structured clinical data.

After this path works end to end on staging, continue with production rollout and error handling.

Next steps

After you complete your first Patient Summary workflow: Authentication API - Login, register, and authentication configuration. CKG Data Ingestion - Upload FHIR bundles and track ingestion status. Summary Generation API - Trigger asynchronous summary generation jobs. Patient Summaries API - Retrieve full and pre-visit Patient Summaries.

​Access and credentials

​Prerequisites

​Environments to use for development and testing

​Complete staging script

​Steps

​Verify your integration

​Next steps

Access and credentials

Prerequisites

Environments to use for development and testing

Complete staging script

Steps

Verify your integration

Next steps