Skip to main content
Quick summary
Use session content for one recording. Use note-level APIs with composition_id as note_id when the shared note may include more recordings or Web SDK edits. Use list encounter notes with emr_encounter_id when the chart opens on the EHR visit. Encounter content uses Ambient encounter_id, not emr_encounter_id.
Last updated:August 2026
Get the generated clinical note covers the simplest workflow: the clinician starts and stops one ambient session. Your application waits for the session to complete, then retrieves the generated note. Real workflows can be more complex. A visit may have:
  • More than one ambient session.
  • A note that was edited in a headed product such as Web SDK.
  • A note that your application needs to find using an EMR encounter.
In these cases, retrieve the note based on what your screen represents. The identifier you use depends on that scope. Each retrieve API uses one of these identifiers. Do not mix ambient_session_id, note_id, Ambient encounter_id, and emr_encounter_id on the same request.

​
Choose the scope that matches your screen

This lets your application show the note that belongs to the workflow the clinician is viewing. For example, if the clinician opens a chart by EMR encounter, call list encounter notes with that emr_encounter_id, then load the selected note with note-level APIs. Do not retrieve only one ambient session when the screen represents the full EMR visit. Using the correct scope also helps your application:
  • Show the latest shared note when recording continues on another device.
  • Show edits that were already made in Web SDK.
  • Find all notes associated with an EMR encounter when the workflow includes multiple notes.

​
What your application needs to track

Store the identifiers needed for the workflows your application supports:
  • ambient_session_id for an individual ambient session.
  • composition_id, used as note_id, for a generated note.
  • emr_encounter_id when the note is associated with an EMR encounter.
  • Ambient encounter_id when your workflow groups re-ambient sessions on the same note.
For note rendering, map note sections using loinc_code at the scope supported by the API you are calling. See Note sections.
If your screen represents one generated note, retrieve it with composition_id as note_id. See Fetch note content with composition_id for a request example. Use this page when you still need to choose among ambient_session_id, note_id, emr_encounter_id, and Ambient encounter_id.

​
Decide which content to load

Pick the API that matches the screen the clinician is opening. Do not mix session and note IDs on the same request.

Session Content

What you get:
  • Note sections for one ambient recording
  • Session structured data for diagnoses and orders from that recording
When to call:
  • Call after that session status is completed.
  • Use this path right after a single Start/Stop on this client.
  • Use this path when the clinician is reviewing only the recording they just ended.

Note Content

What you get:
  • Accumulated section content across every ambient session on the shared note
  • The latest edited section text after clinicians review or edit in Web SDK
When to call:
  • Pass composition_id from create as note_id.
  • Use this path when the note spans more than one recording.
  • Use this path after headed-product review, before you write the note back to the EHR.

List Encounter Notes

What you get:
  • Every note tied to the EMR visit, including finished and unfinished notes
  • Each note id to pass as note_id on note-level APIs
When to call:
  • Pass the same emr_encounter_id you sent on create.
  • Use this path when the chart opens on the EHR visit and must list notes.
  • Cross-modality notes require emr_encounter_id on create. Without it, notes are not interoperable across modalities.

Encounter Content

What you get:
  • Cumulative content and structured data for the ambient encounter grouping
  • Empty requested sections included, even when the body is blank
When to call:
  • Pass Ambient encounter_id from create (the re-ambient grouping ID).
  • Use this path when your product loads cumulative content by ambient encounter.
  • Do not pass emr_encounter_id here. That ID belongs to list encounter notes.

​
How the identifiers relate

Create returns ambient_session_id and composition_id. Your application provides emr_encounter_id and Ambient encounter_id on create when you use them, then stores those values with the visit. Pass the ID that matches each retrieve API. For field rules and product naming, see Interoperable identifiers.
Do not pass emr_encounter_id to encounter content or encounter structured data. Those endpoints use Ambient encounter_id. List encounter notes is the EMR-keyed list API.
Cross-modality workflows require emr_encounter_id on create. Without it, Suki still creates an ambient session, but the note is not interoperable across modalities. See Ambient interoperability.

​
Typical workflow for retrieving note and encounter content

