Seed & Read Embedded Forms

This guide shows how to seed, update, and read Embedded Forms with the Headless Web SDK. For what Embedded Forms are and when to use string versus structured, refer to Embedded Forms overview.

To use Embedded Forms, you need Headless Web SDK v0.3.1 or later (@suki-sdk/platform and @suki-sdk/platform-react). Make sure your environment has this feature enabled before you use it.

Seed Embedded Forms

Call setSessionContext any time after you create the session and before you submit it. You can call it before you start recording. It sends the full context with POST, checks that the session is still created, and stores that context in IndexedDB for a later offline upload. Use updateSessionContext only after that first seed, when a template changes during the visit. It sends a PATCH for the fields in updateMask. It does not recover the ambient session, and it does not check that the session is still created. Seed with setSessionContext first so an offline upload still has the templates.

For when to use type: "string" versus type: "structured", refer to Prior text and Embedded Form templates.

Sections and precharted_content shape

Section[]

Sections to seed on the ambient session context.

Hide Section properties

string

required

LOINC code of the note section, for example 10164-2.

PrechartedContent[]

Optional: Prior text and Embedded Form templates for this section. The same LOINC code can have more than one entry, for example one string entry and one or more structured entries.

object

Prior text for the section.

Hide properties

"string"

required

Marks this entry as prior text.

string

required

The prior text, for example "Patient reports intermittent chest pain for 2 weeks."

object

An Embedded Form template.

Hide properties

"structured"

required

Marks this entry as an Embedded Form template.

string

required

Your identifier for the template. The same value comes back on the filled values.

string

Optional: Template language, for example "en".

array

required

Fields for Suki to fill.

Show field properties

string

Optional: Your identifier for the field.

string

required

Field key. The same value comes back on the filled value.

string

Optional: What the field asks for, for example "When did symptoms start?" You can include other field id values as {id} placeholders, for example "Patient has had {slot-symptoms} for {slot-duration}".

"text" | "radio" | "multi_select" | "date"

required

Field type.

string[]

Optional: Choices for the field, for example ["mild", "moderate", "severe"].

Each entry is either string or structured. Do not mix fields from both types in one entry.

The following types show the shape of sections you pass to setSessionContext and updateSessionContext:

TypeScript

// Prior text OR an Embedded Form template for one section entry
type PrechartedContent =
  | { type: "string"; text: string } // Prior / existing section text
  | {
      type: "structured"; // Embedded Form template
      template_id: string; // Your id; comes back on filled results
      language?: string;
      fields: Array<{
        id?: string;
        key: string; // Comes back on each filled value
        context?: string; // What the field asks for; may include {id} placeholders
        type: "text" | "radio" | "multi_select" | "date";
        options?: string[]; // Seed-only choices for radio / multi_select
      }>;
    };

type Section = {
  loinc: string; // Note section LOINC, for example Physical exam
  precharted_content?: PrechartedContent[];
};

React

// Seed Embedded Forms after create and before submit
// From useAmbientSession: ambient.setSessionContext({ sections }) also works
await client.setSessionContext({
  ambientSessionId,
  sections: [
    {
      loinc: "29545-1", // Physical exam
      precharted_content: [
        {
          type: "structured",
          template_id: "partner-exam-iv-1", // Match this id on the filled results
          fields: [
            { key: "blood_pressure", type: "text", context: "Systolic/diastolic" },
            {
              key: "pain_scale",
              type: "radio",
              options: ["0", "1-3", "4-6", "7-10"], // Sent on seed only
            },
          ],
        },
      ],
    },
  ],
});

Update Embedded Forms during a visit

Call updateSessionContext to change sections or templates after the first seed. Prefer the useUpdateAmbientSessionContext hook, which wraps the same call.

updateMask is required. Prefer ["sections"]. The string "sections" is also valid.
precharted_content lives on sections[]. Mask the top-level sections field, then send the full sections list you want. The PATCH replaces that list. It does not append.
Do not use nested paths under sections, such as ["sections.precharted_content"] or ["sections.loinc"]. Those are not supported for Embedded Form updates. Nested paths on object fields, such as patient.dob, are supported when you are updating that field.
Add other top-level paths only when you are also patching those fields, for example ["sections", "orders"].

React

