Skip to main content
This guide covers: Patient Summary APIs.
  • Upload FHIR data into Suki’s Clinical Knowledge Graph (CKG), trigger asynchronous summary generation, poll job status, and retrieve the completed summary.
  • Looking for a quickstart with full scripts? Refer to the Patient Summary API quickstart.
This guide walks you through how to build a standalone Patient Summary workflow with the Patient Summary APIs. In this workflow, you:
  • Authenticate and obtain an sdp_suki_token.
  • Upload FHIR data to CKG.
  • Trigger summary generation for an encounter.
  • Poll job status until generation completes.
  • Retrieve the full Patient Summary or pre-visit section.
Before you start, complete your onboarding with Suki and confirm you can sign the SDP JWT used for CKG ingestion. Refer to Partner authentication and Patient Summary authentication guides.

​
Patient Summary API workflow overview

The Patient Summary API workflow uses CKG Data Ingestion APIs plus Patient Summary REST APIs.
  1. Request a CKG upload URL and upload a FHIR R4 bundle.
  2. Poll ingestion status until CKG processing completes.
  3. Authenticate and obtain an sdp_suki_token.
  4. Trigger summary generation for an encounter and practitioner pair.
  5. Poll generation status until the job is complete.
  6. Retrieve the full summary or pre-visit section.
Patient Summaries are generated from data available in CKG. Keep fhir_encounter_id and fhir_practitioner_id consistent between the ingested FHIR resources and later generation or retrieval calls.

​
Upload FHIR data to CKG

Upload clinical data before you generate a summary.

​
Request an upload URL

Call GET Request FHIR bundle upload URL:
Save transaction_id and upload_url from the response.

​
Upload the FHIR bundle

Upload the bundle JSON to the returned upload_url with HTTP PUT. Refer to Upload FHIR bundle.

​
Poll ingestion status

Call GET Check ingestion status:
Poll until status is COMPLETED. Do not trigger summary generation while ingestion is still running.

​
Request details

  • Authenticate CKG ingestion with an RS256-signed SDP JWT bearer token that includes the sdp_partner_id claim.
  • Include consistent patient, encounter, and practitioner identifiers in the FHIR resources you upload.
  • Use a stable correlation_id when you upload updates related to a previous transaction.

​
Authenticate for Patient Summary APIs

After CKG ingestion is complete, authenticate for generation and retrieval. Call POST Login:
Example response:
Use the returned token as sdp_suki_token in later Patient Summary requests. If login fails because the provider is not registered, call Register once, then login again.

​
Generate a Patient Summary for an encounter

Create an asynchronous generation job for one encounter and practitioner pair. Call POST Generate Patient Summary for an encounter:

​
Request details

  • fhir_encounter_id and fhir_practitioner_id must match identifiers in the ingested FHIR data.
  • Generation is asynchronous. Treat the response as job acceptance, not finished summary content.
  • Save patient_summary_id when the response returns one. You can use it for status and retrieval.
  • If a summary already exists for the appointment, skip generation unless you intentionally refreshed CKG data.
To generate summaries for an entire provider schedule, use Generate Patient Summaries for scheduled appointments instead.

​
Poll generation status

After you trigger generation, poll until the job reaches a terminal status. Call GET Generation status using encounter and practitioner IDs:
Poll until the status is terminal, for example COMPLETED or FAILED. Refer to the Summary Jobs APIs for all status values and the patient_summary_id status path.
Poll at reasonable intervals, for example every 5 seconds. Generation commonly completes within a few seconds to a few minutes, and about 20 seconds per appointment is a useful planning estimate after the request is accepted.

​
Retrieve the Patient Summary

When status is COMPLETED, retrieve the summary content.

​
Retrieve the full summary

Call GET Patient Summary using partner identifiers:
You can also retrieve by patient_summary_id using Patient Summary by ID.

​
Retrieve the pre-visit section

Call GET Pre-visit summary using partner identifiers when your UI needs a short preview:

​
Summary sections to expect

The full Patient Summary is organized into these sections:
Design your UI for partial data. If the patient has an upcoming appointment but no prior encounter record, show About this visit and Problems, and show that no record was found under Summary and Summary of previous visits.If there is no upcoming appointment, show that the patient needs a scheduled appointment before a summary is available.

​
Common integration patterns and use cases

​
Pattern 1: Standard encounter flow

A typical encounter-based Patient Summary workflow follows these steps:
1

Upload FHIR Data

Request an upload URL, upload the FHIR bundle, and poll CKG ingestion until complete.
2

Authenticate

Call login and save sdp_suki_token.
3

Generate the Summary

Call Generate Patient Summary for an encounter.
4

Poll Job Status

Poll Encounter status until the job is terminal.
5

Retrieve Summary Content

Call a Patient Summaries endpoint and render the sections in your UI.

​
Pattern 2: Morning schedule generation

  1. Ingest the provider schedule and patient FHIR data for the day.
  2. Call Generate Patient Summaries for scheduled appointments.
  3. Poll status per appointment.
  4. Retrieve pre-visit sections for schedule cards and full summaries for chart review.

​
Pattern 3: Skip create when a summary already exists

Before you generate, check whether a summary already exists for the appointment. If it does, retrieve and display it. Generate again only when you refreshed CKG data and need an updated summary.

CKG Data Ingestion

Upload FHIR bundles into CKG

Generate for Encounter

Start asynchronous summary generation

Retrieve Patient Summary

Load completed summary content

​
Best practices

  • Finish CKG ingestion first so generation reads complete clinical context.
  • Keep FHIR identifiers consistent across upload, generation, and retrieval.
  • Skip regeneration when a summary already exists for the appointment.
  • Poll status until terminal, then retrieve content.
  • Handle empty states for no upcoming appointment and no prior record.
  • Store tokens securely and refresh sdp_suki_token before expiry.

​
FAQs

Show this message in the patient profile: No upcoming appointment. Schedule an appointment to view the summary. Patient Summary is intended for patients with an upcoming appointment on the provider schedule.
Show About this visit and Problems. Under Summary and Summary of previous visits, show that no record was found.
No. Begin generation when the provider logs in or opens the app, but if a summary already exists for a given appointment, do not create a new one.

​
Next steps

Patient Summary best practices - Production polling, retries, logging, and security. How Patient Summary works - Architecture, lifecycle, and data flow. Patient Summary API quickstart - Full staging scripts for the same workflow.
Last modified on August 7, 2026