1

Store IDs at Create

Keep ambient_session_id and composition_id from Create an ambient clinical note. Store emr_encounter_id and re-ambient encounter_id when you use them. Do not ask the clinician to enter these identifiers.
2

Wait for Generated Content

For the recording you just ended, poll session status until it is completed before you call session content. List encounter notes can still return unfinished notes. Do not treat those as finished chart text.
3

Pick Session, Note, List, or Encounter

Single recording on this client: session content. Shared note or Web SDK edits: note content with note_id. Chart opens by EMR visit: list encounter notes, then note-level APIs. Chart keyed by an ambient encounter: encounter content.
4

Map Sections by LOINC

Render note sections with loinc_code as the join key. Show your EHR titles in the UI. Hide sections omitted from session content. For encounter content, empty bodies can still appear. Do not invent note text. See Note sections.

​
When to use each API

Use session content and session structured data with ambient_session_id.This is the default after a single Start/Stop on one client, right after that recording completes. Empty requested sections are omitted. Hide them in the UI.For the full note-review UI after End, see Get the generated clinical note.
Use note content, note context, and note structured data. Pass composition_id from create as note_id.Note content accumulates every ambient session on that note. Use this when capture continues later in the same visit, or when Mobile SDK, Ambient APIs, and Web SDK share the note.See Use interoperable ambient notes across modalities.
Prefer note content when clinicians reviewed or edited the note in a headed product such as Web SDK.For edited sections, the response returns the latest edited section content. Session content is only for one ambient session. After headed review, use note content so your EHR write-back is not missing those edits.See Ambient interoperability.
Use List encounter notes with the same emr_encounter_id you sent on create.The list can include finished and unfinished notes. Use each returned note id as note_id for note-level calls. One EMR encounter can contain multiple clinical notes.
Use encounter content and encounter structured data when your product loads cumulative content by Ambient encounter_id (the re-ambient grouping ID you sent on create).This is not emr_encounter_id. Encounter content can include empty sections from the composition. Session content omits them.

​
How to choose the right API

You usecase determines the API you use and based on the API you use, you pass the corresponding ID. For example, if you are retrieving the note content for a shared note, you would pass the composition_id as note_id.

​
When to use note content after Web SDK edits

Use Get note content when your application must stay in sync with a note clinicians already opened in the headed Web SDK (or another headed product).
  • Session content returns one ambient session. It is the default after a single Start/Stop on your client.
  • Note content returns accumulated section content across ambient sessions on that note. If clinicians edited sections in Web SDK, the response includes the latest edited section content.
  • Pass composition_id from Create an ambient clinical note as note_id.
If capture started on Ambient APIs or Mobile SDK and the clinician edited in Web SDK, read the note back with note content. Do not assume session content includes those headed edits.

​
Example code for loading latest note content by composition_id

Get Note Content APIList Encounter Notes API
Note content uses summary[] with loinc_code, title, and content, the same join key as session content. Map sections into your chart template by loinc_code.

​
Available cookbooks

AmbientAPI

​
Fetch Note Content with composition_id

Retrieve the shared note with composition_id as note_id.

5 min
AmbientAPI

​
Poll Session Status Before Fetching Content

Wait for completed before you retrieve generated content.

5 min

​
Implementation checklist

  • Store ambient_session_id, composition_id as note_id, and emr_encounter_id when the note is interoperable.
  • Use session APIs for one recording. Use note APIs after Web SDK edits or multiple sessions.
  • Use list encounter notes for EMR-keyed charts. Use Ambient encounter_id for encounter content.
  • Wait until that session is completed before treating session content as finished.
  • Map sections by loinc_code. Hide omitted session sections. Do not invent note text for empty encounter sections.

​
Next steps

Get the generated clinical note - Default session retrieve path after End. Use interoperable ambient notes across modalities - Shared note workflow across products. Interoperable identifiers - emr_encounter_id, encounter_id, and note_id. Ambient content retrieval APIs - Endpoint cards. Get note content - Note-level request examples. Note sections - LOINC mapping and empty-section behavior.
Last modified on August 20, 2026