// Mid-visit update: updateMask is required, and sections replaces the full list
await client.updateSessionContext({
  ambientSessionId,
  updateMask: ["sections"],
  sections: [
    {
      loinc: "10164-2", // History of Present Illness
      precharted_content: [
        {
          type: "structured",
          template_id: "partner-hpi-iv-1",
          fields: [{ key: "onset", type: "text", context: "When did symptoms start?" }],
        },
      ],
    },
  ],
});

Errors

Call	Error	When
`client.setSessionContext`	`AmbientSessionError` with `code: "ContextUpdateFailed"`	The session is no longer in the `created` state (for example, after submit or cancel), or the request fails
`updateSessionContext`	`PlatformError` with `reason: "updateSessionContextFailed"`	`ambientSessionId` or `updateMask` is missing, or the request fails
Structured data helpers	`PlatformError` with `reason: "getStructuredDataFailed"`	The ID is empty or the request fails
Section structured data helpers	`PlatformError` with `reason: "getSectionStructuredDataFailed"`	The ID is empty or the request fails
Content helpers	`PlatformError` with `reason: "getContentFailed"`	The ID is empty or the request fails

client.setSessionContext throws AmbientSessionError. setSessionContext from useAmbientSession throws that failure as a string, so do not check it with instanceof AmbientSessionError. updateSessionContext and useUpdateAmbientSessionContext throw PlatformError. The read hooks return the PlatformError object.

Read filled values

Filled values come back in section_structured_values. Use the section helpers when you only need Embedded Forms. Use the full structured data helpers when you also need diagnoses and orders.

Method	Returns
`getAmbientSessionSectionStructuredData(ambientSessionId)`	`{ section_structured_values }` for the session
`getAmbientSessionStructuredData(ambientSessionId)`	`{ structured_data: { diagnoses, orders, section_structured_values } }` for the session
`getAmbientEncounterSectionStructuredData(encounterId)`	`{ section_structured_values }` for the encounter
`getAmbientEncounterStructuredData(encounterId)`	`{ structured_data: { diagnoses, orders, section_structured_values } }` for the encounter
`getAmbientNoteStructuredData(noteId)`	Diagnoses and orders for the note. Does not include Embedded Forms
`getAmbientSessionContent({ ambientSessionId, cumulative? })`	Note text for the session. `cumulative` is optional and applies here only
`getAmbientEncounterContent(encounterId)`	Note text for the encounter
`getAmbientNoteContent(noteId)`	Note text for the note

Note structured data does not include Embedded Forms in this release. Read Embedded Forms from the session or encounter helpers.

The SDK does not poll for filled values in the background. Call the helpers, or refetch the hooks, when your app knows the note is ready. To poll with a hook, pass refetchIntervalMs.

Each filled value is { id?, context?, key, value }. It does not include the options or field type you sent in the template.

TypeScript

// Protobuf JSON value: null, boolean, number, string, array, or object
type JsonValue = null | boolean | number | string | JsonValue[] | { [key: string]: JsonValue };

// One filled section from section_structured_values
type SectionStructuredData = {
  loinc_code?: string; // Same LOINC you seeded
  forms?: Array<{
    template_id?: string; // Same template_id you seeded
    values?: Array<{
      id?: string;
      context?: string; // Same context you seeded, when returned
      key: string; // Same key you seeded
      value?: JsonValue;
    }>;
  }>;
};

// Session / encounter structured data:
// structured_data.section_structured_values?: SectionStructuredData[]

// Section structured data helpers (Embedded Forms only):
// { section_structured_values?: SectionStructuredData[] }

React hooks

@suki-sdk/platform-react includes these hooks for Embedded Forms and related content:

Hook	What it does
`useUpdateAmbientSessionContext`	Updates the session context. Wraps `updateSessionContext`
`useAmbientSessionSectionStructuredData`	Reads Embedded Forms for the session
`useAmbientSessionStructuredData`	Reads structured data for the session
`useAmbientSessionContent`	Reads note content for the session
`useAmbientEncounterSectionStructuredData`	Reads Embedded Forms for the encounter
`useAmbientEncounterStructuredData`	Reads structured data for the encounter
`useAmbientEncounterContent`	Reads note content for the encounter
`useAmbientNoteStructuredData`	Reads diagnoses and orders for the note. Does not include Embedded Forms
`useAmbientNoteContent`	Reads note content for the note

