> ## 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 Best Practices

> Production guidance for authenticating, polling, retrying, logging, monitoring, and securing Patient Summary integrations

<div className="quick-summary-wrapper">
  <div className="quick-summary-header">
    <span className="quick-summary-icon" aria-hidden="true" />

    <span className="quick-summary-title">Quick summary</span>
  </div>

  <div className="quick-summary-content">
    Treat Patient Summary as a production workflow. Ingest FHIR data into CKG before generation, poll asynchronously, handle empty clinical states clearly, and keep identifiers consistent across ingestion, generation, and retrieval.
  </div>
</div>

Patient Summary works best when ingestion, generation, and retrieval are designed for clinic-day use. This guide covers the production practices that keep summaries reliable for partner applications.

In production, focus on these outcomes:

* FHIR data is in CKG before summary generation starts.
* Generation does not block clinician login or chart open.
* Polling is bounded and stops on terminal statuses.
* Failures are logged and visible to your team.
* Empty clinical states are clear in the UI.

## Decide before you build

Before you wire Patient Summary into production, align on a few product decisions. Agree where clinicians see the summary, when generation runs, and how your UI handles missing appointments or missing history.

<AccordionGroup>
  <Accordion title="Define Your Pre-Visit Use Case">
    Be clear about **where** clinicians see Patient Summary and **when** they need it. Common examples include:

    * Morning schedule prep.
    * Patient profile chart review.
    * Appointment detail screens before the visit starts.

    Patient Summary is a short pre-visit overview. It is not Ambient note generation, and it is not Dictation. Use it when clinicians need concise prior-visit context before an upcoming appointment.

    Start with one surface for the pilot, for example schedule preview or patient profile. Adding every clinical screen at once slows your first success path.
  </Accordion>

  <Accordion title="Plan CKG Ingestion">
    Before you build your ingestion path, decide:

    * Which patients and schedule data you upload each day.
    * How often you refresh problems, medications, and prior-visit history.
    * How you keep `fhir_encounter_id` and `fhir_practitioner_id` consistent across ingestion, generation, and retrieval.
    * How you log `organization_id`, `transaction_id`, and `correlation_id` for support.

    Treat CKG freshness as a product requirement. Incomplete or stale ingestion can still start a generation job, but the summary sections will be thin or empty.
  </Accordion>
</AccordionGroup>

## Authentication

Use the authentication model your partnership already follows for Suki Partner APIs.

* Keep `partner_token` and signing material on your backend only.
* Use `sdp_suki_token` for Patient Summary generation, status, and retrieval calls.
* Use the required SDP JWT bearer token for CKG Data Ingestion endpoints.
* Refresh tokens before expiry instead of waiting for unauthorized failures during clinic hours.
* Scope credentials by environment. Do not reuse staging secrets in production.

Refer to [Partner authentication](/documentation/how-to/partner-authentication) and [Patient Summary authentication](/patient-summary-api-reference/authentication) guides for more details.

## Polling recommendations

Patient Summary has two polling surfaces:

* CKG ingestion status after upload.
* Summary job status after generation.

Recommended approach:

* Poll about every **5 seconds** at first.
* Add backoff if a job is still running after the first minute.
* Set a maximum polling window so a stuck job cannot loop forever.
* Stop immediately on terminal statuses such as `COMPLETED`, `FAILED`, `ABORTED`, or `ARCHIVED`.
* For scheduled bulk generation, update each appointment as it completes instead of waiting for the entire schedule.

<Tip>
  Do not poll so aggressively that you create unnecessary load during morning login spikes.
</Tip>

## Retry strategies

Retry only when retrying is safe and useful.

| Failure                  | What to do                                                                             |
| :----------------------- | :------------------------------------------------------------------------------------- |
| Upload URL expired       | Request a new upload URL, then upload again.                                           |
| Transient network or 5xx | Retry with backoff. Preserve the same `correlation_id` when uploading related updates. |
| Ingestion failed         | Inspect logs, fix the bundle or auth issue, then upload again.                         |
| Generation failed        | Confirm CKG readiness and identifiers, then regenerate.                                |
| Summary already exists   | Do not create another summary unless you intentionally refreshed FHIR data.            |
| Identifier mismatch      | Fix the IDs first. Retrying with the same mismatch will not help.                      |

<Tip>
  For clinic-day operations, prefer an early daily ingestion and generation pass so retries happen before providers are in rooms.
</Tip>

## Handling failures

Separate system failures from clinical empty states.

* **No upcoming appointment** is not an API failure. Show that an appointment is required to view the summary.
* **No prior record found** is a valid clinical state. Show **About this visit** and **Problems**, and state that no record was found under **Summary** and **Previous visits**.
* **Ingestion failed** and **generation failed** are system failures. Log them, alert on them, and provide a fallback such as manual chart review.

When a failure affects a clinician-facing screen, show a short recovery message and keep the rest of the patient profile usable.

## Logging

Log enough to reconstruct one appointment path through the system.

Capture at least:

* `organization_id`
* `transaction_id` for ingestion
* `correlation_id` when provided
* `fhir_encounter_id`
* `fhir_practitioner_id`
* `patient_summary_id` when returned
* HTTP status code and error response body
* Job status transitions and timestamps

These fields are also what support needs when an upload or generation issue requires investigation.

## Monitoring

Monitor both technical health and clinic readiness.

Useful signals:

* Ingestion success rate and time to complete
* Generation success rate and time per appointment
* Count of appointments still preparing at clinic open
* Rate of empty prior-history summaries
* Rate of “no upcoming appointment” views versus true generation failures
* Retry volume and repeated failures for the same encounter

Alert when morning ingestion or schedule generation falls behind the window your clinic operations expect.

## Performance considerations

* Ingest once per morning for the day's schedule where possible.
* Pre-generate summaries before peak login instead of generating only when a patient is opened.
* Skip generation when a summary already exists for the appointment.
* Retrieve pre-visit sections for dense schedule UIs, and full summaries for chart review.
* Cache completed summary payloads for the appointment lifetime when your product and privacy rules allow it.

<Note>
  - Generation can take roughly **20 seconds per appointment** after the request is accepted. Design loading states around that expectation, especially for bulk schedule runs.
  - Summary content, lookback period, and length depend on your implementation and configured requirements.
</Note>

## Voice-first clinician UI

If your product supports **voice commands**, design Patient Summary so clinicians can open and navigate sections quickly during busy clinic flow.

* Keep section names stable.
* Keep empty states clear and easy to speak.
* Avoid hiding “no appointment” or “no prior record” messages behind nested menus.
* Make it easy to open, reread, and move between **About this visit**, **Summary**, **Previous visits**, and **Problems**.

## Security considerations

* Keep all Patient Summary and CKG credentials server-side.
* Transmit clinical data only over HTTPS.
* Limit access to summary content to authorized clinical users for the relevant patient and encounter.
* Avoid writing full PHI-rich request and response bodies into unrestricted logs.
* Retain support identifiers without copying more clinical text than your security policy allows.
* Rotate credentials according to your organization policy.
* Validate that `fhir_encounter_id` and `fhir_practitioner_id` match the authenticated clinical context your application already trusts.

## Next steps

Continue with the following guides:

* [Patient Summary basic usage](/documentation/how-to/patient-summary/basic-usage) to implement the end-to-end API workflow.
* [Patient Summary API quickstart](/patient-summary-api-reference/quickstart) to validate the flow on staging.
* [Error messages](/patient-summary-api-reference/error-messages-patient-summary) to interpret Patient Summary API errors.