Skip to main content
Quick summary
Headless Web SDK does not expose React hooks for note content. Use useGetEncounterInfo to list note and session identifiers for an EMR encounter, then call Ambient API note-level endpoints with noteId. When the note may later open in the Web SDK, seed patient_id and structured name with setSessionContext.
  • These flows apply only to Ambient interoperability for Headless Web SDK. Dictation and Form filling do not support interoperability.
  • Use @suki-sdk/platform and @suki-sdk/platform-react v0.3.0 or later.
  • Pass emrEncounterId on create so the note is interoperable. Refer to Ambient interoperability for Headless Web SDK.
After you create an interoperable ambient session, list shared notes for the EMR encounter, retrieve note content through Ambient APIs, and seed patient context when a clinician may review the note in the Web SDK. Follow this guide to learn how to share and manage ambient notes across Suki products using the Headless Web SDK.

How to read shared notes

The Headless Web SDK does not expose React hooks for note content, note context, note structured data, or encounter content. List note and session identifiers for the EMR encounter first, then retrieve content through Ambient API note-level endpoints.
  1. Call useGetEncounterInfo({ emrEncounterId }) to list note and session identifiers and artifact availability for the EMR encounter.
  2. Call Ambient API note-level endpoints with noteId to retrieve content, context, and structured data.

useGetEncounterInfo parameters

string
required
Partner EMR or application encounter identifier. The query is disabled when this value is empty.
boolean
Optional: Controls whether the query runs. Defaults to true. Combined with a non-empty emrEncounterId.

What useGetEncounterInfo returns

The hook returns the encounter info payload and loading and error state. Use those values to render shared notes in your UI.
GetEncounterInfoResponse | undefined
Encounter info payload when the request succeeds. notes is always an array in a successful response.
boolean
true while the encounter info request is in flight.
Error | null
Request failure details. Failures use reason getEncounterInfoFailed.

Code example for listing notes with useGetEncounterInfo

Use the following code example to list notes for an EMR encounter.
React
If the request fails, the error reason is getEncounterInfoFailed. Refer to Error handling.
After you have note_id values from useGetEncounterInfo or from create response noteId, call the Ambient API note-level endpoints from your backend to retrieve content, context, and structured data.

Seed patient context for Web SDK handoff

If you capture audio in Headless but the clinician reviews the note in the Web SDK, send patient identity and name with setSessionContext after start() and before submit(). Suki uses those fields to fill in the patient header in the Web SDK.

Patient fields for Web SDK handoff

Send patient_id and structured name with setSessionContext when a clinician may review the note in the Web SDK. Suki uses those fields to fill in the patient header.
(context: Omit<SessionContext, 'ambientSessionId'>) => Promise<void>
Sends patient, provider, and visit metadata for the active session. Call after start() and before submit().
string
Optional: Patient identifier in your EMR or application. Include this when the session may later open in the Web SDK.
object
Optional: Structured patient name. An empty name object is dropped and is not sent. Values are passed through as provided. The SDK does not force normalization.
string
required
Patient date of birth. Required when you send a patient object.
string
required
Patient sex. Required when you send a patient object.

Code example for seeding patient context

Use the following code example to seed patient context when a clinician may review the note in the Web SDK.
React
  • An empty name object is dropped and is not sent.
  • Patient name values are passed through as provided. The SDK does not force normalization.
  • You can also seed context through the Seed ambient session context API before opening the Web SDK.
For the full SessionContext shape, refer to SessionContext and Manage ambient session.

Available cookbooks

AmbientHeadless Web SDK

Create an Interoperable Headless Session

Pass emrEncounterId on Headless create.

5 min
AmbientWeb SDK

Seed Patient Context for the Web SDK

Seed patient context for Web SDK.

5 min

Next steps

Refer to Ambient interoperability to enable create with emrEncounterId and store noteId. Refer to Handle ambient session conflicts when create fails with sessionAlreadyExists or another Suki product ends the live session. Refer to Manage ambient session for setSessionContext and the full session context shape. Refer to SessionContext for patient identity and name field types. Refer to Web SDK interoperability when the shared note opens in the Web SDK.
Last modified on September 2, 2026