Each read hook takes one object:

string

required

The ID the hook reads by. Session hooks take ambientSessionId, encounter hooks take encounterId, and note hooks take noteId. The query does not run while this value is empty.

boolean

Optional: Controls whether the query runs. Defaults to true.

number

Optional: Polling interval in milliseconds. When you omit it, the hook does not poll.

Each read hook also has a query options factory, such as ambientSessionStructuredDataQueryOptions, that you can use to prefetch with your QueryClient. After a successful useUpdateAmbientSessionContext call, the SDK refreshes the session structured data, section structured data, and session content hooks for that session.

Code examples

This component seeds Embedded Forms with setSessionContext from useAmbientSession, records the visit, updates the templates, and reads the filled values.

React

import { useCallback } from "react";
import {
  useAmbient,
  useAmbientSession,
  useAmbientSessionSectionStructuredData,
  useUpdateAmbientSessionContext,
} from "@suki-sdk/platform-react";

// One HPI section with prior text + Embedded Form fields
const HPI_SECTIONS = [
  {
    loinc: "10164-2", // History of Present Illness
    precharted_content: [
      {
        type: "string" as const, // Prior text already in the chart
        text: "Patient reports intermittent chest pain for 2 weeks.",
      },
      {
        type: "structured" as const, // Embedded Form template
        template_id: "partner-hpi-iv-1", // Match this on filled results
        language: "en",
        fields: [
          {
            id: "onset",
            key: "onset",
            context: "When did symptoms start?",
            type: "text" as const,
          },
          {
            id: "severity",
            key: "severity",
            context: "Pain severity",
            type: "radio" as const,
            options: ["mild", "moderate", "severe"], // Seed-only choices
          },
        ],
      },
    ],
  },
];

function EmbeddedFormsVisit() {
  const { ambientSessionId, session } = useAmbient();
  const ambient = useAmbientSession({ ambientSessionId: ambientSessionId ?? "" });
  const { mutateAsync: updateContext } = useUpdateAmbientSessionContext();

  // Embedded Forms only; does not poll unless you pass refetchIntervalMs
  const ivQuery = useAmbientSessionSectionStructuredData({
    ambientSessionId: ambientSessionId ?? "",
    enabled: Boolean(ambientSessionId),
  });

  const createSession = useCallback(async () => {
    // ambientSessionId updates from useAmbient after create succeeds
    await session.create({ encounterId: "visit-123" });
  }, [session]);

  const seedEmbeddedForms = useCallback(async () => {
    if (!ambientSessionId) return;

    // Full seed after create, before submit (can be before start)
    // useAmbientSession adds ambientSessionId for you
    await ambient.setSessionContext({ sections: HPI_SECTIONS });
  }, [ambientSessionId, ambient]);

  const updateEmbeddedForms = useCallback(async () => {
    if (!ambientSessionId) return;

    // Mid-visit change: updateMask required; sections replaces the previous list
    await updateContext({
      ambientSessionId,
      updateMask: ["sections"],
      sections: HPI_SECTIONS,
    });
  }, [ambientSessionId, updateContext]);

  return (
    <div>
      <button type="button" onClick={createSession}>
        Create session
      </button>
      <button type="button" onClick={seedEmbeddedForms} disabled={!ambientSessionId}>
        Seed Embedded Forms
      </button>
      <button type="button" onClick={() => ambient.start()} disabled={!ambientSessionId}>
        Start recording
      </button>
      <button type="button" onClick={updateEmbeddedForms} disabled={!ambientSessionId}>
        Update Embedded Forms
      </button>
      <button type="button" onClick={() => ambient.submit()} disabled={!ambientSessionId}>
        Submit
      </button>
      {/* Call again after the note is ready */}
      <button type="button" onClick={() => void ivQuery.refetch()} disabled={!ambientSessionId}>
        Refresh Embedded Forms
      </button>

      <pre>{JSON.stringify(ivQuery.data?.section_structured_values ?? null, null, 2)}</pre>
    </div>
  );
}

The following component reads the filled values and the diagnoses after submit. The hooks do not poll by default. Pass refetchIntervalMs only if your app needs polling.

React

