Get the Generated Clinical Note

Quick summary

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.

Last updated:August 2026

When the clinician taps Stop in your UI, your backend must call the End ambient session API and poll 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 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.

Retrieval flow

Content retrieval starts after the ambient session ends and note generation finishes. Do not retrieve generated content while status is still running.

End the Ambient Session

After the clinician taps Stop, send RU9G, close the WebSocket, and call the End ambient session API. See Complete an ambient visit.

Wait for a Completed Status

Poll Get ambient session status until the status is completed, skipped, failed, or aborted. See Check note status.

Retrieve Session Content

When status is completed, call Get session content. Optionally call Get transcript.

Retrieve Structured Data

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.

Show the Note Review UI

Render section text, optional transcript and Data panel, then let the clinician approve or save.

Optionally Collect Feedback

After review, submit 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.

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.

Note Editor

Generated section text mapped to your chart template by loinc_code.

Transcript

Optional drawer for reviewing the conversation, or lang_id when you show detected language.

Data Panel

Optional diagnoses and orders from structured data. Show ICD chips only when type is ICD10.

Feedback and Approve

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

Retrieve optional transcript and structured data

Not every application needs every type of Ambient content.

When to Use the Transcript

The transcript is optional. Use Get transcript when your application needs a transcript drawer for the clinician or lang_id to show detected language.

When to Use Structured Data

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.

When Not to Retrieve

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	Default for a single Start/Stop flow. Diagnoses and orders for the ambient session that just ended.
Note	Note structured data	The note spans multiple ambient sessions. Use `composition_id` / `note_id` for cumulative diagnoses and orders.
Encounter	Encounter structured data	Your application loads structured data by Ambient encounter scope.

One Recording Just Finished

Use Session structured data for diagnoses and orders from the ambient session you just ended. This is the default choice for a single Start/Stop flow.

The Note Spans Multiple Ambient Sessions

Use Note structured data with composition_id / note_id when diagnoses and orders should be cumulative across recordings in the same note.

The Chart Is Keyed by Encounter

Use 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:

{
  "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.

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 and Get ambient session 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

TypeScript
Python

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.
    });
  }
}

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.

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 when diagnoses and orders should be cumulative across recordings in the same note.

See Work with shared notes and Use interoperable ambient notes 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.
Keep optional feedback independent from Approve / Save.
Never present skipped or failed as a successful empty chart.

Next steps

Check note status - Build Generating and terminal-status UI. Complete an ambient visit - Stop, End API, and status polling before retrieval. Work with shared notes - When to retrieve session, note, and encounter content. Give feedback on a clinical note - Collect feedback after the clinician reviews the note. Ambient content retrieval APIs - API endpoints for note content, transcripts, and structured data. Note sections - Note sections and LOINC mapping. Provide visit context - What to send before ending an ambient session.

Get Started

Concepts & Feature Guides

Resources

FAQs & Support

Get the Generated Clinical Note

Retrieval flow

Build the note review experience

Note Editor

Transcript

Data Panel

Feedback and Approve

Map note sections to your chart

Retrieve optional transcript and structured data

Choose the structured-data scope

Render diagnoses and codes

Example code: Load the note after completion

Support multi-session and interoperable notes

Implementation checklist

Next steps

​Retrieval flow

​Build the note review experience

Note Editor

Transcript

Data Panel

Feedback and Approve

​Map note sections to your chart

​Retrieve optional transcript and structured data

​Choose the structured-data scope

​Render diagnoses and codes

​Example code: Load the note after completion

​Support multi-session and interoperable notes

​Implementation checklist

​Next steps

Retrieval flow

Build the note review experience

Map note sections to your chart

Retrieve optional transcript and structured data

Choose the structured-data scope

Render diagnoses and codes

Example code: Load the note after completion

Support multi-session and interoperable notes

Implementation checklist

Next steps