Generate Patient Summaries

Learn the available Patient Summary generation workflows, when to use each one, and how asynchronous jobs fit your application

Patient Summary creates a concise pre-visit summaries for patients with upcoming appointments 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.

Prerequisites

• FHIR data for the patient is available in CKG (ingestion status COMPLETED when you depend on upload status).
• A valid Suki Token. See Partner authentication.
• Stable encounter, practitioner, and patient identifiers that match your ingestion and retrieval paths.

Decide on a generation workflow

Choose the workflow based on how many summaries you need.

Scheduled Appointments

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.

Single Encounter

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.

Scenario	Recommended workflow
Morning provider sign-in	Scheduled appointments
Prepare the day’s schedule	Scheduled appointments
One patient chart	Single encounter
Late schedule addition	Single encounter
Refresh after new FHIR data	Single encounter

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.

Endpoint	What the response means
Single encounter	Returns a patient_summary_id for that job.
Scheduled appointments	Returns 202 Accepted. Each appointment progresses as its own job.

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

Status	What it means
READY	The job is ready to start processing.
RUNNING	Suki is generating the summary.
COMPLETED	Generation finished successfully. Retrieve the summary.
FAILED	Generation failed. Log identifiers and decide whether to retry.
ABORTED	The job was aborted. Treat it as a terminal failure for this attempt.

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

Morning Clinic Preparation

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

Provider Opens the Application

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

Late Appointment

• Confirm the encounter data has been ingested into CKG.
• Generate a summary for that encounter.
• Retrieve and display the completed summary.

Troubleshooting

Plan for these situations in production. Generation should wait on CKG, reuse existing summaries when you can, and treat empty clinical states as product UI, not broken APIs.

CKG Ingestion Incomplete

Summary generation started before FHIR data was available in CKG. Complete ingestion and wait for status COMPLETED before generating summaries.

Summary Already Exists

A summary is already available for the appointment. Reuse it unless new clinical data requires regeneration.

No Upcoming Appointment

The patient does not have an upcoming appointment for that day. Do not expect a pre-visit summary. Without one, Patient Summary is not generated or shown. Design your UI for this empty state.

Limited Patient History

CKG has little or no prior clinical history for the patient. Some summary sections may be empty. Handle partial summaries in the UI instead of treating them as failures.

Job Failed or Aborted

The generation job reached FAILED or ABORTED. Log the identifiers, notify users if appropriate, and retry when applicable.

Identifier Mismatch

The FHIR identifiers used for generation do not match the ingested FHIR data. 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.

Available cookbooks

Next steps

Retrieve patient summaries - Display completed summaries in your application.

Patient Summary basic usage - End-to-end integration example.

Summary generation APIs - Available generation endpoints.