--- name: suki-patient-summary description: >- Use when building Suki Patient Summary integrations: ingest FHIR R4 data into the Clinical Knowledge Graph (CKG), authenticate Patient Summary APIs, generate summaries for scheduled appointments or individual encounters, monitor asynchronous generation jobs, and retrieve completed full or pre-visit summaries. license: SUKI_Proprietary metadata: author: suki version: "2.4" --- ## Patient Summary Use **Patient Summary** to provide clinicians with relevant patient context before an upcoming appointment. Patient Summary uses patient data ingested into Suki's **Clinical Knowledge Graph (CKG)** to generate a concise pre-visit summary. Patient Summary is separate from: - **Ambient**, which generates clinical notes from patient-provider conversations. - **Dictation**, which converts speech to text. - **Form filling**, which generates structured medical form output. The typical Patient Summary workflow is: ```text ingest FHIR data into CKG → generate summary → monitor generation job → retrieve completed summary → display summary in your application ```` ## Accuracy rules * Do not invent endpoints, request fields, response fields, identifiers, or status values. * Use **FHIR R4** data for CKG ingestion. * Keep CKG ingestion authentication separate from Patient Summary API authentication. * Use the documented **SDP JWT** for CKG FHIR ingestion. * Use the documented **Suki Token** in `sdp_suki_token` for Patient Summary generation, status, and retrieval APIs. * Do not use the SDP JWT as the `sdp_suki_token`. * Do not assume a Partner Token and Suki Token are interchangeable. * Use `fhir_encounter_id` and `fhir_practitioner_id` consistently when using the encounter-and-practitioner workflow. * Do not confuse `fhir_encounter_id` with Ambient `encounter_id`. * Do not assume that uploading FHIR data immediately makes a Patient Summary available. * Do not trigger summary generation before the required FHIR data has been ingested into CKG. * Treat summary generation as asynchronous. * Do not retrieve a summary until generation reaches `COMPLETED`. * Stop generation polling when the job reaches `COMPLETED`, `FAILED`, or `ABORTED`. * Do not invent additional generation status values. * Keep JWTs, Suki Tokens, and partner credentials on the server. * If an endpoint, field, status, or authentication requirement is unclear, read the current Patient Summary documentation or use the documentation MCP before writing code. ## Environment Use staging for development and testing unless the user explicitly requests production. | Environment | Base URL | | --- | --- | | Staging | `https://sdp.suki-stage.com` | | Production | `https://sdp.suki.ai` | Do not use production credentials or production patient data in staging. ### API endpoints | Operation | Method | Path | | --- | --- | --- | | Login | `POST` | `/api/v1/auth/login` | | Register | `POST` | `/api/v1/auth/register` | | Request FHIR upload URL | `GET` | `/api/v1/fhir-push/upload-url` | | FHIR push status | `GET` | `/api/v1/fhir-push/status/{transaction_id}` | | Generate for encounter | `POST` | `/api/v1/patient-summary/generate/encounter` | | Generate for schedule | `POST` | `/api/v1/patient-summary/generate/provider-schedule` | | Get summary by ID | `GET` | `/api/v1/patient-summary/{patient_summary_id}` | | Job status by ID | `GET` | `/api/v1/patient-summary/{patient_summary_id}/status` | ## Prerequisites Before implementing Patient Summary, make sure you have: * Partner credentials from Suki. * A working authentication path for Patient Summary APIs. * The ability to generate and sign the SDP JWT required for CKG ingestion. * FHIR R4 patient data. * FHIR R4 encounter data. * FHIR R4 practitioner data. * Schedule and appointment data for the appointments you want to summarize. * Stable identifiers such as: * `fhir_encounter_id` * `fhir_practitioner_id` Patient Summary content depends on the data available in CKG. The quality, completeness, and freshness of the ingested data directly affect the generated summary. ## Choose a workflow | Workflow | Use when | Dedicated skill | | --- | --- | --- | | **Full API integration** | Required patient data is not yet in CKG; your app owns generate/retrieve UI | `suki-patient-summary` (this skill) | | **Generate and retrieve** | Required patient data is already available in CKG | `suki-patient-summary` (this skill) | | **CKG ingestion only** | You are implementing or testing FHIR ingestion separately | `suki-patient-summary` (this skill) | | **Headed Web SDK** | Clinicians use the Web SDK patient profile for snippet + full summary | `suki-web-sdk` | For the headed Web SDK path, fetch: https://developer.suki.ai/.well-known/agent-skills/suki-web-sdk/SKILL.md You still ingest FHIR into CKG on your backend. The Web SDK path does not call Patient Summary generate/status/retrieve from the host app. Patient Summary supports both scheduled-appointment generation and single-encounter generation for the API path. ### Scheduled generation Use scheduled generation when you want to prepare summaries for upcoming appointments, such as generating summaries for a provider's schedule before the clinic day. ### Single-encounter generation Use encounter generation when your application needs to generate a summary for one specific encounter. ## 1. Ingest FHIR data into CKG Before generating a Patient Summary, ingest the relevant patient FHIR data into Suki's Clinical Knowledge Graph. The CKG FHIR ingestion workflow uses an **SDP JWT**. This authentication method is separate from the authentication used by the Patient Summary APIs. The high-level ingestion flow is: ```text generate SDP JWT → request pre-signed upload URL → upload FHIR bundle → monitor ingestion → wait for successful ingestion → generate Patient Summary ``` ### Request an upload URL Request a pre-signed upload URL from the CKG FHIR ingestion API. The request requires: * `organization_id` * `correlation_id` Authenticate the request with the SDP JWT. The response provides the information needed to upload the FHIR bundle, including a `transaction_id` and pre-signed `upload_url`. Use the exact endpoint and request schema documented in the CKG Data Ingestion API. Do not construct or modify the pre-signed upload URL yourself. ### Upload the FHIR bundle Upload the FHIR R4 bundle to the returned pre-signed URL. Use: ```http Content-Type: application/json ``` The documented maximum FHIR bundle size is **500 MB**. The upload URL is temporary. Upload the bundle before the URL expires. Do not send the FHIR bundle to the Patient Summary generation endpoint. ### Monitor ingestion Use the `transaction_id` returned by the upload URL request to monitor the FHIR ingestion transaction. The ingestion workflow is asynchronous. Do not assume that a successful FHIR upload means that the data is already available in CKG. Wait until the ingestion process reaches its documented successful terminal state before starting Patient Summary generation. Use the current CKG Data Ingestion API documentation for the exact ingestion status values. ### Ingestion identifiers The CKG ingestion workflow uses identifiers including: * `transaction_id`: identifies the ingestion transaction. * `correlation_id`: correlates the ingestion request with your application workflow. * `organization_id`: identifies the partner organization. Do not confuse these identifiers with: * `fhir_encounter_id` * `fhir_practitioner_id` * `patient_summary_id` They serve different purposes. ### CKG ingestion webhooks You can use Suki partner webhooks to receive a notification when an asynchronous CKG FHIR ingestion job reaches a terminal state. When using webhooks, follow the `suki-webhooks` skill for: * HMAC signature verification. * Raw request body handling. * CKG ingestion webhook payloads. * `transaction_id`. * `correlation_id`. * CKG ingestion `state`. Do not treat CKG ingestion webhook payloads as Patient Summary generation payloads. ## 2. Authenticate for Patient Summary APIs Patient Summary generation, status, and retrieval APIs use a **Suki Token**. This authentication flow is separate from the SDP JWT used for CKG ingestion. The authentication flow is generally: ```text Partner Token → Suki authentication → Suki Token → Patient Summary APIs ``` Send the Suki Token using: ```http sdp_suki_token: {suki_token} ``` Do not use the SDP JWT as `sdp_suki_token`. Do not assume that a Partner Token can be sent directly to Patient Summary generation, status, or retrieval APIs. Follow the current Partner Authentication and Patient Summary authentication documentation for the exact login and token exchange flow. ### Provider authentication Some Patient Summary APIs also require: ```http sdp_provider_id: {provider_id} ``` Send `sdp_provider_id` when required by the specific endpoint. Do not substitute another identifier, such as `fhir_practitioner_id`, for `sdp_provider_id` unless the endpoint documentation explicitly requires that mapping. ### Authentication separation Use the authentication method appropriate to each workflow: | Workflow | Authentication | | --------------------------------- | ---------------------------------- | | CKG FHIR ingestion | SDP JWT in `Authorization: Bearer` | | Patient Summary generation | Suki Token in `sdp_suki_token` | | Patient Summary generation status | Suki Token in `sdp_suki_token` | | Patient Summary retrieval | Suki Token in `sdp_suki_token` | Do not mix these authentication mechanisms. ## 3. Generate a Patient Summary Patient Summary generation is asynchronous. Suki supports generation for: * Scheduled appointments. * Individual encounters. Choose the generation workflow that matches your application. ### Generate for an encounter For single-encounter generation, use the encounter generation API. The request includes: ```json { "fhir_encounter_id": "encounter-id", "fhir_practitioner_id": "practitioner-id" } ``` Authenticate using: ```http sdp_suki_token: {suki_token} ``` The generation request starts an asynchronous job. A successful generation response does **not** mean that the summary is ready to retrieve. If the response provides a `patient_summary_id`, store it. You can use that identifier with the corresponding Summary Jobs APIs. ### Generate for scheduled appointments Use the scheduled generation workflow when preparing summaries for upcoming appointments. This workflow is useful when: * You have a provider schedule. * The required patient data has already been ingested into CKG. * You want summaries prepared before clinicians need them. Use the exact scheduled-generation endpoint and request schema documented by Suki. Do not assume the scheduled-generation request has the same response shape as single-encounter generation. ## 4. Monitor the generation job Patient Summary generation runs asynchronously. After triggering generation, monitor the corresponding Summary Jobs API. Suki supports generation-status lookup using: * `fhir_encounter_id` and `fhir_practitioner_id` * `patient_summary_id` The Summary Jobs APIs are called only **after** a generation request has been submitted. ### Status using encounter and practitioner IDs Use the documented status endpoint for: ```text fhir_encounter_id fhir_practitioner_id ``` Authenticate with: ```http sdp_suki_token: {suki_token} ``` ### Status using Patient Summary ID If the generation response provides: ```text patient_summary_id ``` use the corresponding Patient Summary ID status endpoint. This is useful when your application stores the generated summary ID and does not want to map the job back to encounter and practitioner identifiers. ### Terminal statuses Stop polling when the generation job reaches: | Status | Meaning | | ----------- | ---------------------------------- | | `COMPLETED` | Generation completed successfully. | | `FAILED` | Generation failed. | | `ABORTED` | Generation was aborted. | Do not continue polling after a terminal state. Do not invent additional status values. ### Polling pattern Use reasonable polling intervals. Do not continuously poll the API in a tight loop. ```text trigger generation → wait → check status → if non-terminal, wait and check again → if COMPLETED, retrieve summary → if FAILED or ABORTED, stop ``` Do not retrieve the summary on every status request. Retrieve the summary only after the generation status is `COMPLETED`. ## 5. Retrieve the completed summary After generation reaches: ```text COMPLETED ``` retrieve the Patient Summary. Patient Summary provides both full-summary and pre-visit retrieval workflows. ### Full Patient Summary For the encounter/practitioner workflow, retrieve the completed summary using the corresponding encounter and practitioner identifiers. Use: ```text fhir_encounter_id fhir_practitioner_id ``` and authenticate with: ```http sdp_suki_token: {suki_token} ``` Follow the current Patient Summaries API reference for the exact endpoint and response schema. ### Pre-visit summary Use the documented pre-visit retrieval endpoint when your application needs the clinician's pre-visit view. The pre-visit summary is intended to support preparation before the appointment. Do not assume that the pre-visit response has exactly the same schema as the full Patient Summary response. Follow the endpoint-specific response schema. ### Retrieve by Patient Summary ID If the generation workflow returns a `patient_summary_id`, use the corresponding Patient Summaries endpoint that accepts that identifier. Do not derive or construct a `patient_summary_id`. ## 6. Patient Summary sections A completed Patient Summary contains these sections: | Section | Description | | -------------------- | ---------------------------------------------------------- | | **About this visit** | Appointment type and reason for the visit. | | **Summary** | A brief overview of the patient's recent clinical history. | | **Previous visits** | Short summaries of recent encounters. | | **Problems** | Active problem list. | The exact content, historical lookback period, and summary length depend on the implementation and configured requirements. Do not assume that the summary contains clinical information that was not available in CKG. ## 7. Present the summary After retrieving the completed summary, display it in the appropriate pre-visit experience. Common locations include: * Schedule views. * Appointment details. * Patient charts. * Patient profiles. * Pre-visit workflows. Keep generation and retrieval separate. A typical application flow is: ```text generate → monitor → retrieve → display ``` Do not make the clinician wait for a new generation job every time they open a page when the workflow can generate summaries ahead of the appointment. For scheduled workflows, generate summaries early enough that they are ready when clinicians need them. ## Data freshness Patient Summary uses the clinical data available in CKG. The quality and completeness of the generated summary depend on: * The quality of the FHIR data. * The completeness of the FHIR data. * The freshness of the data in CKG. * The configured historical lookback and summary requirements. Your integration should establish a reliable FHIR ingestion process for the appointments you want to summarize. If new clinical data becomes available and your application needs an updated summary, follow the documented generation workflow again. Do not assume that uploading new FHIR data automatically regenerates an existing Patient Summary. ## FHIR data Patient Summary requires FHIR R4 data in CKG. The Patient Summary prerequisites include FHIR data for: * Patient. * Encounter. * Practitioner. * Schedule. * Clinical history. Use the FHIR resource types and payload constraints documented by the current CKG Data Ingestion APIs. Do not invent resource mappings or assume that unsupported FHIR resources will contribute to a Patient Summary. ### Identifier consistency The identifiers used during Patient Summary generation must correspond to the FHIR data ingested into CKG. In particular: ```text fhir_encounter_id fhir_practitioner_id ``` must identify the encounter and practitioner used by the Patient Summary workflow. Do not substitute an Ambient: ```text encounter_id ``` for: ```text fhir_encounter_id ``` Ambient `encounter_id` is a session-group identifier and belongs to the Ambient workflow. Do not use an Ambient session ID as a Patient Summary encounter identifier. ## Common mistakes ### Using the SDP JWT for Patient Summary APIs Wrong: ```http POST /api/v1/patient-summary/generate/encounter Authorization: Bearer {SDP_JWT} ``` Use the Patient Summary authentication mechanism: ```http sdp_suki_token: {suki_token} ``` The SDP JWT is used for CKG FHIR ingestion APIs. ### Using the Suki Token for FHIR ingestion Do not use: ```http sdp_suki_token: {suki_token} ``` for CKG FHIR-push endpoints. Use the SDP JWT as the documented Bearer token. ### Generating before CKG ingestion completes Wrong: ```text upload FHIR → immediately generate Patient Summary ``` Correct: ```text request upload URL → upload FHIR bundle → monitor ingestion → wait for successful ingestion → generate Patient Summary ``` ### Treating generation as synchronous Wrong: ```text POST generate → immediately GET summary ``` Correct: ```text POST generate → poll generation status → wait for COMPLETED → GET summary ``` ### Polling before generation Do not call a Summary Jobs endpoint before triggering summary generation. The Summary Jobs documentation explicitly requires generation to be triggered first. ### Polling forever Stop polling when the generation job reaches: ```text COMPLETED FAILED ABORTED ``` Do not invent additional terminal values. ### Mixing FHIR and Ambient identifiers Do not use: ```text encounter_id ``` where Patient Summary expects: ```text fhir_encounter_id ``` These identifiers represent different concepts. ### Assuming every generation response has the same identifier Some generation workflows provide a `patient_summary_id`. If it is returned, use it with the ID-based Summary Jobs and retrieval APIs. For workflows that use encounter and practitioner identifiers, use the documented `fhir_encounter_id` and `fhir_practitioner_id` endpoints. Do not derive one identifier from another. ### Assuming a completed ingestion means a completed summary FHIR ingestion and Patient Summary generation are separate asynchronous processes. The flow is: ```text FHIR ingestion → ingestion completes → summary generation → generation completes → summary retrieval ``` Do not combine the two job lifecycles. ## Non-negotiable rules Before generating or reviewing Patient Summary code, verify: * [ ] FHIR R4 data is being used. * [ ] Required patient, encounter, practitioner, schedule, and history data is available for the appointments being summarized. * [ ] CKG ingestion uses the SDP JWT. * [ ] Patient Summary APIs use the Suki Token in `sdp_suki_token`. * [ ] Authentication modes are not mixed. * [ ] `fhir_encounter_id` refers to the FHIR encounter. * [ ] `fhir_practitioner_id` refers to the FHIR practitioner. * [ ] Required FHIR data has been ingested before generation starts. * [ ] Generation is treated as asynchronous. * [ ] Summary status is checked only after generation is triggered. * [ ] Polling stops at `COMPLETED`, `FAILED`, or `ABORTED`. * [ ] The summary is retrieved only after `COMPLETED`. * [ ] The correct generation workflow is being used. * [ ] The correct status endpoint is being used. * [ ] The correct retrieval endpoint is being used. * [ ] Secrets remain on the server. * [ ] Credentials are not committed to source control. * [ ] Production clinical data is not fabricated for testing. ## Implementation checklist ### CKG ingestion * [ ] Confirm the `organization_id`. * [ ] Generate and sign the SDP JWT. * [ ] Request the pre-signed upload URL. * [ ] Store the returned `transaction_id`. * [ ] Upload the FHIR R4 bundle to the returned upload URL. * [ ] Respect the documented bundle size limit. * [ ] Monitor the ingestion transaction. * [ ] Wait for successful ingestion before triggering summary generation. ### Patient Summary authentication * [ ] Complete Partner authentication. * [ ] Obtain the Suki Token required by Patient Summary APIs. * [ ] Send the token using `sdp_suki_token`. * [ ] Send `sdp_provider_id` when required. * [ ] Keep all credentials server-side. ### Generation * [ ] Choose scheduled-appointment or single-encounter generation. * [ ] Use the correct generation endpoint. * [ ] Pass the correct FHIR identifiers. * [ ] Store `patient_summary_id` when the generation response provides it. * [ ] Treat generation as asynchronous. ### Status * [ ] Use the correct Summary Jobs endpoint. * [ ] Start polling only after generation is triggered. * [ ] Poll at reasonable intervals. * [ ] Stop at `COMPLETED`. * [ ] Stop at `FAILED`. * [ ] Stop at `ABORTED`. * [ ] Do not retrieve the summary before `COMPLETED`. ### Retrieval * [ ] Retrieve the full Patient Summary after successful generation. * [ ] Retrieve the pre-visit summary when required. * [ ] Use the correct identifier for the selected retrieval endpoint. * [ ] Display the summary in the appropriate pre-visit experience. ## When to read more - [Patient Summary API Quickstart](https://developer.suki.ai/patient-summary-api-reference/quickstart): Upload FHIR data, trigger summary generation, and retrieve Patient Summaries on staging - [Patient Summary Overview](https://developer.suki.ai/documentation/concepts/patient-summary/overview): Start here for Patient Summary: what it is, why to use it, key capabilities, how it fits your application, and where to go next - [Partner Authentication Mechanisms](https://developer.suki.ai/documentation/how-to/partner-authentication): Compare and choose the right authentication mechanism for your APIs and SDKs, including Partner Token exchange, JWKS, and provider registration - [Patient Summary In Web SDK](https://developer.suki.ai/web-sdk/guides/patient-summary): Show pre-visit Patient Summary in the Headed Web SDK patient profile after you ingest FHIR into CKG and pass matching encounter.identifier and encounter.practitionerFhirId - [llms-full.txt](https://developer.suki.ai/llms-full.txt): Full-site dump for broad cross-product questions ## Sister skills * Web SDK: [https://developer.suki.ai/.well-known/agent-skills/suki-web-sdk/SKILL.md](https://developer.suki.ai/.well-known/agent-skills/suki-web-sdk/SKILL.md) * Webhooks: [https://developer.suki.ai/.well-known/agent-skills/suki-webhooks/SKILL.md](https://developer.suki.ai/.well-known/agent-skills/suki-webhooks/SKILL.md) * Platform router: [https://developer.suki.ai/.well-known/agent-skills/suki-platform/SKILL.md](https://developer.suki.ai/.well-known/agent-skills/suki-platform/SKILL.md) * Ambient: [https://developer.suki.ai/.well-known/agent-skills/suki-ambient/SKILL.md](https://developer.suki.ai/.well-known/agent-skills/suki-ambient/SKILL.md)