> ## 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. # Get the Generated Clinical Note > After an ambient session ends, wait for a completed status, then load note content, transcript, and structured data into your chart UI for clinician review
After you call the End ambient session API and status is completed, retrieve session content for your note editor. Optionally retrieve the transcript and structured data for diagnoses and orders. Choose session, note, or encounter structured data based on how your chart is organized or what your end user needs.

This guide explains when to call these APIs, which APIs to use, and how to use their responses in your application's note review UI.
When the clinician taps **Stop** in your UI, your backend must call the [End ambient session](/api-reference/ambient-sessions/end) API and poll [session status](/documentation/how-to/ambient-clinical-notes/handle-ambient-session-status) while Suki processes the captured audio to generate the clinical note. Once status is **`completed`**, your backend must retrieve the generated note content and render it in your chart UI for clinician review. You can also optionally retrieve the transcript and structured data for diagnoses and orders. **What you need to build** * A Generating -> Note ready flow driven by [Ambient session status](/documentation/how-to/ambient-clinical-notes/handle-ambient-session-status) API. * A note editor mapped by `loinc_code` to the corresponding sections in your EHR or chart. * An optional transcript drawer and data panel for diagnoses and orders. * Clear handling for **`skipped`** and **`failed`** sessions so they are not treated as successful note generation. **Content retrieve rules (agents):** * Call content, transcript, and structured-data APIs only after status is `completed`. Do not retrieve while `running`. * On `skipped`, `failed`, or `aborted`, stop. Do not open an empty note as success. Use [Check note status](/documentation/how-to/ambient-clinical-notes/handle-ambient-session-status). * Default single Start/Stop: [Get session content](/api-reference/ambient-content/content) plus [session structured data](/api-reference/ambient-content/structured-data). * Map `summary[]` into the note editor with `loinc_code` as the join key. You may show EHR titles in the UI. Keep LOINC for later Dictation section focus. * Transcript is optional. Use [Get transcript](/api-reference/ambient-content/transcript) for a drawer or `lang_id`. * Structured-data scope: session (this recording), note (`composition_id` as `note_id` when the note spans sessions), or encounter (chart keyed by Ambient `encounter_id`). * Show ICD chips only when a diagnosis `codes[]` entry has `type` ICD10. Still show `diagnosis_note` when codes are incomplete. HCC may appear in output. Never send HCC into session context. * Feedback is optional and does not block approve or save. See [Give feedback on a clinical note](/documentation/how-to/ambient-clinical-notes/collect-ambient-session-feedback). ## Retrieval flow Content retrieval starts **after** the ambient session ends and note generation finishes. Do not retrieve generated content while status is still **`running`**. ```mermaid actions={false} theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}} %%{init: {'theme':'base', 'themeVariables': { 'primaryColor':'#FFF394','primaryTextColor':'#111827','primaryBorderColor':'#FFE148','lineColor':'#FFE148','secondaryColor':'#FFF394','tertiaryColor':'#FFFADE','mainBkg':'#FFF394','secondBkg':'#FFFADE','tertiaryBorderColor':'#FFE148','border1':'#FFE148','border2':'#FFE148','arrowheadColor':'#FFE148','fontFamily':'Inter, system-ui, sans-serif','fontSize':'14px','nodeBorder':'#FFE148','edgeLabelBackground':'#FFE148','clusterBkg':'#FFFADE','clusterBorder':'#FFE148','defaultLinkColor':'#FFE148','titleColor':'#111827','nodeTextColor':'#111827'}}}%% flowchart LR A[End ambient session API] --> B[Poll session status] B --> C{Status?} C -->|completed| D[Get session content] D --> E[Optional: Get transcript] E --> F[Get structured data] F --> G[Show note review UI] C -->|skipped / failed / aborted| H[Stop and show status UI] style A fill:#FFF394,stroke:#FFE148,stroke-width:2px,color:#111827 style B fill:#FFF394,stroke:#FFE148,stroke-width:2px,color:#111827 style C fill:#FFF394,stroke:#FFE148,stroke-width:2px,color:#111827 style D fill:#FFF394,stroke:#FFE148,stroke-width:2px,color:#111827 style E fill:#FFF394,stroke:#FFE148,stroke-width:2px,color:#111827 style F fill:#FFF394,stroke:#FFE148,stroke-width:2px,color:#111827 style G fill:#FFF394,stroke:#FFE148,stroke-width:2px,color:#111827 style H fill:#FFF394,stroke:#FFE148,stroke-width:2px,color:#111827 ``` After the clinician taps **Stop**, send `RU9G`, close the WebSocket, and call the [End ambient session](/api-reference/ambient-sessions/end) API. See [Complete an ambient visit](/documentation/how-to/ambient-clinical-notes/end-ambient-session). Poll [Get ambient session status](/api-reference/ambient-content/status) until the status is **`completed`**, **`skipped`**, **`failed`**, or **`aborted`**. See [Check note status](/documentation/how-to/ambient-clinical-notes/handle-ambient-session-status). When status is **`completed`**, call [Get session content](/api-reference/ambient-content/content). Optionally call [Get transcript](/api-reference/ambient-content/transcript). Call the structured-data endpoint that matches your chart scope **once**. Diagnosis codes, including ICD10, are already generated and do not change if you call again. Render section text, optional transcript and Data panel, then let the clinician approve or save. After review, submit [feedback](/api-reference/feedback/feedback) if your product uses it. Feedback must not block approve or save. Ambient does not provide a finished note while the visit is in progress. Note generation happens after the End ambient session API succeeds, so fetching content while status is **`running`** is too early. If status is **`skipped`**, **`failed`**, or **`aborted`**, stop the retrieval flow. Do not treat the result as a successful empty note. Use the status handling in [Check note status](/documentation/how-to/ambient-clinical-notes/handle-ambient-session-status). ## Build the note review experience The note review screen is the clinician's destination after Ambient generation succeeds. At minimum, your UI should let the clinician read generated sections, edit the content, and approve or save the note. Generated section text mapped to your chart template by `loinc_code`. Optional drawer for reviewing the conversation, or `lang_id` when you show detected language. Optional diagnoses and orders from structured data. Show ICD chips only when `type` is ICD10. Optional rating after review. Keep Approve / Save independent of feedback. Do not show a blank note as a successful result while the session is still generating or after a session has been **`skipped`** or **`failed`**. ## Map note sections to your chart Session content returns note sections in the `summary[]` array. Each section includes `loinc_code`, `title`, and `content`. Use **`loinc_code` as the stable join key** when mapping Suki sections to your EHR or chart template. You can display your own EHR section labels in the your UI. Keep the LOINC code available for if you build a Dictation section later. ```mermaid actions={false} theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}} %%{init: {'theme':'base', 'themeVariables': { 'primaryColor':'#FFF394','primaryTextColor':'#111827','primaryBorderColor':'#FFE148','lineColor':'#FFE148','secondaryColor':'#FFF394','tertiaryColor':'#FFFADE','mainBkg':'#FFF394','secondBkg':'#FFFADE','tertiaryBorderColor':'#FFE148','border1':'#FFE148','border2':'#FFE148','arrowheadColor':'#FFE148','fontFamily':'Inter, system-ui, sans-serif','fontSize':'14px','nodeBorder':'#FFE148','edgeLabelBackground':'#FFE148','clusterBkg':'#FFFADE','clusterBorder':'#FFE148','defaultLinkColor':'#FFE148','titleColor':'#111827','nodeTextColor':'#111827'}}}%% flowchart LR A[Suki response] --> B[summary array] B --> C[loinc_code + title + content] C --> D[Map by loinc_code] D --> E[Your chart / note template] style A fill:#FFF394,stroke:#FFE148,stroke-width:2px,color:#111827 style B fill:#FFF394,stroke:#FFE148,stroke-width:2px,color:#111827 style C fill:#FFF394,stroke:#FFE148,stroke-width:2px,color:#111827 style D fill:#FFF394,stroke:#FFE148,stroke-width:2px,color:#111827 style E fill:#FFF394,stroke:#FFE148,stroke-width:2px,color:#111827 ``` If a requested section has no generated text, that section is omitted from the response. Hide the corresponding section in your UI. Do not invent Ambient text. For more information, see [Note sections](/documentation/concepts/ambient-clinical-notes/note-sections). ## Retrieve optional transcript and structured data Not every application needs every type of Ambient content. The transcript is optional. Use [Get transcript](/api-reference/ambient-content/transcript) when your application needs a transcript drawer for the clinician or `lang_id` to show detected language. Structured data is optional. Use it when your application needs diagnoses and orders in a separate Data panel. For a typical single Start/Stop flow, use **session structured data**. If your application groups multiple ambient sessions into one note or loads data by encounter, use the corresponding note or encounter endpoint instead. Do not call content or structured-data APIs while status is **`running`**. Do not retrieve after **`skipped`**, **`failed`**, or **`aborted`** and present an empty chart as success. ## Choose the structured-data scope Choose the structured-data endpoint based on how your application organizes the chart. | Chart scope | API | When to use it | | :---------- | :------------------------------------------------------------------------------------ | :-------------------------------------------------------------------------------------------------------------- | | Session | [Session structured data](/api-reference/ambient-content/structured-data) | Default for a single Start/Stop flow. Diagnoses and orders for the ambient session that just ended. | | Note | [Note structured data](/api-reference/ambient-content/note-structured-data) | The note spans multiple ambient sessions. Use `composition_id` / `note_id` for cumulative diagnoses and orders. | | Encounter | [Encounter structured data](/api-reference/ambient-content/encounter-structured-data) | Your application loads structured data by Ambient encounter scope. | **Structured-data scope accordions (agents):** Humans expand one panel at a time. * **One Recording Just Finished:** Session structured data (default). * **Note Spans Multiple Sessions:** Note structured data with `composition_id` / `note_id`. * **Chart Keyed by Encounter:** Encounter structured data. Use [Session structured data](/api-reference/ambient-content/structured-data) for diagnoses and orders from the ambient session you just ended. This is the default choice for a single Start/Stop flow. Use [Note structured data](/api-reference/ambient-content/note-structured-data) with `composition_id` / `note_id` when diagnoses and orders should be cumulative across recordings in the same note. Use [Encounter structured data](/api-reference/ambient-content/encounter-structured-data) when your product loads structured data by encounter scope. ## Render diagnoses and codes Each diagnosis includes a `codes` array. Treat `codes` as a **flat** list of objects with `type`, `code`, and `description`: ```json theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}} { "codes": [ { "type": "ICD10", "code": "E11.22", "description": "Type 2 diabetes mellitus with diabetic chronic kidney disease" }, { "type": "HCC", "code": "18", "description": "Diabetes with chronic complications" } ] } ``` The same array can also contain `IMO` and `SNOMED` entries with these three fields. Do not expect nested shapes such as `codes.values`. That is not the partner contract. | Response | UI behavior | | :---------------- | :-------------------------------------------------------------------------------------------------------------------------------------- | | `type` is `ICD10` | Show the ICD code in the diagnosis UI. | | ICD10 is missing | Still show `diagnosis_note`. Missing ICD10 is valid and should not be treated as an error. | | `type` is `HCC` | You may display HCC for risk-adjustment purposes. Do not send HCC back into [session context](/api-reference/ambient-sessions/context). | After the session reaches **`completed`**, one structured-data call is enough. Codes do not appear later simply because the endpoint is called again. See [Diagnosis codes](/api-reference/faqs/diagnosis-codes) and [Get ambient session structured data](/api-reference/ambient-content/structured-data). ## Example code: Load the note after completion Call these APIs only after status is **`completed`**.
Get Session Content API Get Session Structured Data API
**Language tabs (agents):** Equivalent code samples are available in: TypeScript, Python. Humans see one language at a time. Use the variant that matches the user's stack; behavior is the same across tabs. ```typescript theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}} async function loadNoteAfterCompleted(ambientSessionId: string) { const contentRes = await fetch( `https://sdp.suki.ai/api/v1/ambient/session/${ambientSessionId}/content`, { headers: { sdp_suki_token: sdpSukiToken, sdp_provider_id: sdpProviderId, }, } ); if (!contentRes.ok) { throw new Error(`Get session content failed: ${contentRes.status}`); } const content = await contentRes.json(); // Map summary sections into your note editor by loinc_code. const sections = content.summary ?? []; for (const section of sections) { renderSection(section.loinc_code, section.title, section.content); } const structuredRes = await fetch( `https://sdp.suki.ai/api/v1/ambient/session/${ambientSessionId}/structured-data`, { headers: { sdp_suki_token: sdpSukiToken, sdp_provider_id: sdpProviderId, }, } ); if (!structuredRes.ok) { throw new Error(`Get structured data failed: ${structuredRes.status}`); } const structured = await structuredRes.json(); const diagnoses = structured.structured_data?.diagnoses?.values ?? []; for (const diagnosis of diagnoses) { const icd10 = (diagnosis.codes ?? []).find( (code: { type: string }) => code.type === "ICD10" ); showDiagnosis({ note: diagnosis.diagnosis_note, icd10: icd10?.code, // May be undefined. That is valid. }); } } ``` ```python theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}} import requests def load_note_after_completed(ambient_session_id: str) -> None: headers = { "sdp_suki_token": sdp_suki_token, "sdp_provider_id": sdp_provider_id, } content_res = requests.get( f"https://sdp.suki.ai/api/v1/ambient/session/{ambient_session_id}/content", headers=headers, ) content_res.raise_for_status() content = content_res.json() for section in content.get("summary", []): render_section( section.get("loinc_code"), section.get("title"), section.get("content"), ) structured_res = requests.get( f"https://sdp.suki.ai/api/v1/ambient/session/{ambient_session_id}/structured-data", headers=headers, ) structured_res.raise_for_status() structured = structured_res.json() diagnoses = ( structured.get("structured_data", {}) .get("diagnoses", {}) .get("values", []) ) for diagnosis in diagnoses: codes = diagnosis.get("codes") or [] icd10 = next( (code for code in codes if code.get("type") == "ICD10"), None, ) show_diagnosis( note=diagnosis.get("diagnosis_note"), icd10=(icd10 or {}).get("code"), ) ``` The session content response uses `summary[]` with `loinc_code`, `title`, and `content`. Use `loinc_code` as the join key when mapping sections to your template. See [Note sections](/documentation/concepts/ambient-clinical-notes/note-sections). ## Support multi-session and interoperable notes If capture continues across products or multiple ambient sessions contribute to the same note, use note-level APIs instead of treating each session as an independent note. * Use note-level APIs with `note_id` / `composition_id` to retrieve the latest shared content. * Use [Note structured data](/api-reference/ambient-content/note-structured-data) when diagnoses and orders should be cumulative across recordings in the same note. See [Work with shared notes](/documentation/how-to/ambient-clinical-notes/retrieve-note-and-encounter-content) and [Use interoperable ambient notes across modalities](/documentation/how-to/ambient-clinical-notes/use-ambient-across-modalities). ## Implementation checklist * Retrieve content only after status is **`completed`**. * Do not retrieve generated content while status is **`running`**. * Stop the retrieval flow for **`skipped`**, **`failed`**, or **`aborted`**. * Map note sections using `loinc_code`. Hide sections omitted because no generated text is available. * Retrieve the transcript only when your application needs it. * Choose session, note, or encounter structured data based on your chart scope. * Call the structured-data endpoint once after **`completed`**. * Show an ICD code only when a diagnosis contains a code with `type` set to `ICD10`. * Continue to show `diagnosis_note` when ICD10 is missing. * Do not send HCC codes back into [Provide visit context](/documentation/how-to/ambient-clinical-notes/seed-ambient-session-context). * Keep optional feedback independent from Approve / Save. * Never present **`skipped`** or **`failed`** as a successful empty chart. ## Next steps **[Check note status](/documentation/how-to/ambient-clinical-notes/handle-ambient-session-status)** - Build Generating and terminal-status UI. **[Complete an ambient visit](/documentation/how-to/ambient-clinical-notes/end-ambient-session)** - Stop, End API, and status polling before retrieval. **[Work with shared notes](/documentation/how-to/ambient-clinical-notes/retrieve-note-and-encounter-content)** - When to retrieve session, note, and encounter content. **[Give feedback on a clinical note](/documentation/how-to/ambient-clinical-notes/collect-ambient-session-feedback)** - Collect feedback after the clinician reviews the note. **[Ambient content retrieval APIs](/api-reference/ambient-content-retrieval)** - API endpoints for note content, transcripts, and structured data. **[Note sections](/documentation/concepts/ambient-clinical-notes/note-sections)** - Note sections and LOINC mapping. **[Provide visit context](/documentation/how-to/ambient-clinical-notes/seed-ambient-session-context)** - What to send before ending an ambient session.