import {
  useAmbientSessionStructuredData,
  useAmbientSessionSectionStructuredData,
} from "@suki-sdk/platform-react";

function Results({ ambientSessionId }: { ambientSessionId: string }) {
  // Diagnoses, orders, and Embedded Forms together
  const structured = useAmbientSessionStructuredData({
    ambientSessionId,
    // Turn on when your app knows the note is ready to read
    enabled: Boolean(ambientSessionId),
  });

  // Embedded Forms only
  const embeddedForms = useAmbientSessionSectionStructuredData({
    ambientSessionId,
    enabled: Boolean(ambientSessionId),
  });

  const fills = embeddedForms.data?.section_structured_values ?? [];
  const withDxOrders = structured.data?.structured_data;

  return (
    <div>
      <h3>Embedded Forms</h3>
      {fills.map((section) => (
        <div key={section.loinc_code}>
          <strong>{section.loinc_code}</strong>
          {section.forms?.map((form) => (
            <ul key={form.template_id}>
              {form.values?.map((v) => (
                <li key={v.key}>
                  {v.context ?? v.key}: {String(v.value ?? "")}
                </li>
              ))}
            </ul>
          ))}
        </div>
      ))}

      <h3>Diagnoses</h3>
      <pre>{JSON.stringify(withDxOrders?.diagnoses, null, 2)}</pre>
    </div>
  );
}

Offline behavior

Seed Embedded Forms with setSessionContext. It stores the full context in your browser’s IndexedDB, so the SDK can upload it if the session goes offline.
After a successful updateSessionContext, the SDK merges only the fields in updateMask into IndexedDB. A later offline upload keeps those updates.
If there is no IndexedDB context row yet, the SDK does not mirror the update locally and logs a warning. The update still reaches Suki, but a later offline upload does not include it. Call setSessionContext first.

For how the SDK handles offline sessions, refer to Offline mode.

Troubleshooting

setSessionContext Throws ContextUpdateFailed

The session must still be in the created state. If you already called submit or cancel, client.setSessionContext throws AmbientSessionError with code: "ContextUpdateFailed". Seed Embedded Forms after create and before submit. setSessionContext from useAmbientSession throws that failure as a string.

updateSessionContext Fails with updateSessionContextFailed

Pass both ambientSessionId and updateMask. Prefer updateMask: ["sections"], then send the full sections list you want. Nested paths under sections, such as sections.precharted_content, are not supported. Prefer useUpdateAmbientSessionContext. This call throws PlatformError, not AmbientSessionError.

section_structured_values Is Empty

Wait until your app knows the note is ready, then call the helper or refetch the hook. The SDK does not poll in the background unless you pass refetchIntervalMs. Use the session or encounter structured data helpers. getAmbientNoteStructuredData does not include Embedded Forms in this release. Note content helpers return note text only, not Embedded Forms.

Offline Upload Is Missing Embedded Forms

Call setSessionContext first so the SDK stores the full context in your browser’s IndexedDB. If you call updateSessionContext with no prior IndexedDB context row, the update can still reach Suki, but a later offline upload does not include it. Refer to Offline behavior.

cumulative Does Not Affect Embedded Forms

The optional cumulative flag applies only to session content helpers such as getAmbientSessionContent. It does not apply to section structured data reads.

Next steps

Embedded Forms overview - What Embedded Forms are, the ambient flow, and string versus structured. Platform client and provider - setSessionContext, updateSessionContext, and structured data methods. SessionContext - Full session context shape, including precharted_content. Offline mode - Track sessions that upload after the network returns. Manage ambient session - Start, pause, and submit recording.

Get Started

Concepts & Feature Guides

API Reference

Resources

Seed & Read Embedded Forms

Seed Embedded Forms

Sections and precharted_content shape

Update Embedded Forms during a visit

Errors

Read filled values

React hooks

Code examples

Offline behavior

Troubleshooting

Next steps

​Seed Embedded Forms

​Sections and precharted_content shape

​Update Embedded Forms during a visit

​Errors

​Read filled values

​React hooks

​Code examples

​Offline behavior

​Troubleshooting

​Next steps

Seed Embedded Forms

Sections and precharted_content shape

Update Embedded Forms during a visit

Errors

Read filled values

React hooks

Code examples

Offline behavior

Troubleshooting

Next steps