Skip to main content
Patient Summary creates a concise pre-visit summary for a patient with an upcoming appointment using FHIR data ingested into the Clinical Knowledge Graph (CKG). After your application successfully ingests FHIR data into CKG, it can start generating patient summaries. Generation is asynchronous. Submit a generation request to start a background job, monitor the job status, then retrieve the completed summary when it is ready. Patient Summary supports two generation workflows:

Scheduled Appointments

Prepare summaries for every appointment on a provider’s schedule, such as morning clinic preparation or provider sign-in.

Single Encounter

Generate a summary for one upcoming encounter when you need it for a specific patient.
Choose the workflow that best fits your application’s use case. For request and response details, refer to the Summary Generation APIs. Your application is responsible for:
  • Deciding when to generate summaries.
  • Selecting the appropriate generation workflow.
  • Monitoring generation and retrieving completed summaries.
Before generating summaries:
1

Complete CKG Ingestion

Ingest the required patients, encounters, practitioners, and provider schedule into CKG. Wait until ingestion status is COMPLETED.
2

Align FHIR Identifiers

Use the same fhir_encounter_id and fhir_practitioner_id values during ingestion and generation.
3

Check for an Existing Summary

Confirm whether a summary already exists for the appointment before starting another job.
4

Generate Only When Needed

Start generation when no usable summary exists, or when new clinical data requires regeneration.
Generate summaries when the provider signs in or before the clinic day begins. If a summary already exists for an appointment, reuse it instead of creating another one.

​
Decide on a generation workflow

Choose the workflow based on how many summaries you need.
Use scheduled generation to prepare summaries for every appointment on a provider’s schedule.Typical scenarios include:
  • Morning clinic preparation.
  • Provider sign-in or application launch.
  • Preloading schedule views before patient visits.
One request starts generation for every qualifying appointment on the provider’s schedule. Call the endpoint with fhir_practitioner_id. Refer to Generate Patient Summaries for scheduled appointments.
Use encounter generation when you need a summary for only one patient.Typical scenarios include:
  • A clinician opens a patient chart.
  • A patient is added after the morning generation run.
  • New clinical data requires an updated summary.
One request generates a summary for a single encounter. Call the endpoint with fhir_encounter_id and fhir_practitioner_id. Refer to Generate Patient Summary for an encounter.
Many production integrations use both workflows.
  • Scheduled generation prepares summaries before the clinic day begins.
  • Encounter generation handles individual requests throughout the day.

​
Generate summaries for scheduled appointments

Use this workflow to generate summaries for every appointment on a provider’s schedule.

​
Typical workflow

1

Confirm Schedule and Patient Data

Ensure the provider schedule and related patient FHIR data have been ingested into CKG.
2

Trigger Scheduled Generation

Call Generate Patient Summaries for scheduled appointments with the fhir_practitioner_id.
3

Accept the Batch Job

The endpoint returns 202 Accepted when generation is scheduled. Suki starts a generation job for each matching appointment.
4

Monitor Each Appointment

Poll job status for each appointment independently. Status values are described in How generation jobs work.
5

Retrieve Completed Summaries

Retrieve completed summaries as they become available, without waiting for every appointment to finish.
  • Most partners ingest provider schedules once each day.
  • Generation typically takes about 20 seconds per appointment after the request is accepted.
  • Skip appointments that already have a valid summary unless new clinical data requires regeneration.

​
Generate summaries for a single encounter

Use this workflow to generate a summary for one upcoming encounter.
1

Confirm Encounter Data

Confirm the Patient, Encounter, Practitioner, and related clinical data have been ingested into CKG.
2

Trigger Encounter Generation

Call Generate Patient Summary for an encounter with fhir_encounter_id and fhir_practitioner_id.
3

Save the Patient Summary ID

The response includes a patient_summary_id. Store it if your application uses it for status checks or retrieval.
4

Monitor the Job

Poll until the job reaches a terminal status (COMPLETED, FAILED, or ABORTED).
5

Retrieve the Summary

Retrieve the completed summary or pre-visit section for display in your application.

​
How generation jobs work

Each generation request creates an asynchronous job. The summary is generated in the background and is not included in the initial generation response. The typical lifecycle is:
  1. Submit a generation request.
  2. Receive acknowledgment (patient_summary_id for a single encounter, or 202 Accepted for scheduled generation).
  3. Monitor the job status.
  4. Stop polling when the job reaches a terminal status.
  5. Retrieve the completed summary.

​
Status values

COMPLETED, FAILED, and ABORTED are terminal statuses. Stop polling when you receive one of them.
Poll status with the Summary Jobs APIs using either:
  • patient_summary_id, or
  • fhir_encounter_id and fhir_practitioner_id.
Your application controls how often to poll, retry behavior, and what users see while generation is in progress.
Poll about every 5 seconds, then add backoff if the job is still running. Generation typically completes within seconds to minutes, depending on the volume of patient data in CKG.
For scheduled generation, each appointment progresses independently. Display summaries as they become available instead of waiting for every appointment to finish.

​
Common workflows

  • Ingest the provider schedule and patient data.
  • Generate summaries for the day’s appointments.
  • Monitor job progress per appointment.
  • Display summaries in the provider schedule.
  • Check whether today’s appointments already have summaries.
  • Generate summaries only for appointments that do not.
  • Continue monitoring generation in the background.
  • Display summaries as clinicians open patient charts.
  • Confirm the encounter data has been ingested into CKG.
  • Generate a summary for that encounter.
  • Retrieve and display the completed summary.

​
Error handling

Plan for the following situations in production.
Cause: Summary generation started before FHIR data was available in CKG.Resolution: Complete ingestion and wait for status COMPLETED before generating summaries.
Cause: A summary is already available for the appointment.Resolution: Reuse the existing summary unless new clinical data requires regeneration.
Cause: The patient does not have an upcoming appointment for that day.Resolution: Do not expect a pre-visit summary. Design your UI for this empty state.
Cause: CKG has little or no prior clinical history for the patient.Resolution: Some summary sections may be empty. Design your UI to handle partial summaries gracefully.
Cause: The generation job reached a terminal failure status (FAILED or ABORTED).Resolution: Log the identifiers, notify users if appropriate, and retry if applicable.
Cause: The FHIR identifiers used for generation do not match the ingested FHIR data.Resolution: Verify fhir_encounter_id and fhir_practitioner_id across ingestion and generation, then retry.

​
Best practices

  • Generate summaries only for patients with upcoming appointments.
  • Use scheduled generation to prepare summaries before the clinic day begins.
  • Reuse existing summaries whenever possible.
  • Perform generation from your backend instead of client applications.
  • Use exponential backoff when polling job status.
  • Regenerate summaries only after meaningful CKG updates.
  • Store the encounter, practitioner, and patient_summary_id for retrieval, troubleshooting, and retries.

​
Next steps

Continue with the following guides:
Last modified on August 7, 2026