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

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

Which Retrieve API Should I Call

• This recording only: Use Session content with ambient_session_id.
• Shared note across sessions: Use Note content with note_id.
• Optional transcript: Use Get transcript after status is completed.
• Do not retrieve while status is still running, or treat skipped / failed as a successful note.

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.

Prerequisites

• Session status is completed for the ambient_session_id you will query. See Check note status.
• A valid Suki Token. See Partner authentication.
• Stored identifiers for the retrieve path you need (ambient_session_id, and note_id when you use note-level APIs).

Retrieval flow

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

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

2. Wait for a Completed Status

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

3. Retrieve Session Content

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

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

5. Show the Note Review UI

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

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

Sample session content response

After status is completed, Get session content returns the generated note in summary[], with optional structured_data blocks in the same response. Expand the sample to inspect a real-shaped payload and the Ambient APIs that produce it.

Sample API Response

{
  "summary": [
    {
      "title": "PROCEDURE",
      "content": "- Prescription of medication for symptomatic relief\n- Recommendation for RT PCR test",
      "source_transcripts": [],
      "loinc_code": "47519-4"
    },
    {
      "title": "RESULTS",
      "content": "- RT PCR test scheduled",
      "source_transcripts": [],
      "loinc_code": "30954-2"
    },
    {
      "title": "ASSESSMENT AND PLAN",
      "content": "1. Potential COVID-19 exposure\nThe patient's daughter exhibits symptoms that may align with a viral infection, including fever and cough, possibly COVID-19. Given the prevalence of COVID-19, I recommended an RT PCR test to rule out infection. Precautionary isolation and symptomatic treatment are advised if results return positive. I emphasized staying hydrated and will review further care as needed.",
      "source_transcripts": [],
      "loinc_code": "51847-2"
    },
    {
      "title": "CHIEF COMPLAINT",
      "content": "\"I'm doing good, doctor, but my daughter isn't doing well.\"",
      "source_transcripts": [],
      "loinc_code": "10154-3"
    },
    {
      "title": "REASON FOR VISIT",
      "content": "Consultation for concerns regarding daughter's symptoms possibly related to COVID-19 exposure.",
      "source_transcripts": [],
      "loinc_code": "29299-5"
    },
    {
      "title": "HISTORY OF PRESENT ILLNESS",
      "content": "The patient is a 26-year-old male presenting with concerns over his daughter's symptoms, suggestive of possible COVID-19 exposure. The daughter returned from Pune, where her college had closed due to COVID-19 concerns, and began displaying symptoms of high fever and persistent cough soon after. In response to the father's concerns and to address the possibility of a COVID-19 infection, I instructed that an RT PCR test be performed. Until results are obtained, symptomatic relief through medication and maintaining hydration was advised. Should the test confirm a COVID-19 infection, isolation protocols are recommended to prevent transmission. Arrangements were made for the daughter's further assessment.",
      "source_transcripts": [],
      "loinc_code": "10164-2"
    }
  ],
  "structured_data": []
}

APIs used for this sample

This payload comes from Get session content after a completed ambient visit. Empty structured_data means no diagnosis or order blocks were generated here.

1. Create ambient session: Start the visit recording.
2. Provide visit context: Pass LOINC sections such as 10154-3 and 10164-2.
3. Stream ambient audio: Send live audio over WebSocket.
4. End ambient session: Stop capture and start note generation.
5. Get session status: Poll until status is completed.
6. Get session content: Returns this summary[] response.

Optional: Get transcript for the conversation drawer. That endpoint is separate from this sample.

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 note_id for cumulative diagnoses and orders.
Encounter	Encounter structured data	Your application loads structured data by Ambient encounter scope.

If you seeded Embedded Form templates, session and encounter structured data also return the filled values in structured_data.section_structured_values. Note structured data does not include them. Refer to Seed and read Embedded Forms.

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

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

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

Troubleshooting

Retrieval problems are almost always status timing or treating a terminal non-success status as an empty chart.

Note Looks Blank while Still Generating

Do not show a blank note as a successful result while status is still running. Keep Generating note… until status is completed, then load content.

Status Is Skipped, Failed, or Aborted

Stop the retrieval flow. Do not treat the result as a successful empty note. Use Check note status for the UI each status needs.

Content Called before Completed

Call content, transcript, and structured-data APIs only after status is completed. Polling status and retrieving content are separate steps.

ICD Codes Missing on Diagnoses

Show an ICD code only when a diagnosis contains a code with type set to ICD10. Keep showing diagnosis_note when ICD10 is missing, and do not send HCC codes back into seed context.

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