Skip to main content
Embedded Forms let you capture specific answers from an ambient visit as separate fields your app can use directly. After a visit, Suki still returns the usual note text for each section, but with Embedded Forms, you also get filled values for the custom fields you asked or defined, such as onset and severity on History of Present Illness, so you do not need to parse the note to find them. You define the custom fields up front, Suki fills them from the conversation, and you read the answers when the note is ready from section_structured_values. You can also send text that is already in the chart for the same section, such as prior history, in the same request. Create the ambient session with useAmbient or createNewAmbientSession, attach the fields with setSessionContext, record with useAmbientSession, then read the filled values.
Embedded Forms require 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.

​
How Embedded Forms work

Embedded Forms work in three steps: seed what you want filled, record the visit, then read the results when the note is ready.
1

Seed the Session Context

After you create the ambient session, and before you submit it, call setSessionContext with sections. Each section has a LOINC code and a precharted_content list that holds prior text, Embedded Form templates, or both.
2

Record the Visit

Start, pause, and submit recording with useAmbientSession the same way you do today. To change templates during the visit, call updateSessionContext.
3

Read the Filled Values

After note generation completes, call the section structured data helper or its React hook. Filled values come back in section_structured_values.
It is your responsibility to send Embedded Form templates on the session context. Suki fills those fields from the visit and you read the filled values from structured data helpers. Note content helpers return note text only. The optional cumulative flag applies to session content helpers only, not to Embedded Form reads.

​
Common use cases

Fill Fields from a Visit

Seed Embedded Form templates, record the visit, then read the filled values when the note is ready.

Include Prior Section Text

Send text already in the chart with the templates for that section.

Change Templates Mid-Visit

Update the section list if the fields need to change before submit.

Read Fills with Diagnoses and Orders

Pull Embedded Forms together with diagnoses and orders when your UI needs both.

Keep Offline Uploads Complete

Seed the full context first so later updates stay available if the session goes offline.

​
Prior text and Embedded Form templates

When you seed a note section, you send a LOINC code so Suki knows which section it is. On that section you can also send a precharted_content list. Each item in the list is either prior text for the section, or an Embedded Form template. Set type to "string" or "structured" so Suki knows which one you mean. You can send both on the same section, and you can send more than one template when you need more than one set of fields.

​
Plain text (type: "string")

Use this when you already have text for the note section and you want Suki to receive that text as part of the session context. Common cases are prior section history, text already in the chart, or other plain text your app owns for that LOINC.
Send only type: "string" and text. Do not add template_id or fields on a string entry.

​
Embedded Form template (type: "structured")

Use this when you want Suki to fill specific custom fields for that section from the ambient visit, such as onset, severity, or blood pressure. This is the Embedded Forms path. Each template needs a template_id you choose so you can match the filled results later, a fields list for Suki to fill, and an optional language such as "en". Every field needs a key and a type, and you can add optional id, context, and options to describe the field more clearly. options are only for the seed request, for example choices on a radio field, and they do not come back on the filled-value read path.

​
Which one to send

  • Send string when you have existing section text and you are not asking Suki to fill discrete fields.
  • Send structured when you want filled Embedded Forms back in section_structured_values.
  • Send both on the same section when you have prior text and Embedded Form fields for that LOINC. Keep them as separate entries in precharted_content. Do not mix text and fields in one entry.
If you only need Embedded Forms, you can omit string entries. If you only need to seed prior text, you can omit structured entries.
For field shapes, code samples, mid-visit updates, and how to read results, refer to Seed and read Embedded Forms.

​
Next steps

Seed and read Embedded Forms - Seed, update, read filled values, offline behavior, and examples. SessionContext - Full session context shape, including precharted_content. Platform client and provider - setSessionContext, updateSessionContext, and structured data methods. Manage ambient session - Start, pause, and submit recording.
Last modified on October 16, 2026