> ## 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. # Patient Summary Basic Usage > Upload FHIR data to CKG, authenticate, generate a Patient Summary, poll job status, and retrieve summary content with Patient Summary APIs **This guide covers:** [Patient Summary APIs](/patient-summary-api-reference/overview). * 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](/patient-summary-api-reference/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 call Login to obtain an `sdp_suki_token`. Refer to [Partner authentication](/documentation/how-to/partner-authentication) and [Patient Summary authentication](/patient-summary-api-reference/authentication) guides. ## Patient Summary API workflow overview The Patient Summary API workflow uses CKG Data Ingestion APIs plus Patient Summary REST APIs. 1. Authenticate and obtain an `sdp_suki_token`. 2. Request a CKG upload URL and upload a FHIR R4 bundle. 3. Poll ingestion status until CKG processing completes. 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 Call [Login](/patient-summary-api-reference/authentication/login) first and use the returned `sdp_suki_token` on CKG ingestion requests. Upload clinical data before you generate a summary. ### Request an upload URL Call GET [Request FHIR bundle upload URL](/patient-summary-api-reference/ckg-data-ingestion/upload): ```bash theme={"theme":{"light":"one-light","dark":"material-theme-darker"}} curl --request GET \ --url 'https://sdp.suki-stage.com/api/v1/fhir-push/upload-url?organization_id=&correlation_id=' \ --header 'Authorization: Bearer ' ``` 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](/patient-summary-api-reference/ckg-data-ingestion/fhir-data). ```bash theme={"theme":{"light":"one-light","dark":"material-theme-darker"}} curl --request PUT \ --url '' \ --header 'Content-Type: application/json' \ --header 'x-goog-content-length-range: 0,524288000' \ --data-binary @patient-fhir-bundle.json ``` ### Poll ingestion status Call GET [Check ingestion status](/patient-summary-api-reference/ckg-data-ingestion/ingestion-status): ```bash theme={"theme":{"light":"one-light","dark":"material-theme-darker"}} curl --request GET \ --url https://sdp.suki-stage.com/api/v1/fhir-push/status/ \ --header 'Authorization: Bearer ' ``` Poll until status is `COMPLETED`. Do not trigger summary generation while ingestion is still running. ### Request details * Authenticate CKG ingestion with the same Suki Token (`sdp_suki_token`) returned by Login. * Pass `organization_id` as your partner organization ID for your organization (chosen at provisioning). It can be a UUID or non-UUID string. But not a Suki UUID. * 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 Call Login before CKG upload and before generation or retrieval. Use the same `sdp_suki_token` for all of these calls. Call POST [Login](/patient-summary-api-reference/authentication/login): ```bash theme={"theme":{"light":"one-light","dark":"material-theme-darker"}} curl --request POST \ --url https://sdp.suki-stage.com/api/v1/auth/login \ --header 'Content-Type: application/json' \ --data '{ "partner_id": "", "partner_token": "", "provider_id": "" }' ``` Example response: ```json theme={"theme":{"light":"one-light","dark":"material-theme-darker"}} { "suki_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..." } ``` Use the returned token as `sdp_suki_token` in later Patient Summary requests. If login fails because the provider is not registered, call [Register](/patient-summary-api-reference/authentication/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](/patient-summary-api-reference/summary-generation/encounter-summary): ```bash theme={"theme":{"light":"one-light","dark":"material-theme-darker"}} curl --request POST \ --url https://sdp.suki-stage.com/api/v1/patient-summary/generate/encounter \ --header 'Content-Type: application/json' \ --header 'sdp_suki_token: ' \ --header 'sdp_provider_id: ' \ --data '{ "fhir_encounter_id": "encounter-123", "fhir_practitioner_id": "practitioner-456" }' ``` ### 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](/patient-summary-api-reference/summary-generation/scheduled-appointment-summary) 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](/patient-summary-api-reference/summary-jobs/encounter-status): ```bash theme={"theme":{"light":"one-light","dark":"material-theme-darker"}} curl --request GET \ --url https://sdp.suki-stage.com/api/v1/patient-summary/encounter/encounter-123/practitioner/practitioner-456/status \ --header 'sdp_suki_token: ' \ --header 'sdp_provider_id: ' ``` Poll until the status is terminal, for example `COMPLETED` or `FAILED`. Refer to the [Summary Jobs APIs](/patient-summary-api-reference/summary-jobs) 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](/patient-summary-api-reference/summaries/encounter-practitioner): ```bash theme={"theme":{"light":"one-light","dark":"material-theme-darker"}} curl --request GET \ --url https://sdp.suki-stage.com/api/v1/patient-summary/encounter/encounter-123/practitioner/practitioner-456 \ --header 'sdp_suki_token: ' \ --header 'sdp_provider_id: ' ``` You can also retrieve by `patient_summary_id` using [Patient Summary by ID](/patient-summary-api-reference/summaries/patient-summary). ### Retrieve the pre-visit section Call GET [Pre-visit summary using partner identifiers](/patient-summary-api-reference/summaries/encounter-pre-visit) when your UI needs a short preview: ```bash theme={"theme":{"light":"one-light","dark":"material-theme-darker"}} curl --request GET \ --url https://sdp.suki-stage.com/api/v1/patient-summary/encounter/encounter-123/practitioner/practitioner-456/pre_visit \ --header 'sdp_suki_token: ' \ --header 'sdp_provider_id: ' ``` ### Summary sections to expect The full Patient Summary is organized into these sections: | Section | Description | Source | | :- | :- | :- | | **About this visit** | Appointment type and reason for visit | API / appointment context | | **Summary** | One or two lines that summarize previous-visit summaries | CKG | | **Summary of previous visits** | Short paragraphs for recent visits | CKG | | **Problems** | Active problem list | CKG | Design your UI for partial data. If the patient has an upcoming appointment but no prior encounter record, show **About this visit** and **Problems**. 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: Request an upload URL, upload the FHIR bundle, and poll CKG ingestion until complete. Call login and save `sdp_suki_token`. Call [Generate Patient Summary for an encounter](/patient-summary-api-reference/summary-generation/encounter-summary). Poll [Encounter status](/patient-summary-api-reference/summary-jobs/encounter-status) until the job is terminal. Call a [Patient Summaries](/patient-summary-api-reference/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](/patient-summary-api-reference/summary-generation/scheduled-appointment-summary). 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. ## Related API references Upload FHIR bundles into CKG. Start asynchronous summary generation. 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. ## Available cookbooks