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

> Learn how to upload FHIR data to CKG, authenticate, generate a Patient Summary, poll job status, and retrieve summary content using Patient Summary APIs

<Info>
  **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).
</Info>

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 sign the SDP JWT used for CKG ingestion. 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. Request a CKG upload URL and upload a FHIR R4 bundle.
2. Poll ingestion status until CKG processing completes.
3. Authenticate and obtain an `sdp_suki_token`.
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.

<Note>
  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.
</Note>

## Upload FHIR data to CKG

Upload clinical data before you generate a summary.

### Request an upload URL

Call <Badge color="green" size="sm">GET</Badge> [Request FHIR bundle upload URL](/patient-summary-api-reference/ckg-data-ingestion/upload):

```bash theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
curl --request GET \
  --url 'https://sdp.suki-stage.com/api/v1/fhir-push/upload-url?organization_id=<organization_id>&correlation_id=<correlation_id>' \
  --header 'Authorization: Bearer <sdp_jwt_bearer_token>'
```

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":"github-dark","dark":"material-theme-darker"}}
curl --request PUT \
  --url '<upload_url>' \
  --header 'Content-Type: application/json' \
  --header 'x-goog-content-length-range: 0,524288000' \
  --data-binary @patient-fhir-bundle.json
```

### Poll ingestion status

Call <Badge color="green" size="sm">GET</Badge> [Check ingestion status](/patient-summary-api-reference/ckg-data-ingestion/ingestion-status):

```bash theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
curl --request GET \
  --url https://sdp.suki-stage.com/api/v1/fhir-push/status/<transaction_id> \
  --header 'Authorization: Bearer <sdp_jwt_bearer_token>'
```

Poll until status is `COMPLETED`. Do not trigger summary generation while ingestion is still running.

### Request details

* Authenticate CKG ingestion with an RS256-signed SDP JWT bearer token that includes the `sdp_partner_id` claim.
* 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

After CKG ingestion is complete, authenticate for generation and retrieval.

Call <Badge color="blue" size="sm">POST</Badge> [Login](/patient-summary-api-reference/authentication/login):

```bash theme={"theme":{"light":"github-dark","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_id>",
    "partner_token": "<partner_token>",
    "provider_id": "<provider_id>"
  }'
```

Example response:

```json theme={"theme":{"light":"github-dark","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 <Badge color="blue" size="sm">POST</Badge> [Generate Patient Summary for an encounter](/patient-summary-api-reference/summary-generation/encounter-summary):

```bash theme={"theme":{"light":"github-dark","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: <sdp_suki_token>' \
  --header 'sdp_provider_id: <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 <Badge color="green" size="sm">GET</Badge> [Generation status using encounter and practitioner IDs](/patient-summary-api-reference/summary-jobs/encounter-status):

```bash theme={"theme":{"light":"github-dark","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: <sdp_suki_token>' \
  --header 'sdp_provider_id: <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.

<Tip>
  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.
</Tip>

## Retrieve the Patient Summary

When status is `COMPLETED`, retrieve the summary content.

### Retrieve the full summary

Call <Badge color="green" size="sm">GET</Badge> [Patient Summary using partner identifiers](/patient-summary-api-reference/summaries/encounter-practitioner):

```bash theme={"theme":{"light":"github-dark","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: <sdp_suki_token>' \
  --header 'sdp_provider_id: <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 <Badge color="green" size="sm">GET</Badge> [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":"github-dark","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: <sdp_suki_token>' \
  --header 'sdp_provider_id: <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                       |

<Tip>
  Design your UI for partial data. If the patient has an upcoming appointment but no prior encounter record, show **About this visit** and **Problems**, and 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.
</Tip>

## Common integration patterns and use cases

### Pattern 1: Standard encounter flow

A typical encounter-based Patient Summary workflow follows these steps:

<Steps>
  <Step title="Upload FHIR Data">
    Request an upload URL, upload the FHIR bundle, and poll CKG ingestion until complete.
  </Step>

  <Step title="Authenticate">
    Call login and save `sdp_suki_token`.
  </Step>

  <Step title="Generate the Summary">
    Call [Generate Patient Summary for an encounter](/patient-summary-api-reference/summary-generation/encounter-summary).
  </Step>

  <Step title="Poll Job Status">
    Poll [Encounter status](/patient-summary-api-reference/summary-jobs/encounter-status) until the job is terminal.
  </Step>

  <Step title="Retrieve Summary Content">
    Call a [Patient Summaries](/patient-summary-api-reference/summaries) endpoint and render the sections in your UI.
  </Step>
</Steps>

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

<CardGroup cols={3}>
  <Card title="CKG Data Ingestion" icon="upload" href="/patient-summary-api-reference/ckg-data-ingestion" arrow={true}>
    Upload FHIR bundles into CKG
  </Card>

  <Card title="Generate for Encounter" icon="waveform" href="/patient-summary-api-reference/summary-generation/encounter-summary" arrow={true}>
    Start asynchronous summary generation
  </Card>

  <Card title="Retrieve Patient Summary" icon="table" href="/patient-summary-api-reference/summaries/encounter-practitioner" arrow={true}>
    Load completed summary content
  </Card>
</CardGroup>

## Best practices

<Tip>
  * **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.
</Tip>

## FAQs

<Accordion title="What If the Patient Has No Upcoming Appointment?">
  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.
</Accordion>

<Accordion title="What If the Patient Has an Appointment but No Prior Records?">
  Show **About this visit** and **Problems**. Under **Summary** and **Summary of previous visits**, show that no record was found.
</Accordion>

<Accordion title="Should I Generate Again Every Time the Provider Opens the App?">
  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.
</Accordion>

## Next steps

<Icon icon="file-lines" iconType="solid" /> [Patient Summary best practices](/documentation/how-to/patient-summary/best-practices) - Production polling, retries, logging, and security.

<Icon icon="file-lines" iconType="solid" /> [How Patient Summary works](/documentation/concepts/patient-summary/architecture) - Architecture, lifecycle, and data flow.

<Icon icon="file-lines" iconType="solid" /> [Patient Summary API quickstart](/patient-summary-api-reference/quickstart) - Full staging scripts for the same workflow.