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

# Read Shared Ambient Notes

> List notes for an EMR encounter with useGetEncounterInfo, retrieve content through Ambient APIs, and seed patient context for Web SDK handoff

<div className="quick-summary-wrapper">
  <div className="quick-summary-header">
    <span className="quick-summary-icon" aria-hidden="true" />

    <span className="quick-summary-title">Quick summary</span>
  </div>

  <div className="quick-summary-content">
    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`.
  </div>

  <div className="quick-summary-footer">
    <span className="quick-summary-footer-icon" aria-hidden="true" />

    <span className="quick-summary-footer-text">Last updated:</span>
    <span className="quick-summary-footer-date">September 2026</span>
  </div>
</div>

<Warning>
  * 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](/headless-web-sdk/guides/ambient-interoperability).
</Warning>

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

<ResponseField name="emrEncounterId" type="string" required>
  Partner EMR or application encounter identifier. The query is disabled when this value is empty.
</ResponseField>

<ResponseField name="enabled" type="boolean">
  **Optional**: Controls whether the query runs. Defaults to `true`. Combined with a non-empty `emrEncounterId`.
</ResponseField>

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

<ResponseField name="data" type="GetEncounterInfoResponse | undefined">
  Encounter info payload when the request succeeds. `notes` is always an array in a successful response.

  <Expandable title="data.notes[]" defaultOpen={true}>
    <ResponseField name="note_id" type="string">
      Shared clinical note id. Use this value with Ambient note-level APIs.
    </ResponseField>

    <ResponseField name="status" type="string">
      Current status of the note.
    </ResponseField>

    <ResponseField name="created_at" type="string">
      Note creation timestamp.
    </ResponseField>

    <ResponseField name="updated_at" type="string">
      **Optional**: Note update timestamp when present.
    </ResponseField>

    <ResponseField name="sessions" type="array">
      Ambient sessions for the note. Each item includes `session_id`, `status`, and optional `artifacts` such as `"transcript"`, `"recording"`, or `"content"`.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="isLoading" type="boolean">
  `true` while the encounter info request is in flight.
</ResponseField>

<ResponseField name="error" type="Error | null">
  Request failure details. Failures use reason **`getEncounterInfoFailed`**.
</ResponseField>

| Method or API                                                                   | Pass             | Returns                                                                                           |
| ------------------------------------------------------------------------------- | ---------------- | ------------------------------------------------------------------------------------------------- |
| **`useGetEncounterInfo`**                                                       | `emrEncounterId` | Notes with `note_id`, status, timestamps, and sessions (`session_id`, status, optional artifacts) |
| [Get note content](/api-reference/ambient-content/note-content)                 | `noteId`         | Latest shared note content                                                                        |
| [Get note context](/api-reference/ambient-content/note-context)                 | `noteId`         | Aggregated note context                                                                           |
| [Get note structured data](/api-reference/ambient-content/note-structured-data) | `noteId`         | Diagnoses and orders for the note                                                                 |

### Code example for listing notes with useGetEncounterInfo

Use the following code example to list notes for an EMR encounter.

```tsx React expandable theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
import { useGetEncounterInfo } from "@suki-sdk/platform-react";

export function EncounterNotesList({
  emrEncounterId,
}: {
  emrEncounterId: string;
}) {
  const { data, isLoading, error } = useGetEncounterInfo({
    emrEncounterId,
  });

  if (isLoading) {
    return <p>Loading encounter notes...</p>;
  }

  if (error) {
    return <p role="alert">{error.message}</p>;
  }

  // data?.notes is always an array when the request succeeds
  return (
    <ul>
      {(data?.notes ?? []).map((note) => (
        <li key={note.note_id}>{note.note_id}</li>
      ))}
    </ul>
  );
}

// Example call site:
// <EncounterNotesList emrEncounterId="6ec3920f-b0b1-499d-a4e9-889bf788e5ab" />
```

<Note>
  If the request fails, the error reason is **`getEncounterInfoFailed`**. Refer to [Error handling](/headless-web-sdk/guides/error-handling#interoperability-errors).
</Note>

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

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

<ResponseField name="setSessionContext" type="(context: Omit<SessionContext, 'ambientSessionId'>) => Promise<void>">
  Sends patient, provider, and visit metadata for the active session. Call after **`start()`** and before **`submit()`**.
</ResponseField>

<ResponseField name="patient.patient_id" type="string">
  **Optional**: Patient identifier in your EMR or application. Include this when the session may later open in the Web SDK.
</ResponseField>

<ResponseField name="patient.name" type="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.

  <Expandable title="properties" defaultOpen={true}>
    <ResponseField name="family" type="string">
      **Optional**: Family name.
    </ResponseField>

    <ResponseField name="given" type="string[]">
      **Optional**: Given names.
    </ResponseField>

    <ResponseField name="suffix" type="string[]">
      **Optional**: Name suffixes.
    </ResponseField>

    <ResponseField name="use" type="string">
      **Optional**: Name use, for example `"official"`.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="patient.dob" type="string" required>
  Patient date of birth. Required when you send a `patient` object.
</ResponseField>

<ResponseField name="patient.sex" type="string" required>
  Patient sex. Required when you send a `patient` object.
</ResponseField>

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

```tsx React expandable theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
import { useAmbientSession } from "@suki-sdk/platform-react";

export function SeedPatientContext({
  ambientSessionId,
}: {
  ambientSessionId: string;
}) {
  const { start, setSessionContext } = useAmbientSession({
    ambientSessionId,
  });

  const seedContext = async () => {
    await start();

    // Call after start() and before submit(). Session status must still be "created".
    await setSessionContext({
      patient: {
        patient_id: "905c2521-25eb-4324-9978-724636df3436",
        name: {
          use: "official",
          family: "Doe",
          given: ["John"],
        },
        dob: "1990-01-01",
        sex: "male",
      },
    });
  };

  return (
    <button type="button" onClick={() => void seedContext()}>
      Start and seed patient context
    </button>
  );
}
```

<Note>
  * 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](/api-reference/ambient-sessions/context) before opening the Web SDK.
</Note>

For the full `SessionContext` shape, refer to [SessionContext](/headless-web-sdk/api-reference/types/session-context) and [Manage ambient session](/headless-web-sdk/guides/hooks/ambient-session-hook#session-context).

## Available cookbooks

<div className="hp-io-method-grid tut-hub-card-grid" data-cookbook-related-grid>
  <a className="hp-io-method-card tut-hub-method-card" href="/documentation/cookbooks/create-interoperable-headless-session">
    <div className="tut-hub-card-media" aria-hidden="true" />

    <div className="hp-io-method-card-body">
      <div className="tut-hub-card-badges">
        <span className="hp-wn-badge hp-wn-badge-new">Ambient</span>
        <span className="hp-wn-badge cookbook-hub-badge-surface cookbook-hub-badge-surface--sdk">Headless Web SDK</span>
      </div>

      <h3 className="hp-io-method-card-title">Create an Interoperable Headless Session</h3>

      <p className="hp-io-method-card-desc cookbook-hub-card-desc">
        Pass emrEncounterId on Headless create.
      </p>

      <div className="hp-io-method-card-meta tut-hub-card-foot" aria-label="5 min">
        <div className="tut-hub-card-foot-meta">
          <span className="hp-io-method-card-meta-time">5 min</span>
        </div>
      </div>
    </div>
  </a>

  <a className="hp-io-method-card tut-hub-method-card" href="/documentation/cookbooks/seed-patient-context-for-web-sdk">
    <div className="tut-hub-card-media tut-hub-card-media--blue" aria-hidden="true" />

    <div className="hp-io-method-card-body">
      <div className="tut-hub-card-badges">
        <span className="hp-wn-badge hp-wn-badge-new">Ambient</span>
        <span className="hp-wn-badge cookbook-hub-badge-surface cookbook-hub-badge-surface--sdk">Web SDK</span>
      </div>

      <h3 className="hp-io-method-card-title">Seed Patient Context for the Web SDK</h3>

      <p className="hp-io-method-card-desc cookbook-hub-card-desc">
        Seed patient context for Web SDK.
      </p>

      <div className="hp-io-method-card-meta tut-hub-card-foot" aria-label="5 min">
        <div className="tut-hub-card-foot-meta">
          <span className="hp-io-method-card-meta-time">5 min</span>
        </div>
      </div>
    </div>
  </a>
</div>

## Next steps

<Icon icon="file-lines" iconType="solid" /> Refer to [Ambient interoperability](/headless-web-sdk/guides/ambient-interoperability) to enable create with `emrEncounterId` and store `noteId`.

<Icon icon="file-lines" iconType="solid" /> Refer to [Handle ambient session conflicts](/headless-web-sdk/guides/handle-ambient-session-conflicts) when create fails with `sessionAlreadyExists` or another Suki product ends the live session.

<Icon icon="file-lines" iconType="solid" /> Refer to [Manage ambient session](/headless-web-sdk/guides/hooks/ambient-session-hook) for `setSessionContext` and the full session context shape.

<Icon icon="file-lines" iconType="solid" /> Refer to [SessionContext](/headless-web-sdk/api-reference/types/session-context) for patient identity and name field types.

<Icon icon="file-lines" iconType="solid" /> Refer to [Web SDK interoperability](/web-sdk/guides/ambient-interoperability) when the shared note opens in the Web SDK.