> ## 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.
# Embedded Forms Overview
> What Embedded Forms are in the Headless Web SDK, how the ambient flow works, and when to use string vs structured precharted content
export const QuickSummary = ({title = "Quick summary", updated, children}) =>
{title}
{children}
{updated ?
Last updated:
{updated}
: null}
;
Embedded Forms let you send field templates on an ambient session, then read the filled values after the note is ready. Seed them with `setSessionContext`and change templates during the visit with `updateSessionContext`. Read the filled values with structured data helpers or React hooks. Your app decides when to read or refresh as the SDK does not poll for them.
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.
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.
Start, pause, and submit recording with `useAmbientSession` the same way you do today. To change templates during the visit, call `updateSessionContext`.
After note generation completes, call the section structured data helper or its React hook. Filled values come back in `section_structured_values`.
```mermaid actions={false} theme={"theme":{"light":"one-light","dark":"material-theme-darker"}}
flowchart TD
A[1. Create ambient session] --> B[2. setSessionContext with sections]
B --> C[3. Record the visit]
C --> D{Change Embedded Form templates?}
D -->|Yes| E[updateSessionContext with updateMask sections]
E --> C
D -->|No| F[4. Submit the session]
F --> G[5. Wait until the note is ready]
G --> H[6. Read section_structured_values]
style A fill:#FFF394,stroke:#D4A017,color:#000000
style B fill:#FFF394,stroke:#D4A017,color:#000000
style C fill:#FFF394,stroke:#D4A017,color:#000000
style F fill:#FFF394,stroke:#D4A017,color:#000000
style G fill:#FFF394,stroke:#D4A017,color:#000000
style H fill:#FFF394,stroke:#D4A017,color:#000000
style E fill:#e3e0e0,stroke:#8b8a8a,color:#000000
```
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.
```mermaid actions={false} theme={"theme":{"light":"one-light","dark":"material-theme-darker"}}
flowchart LR
A[You send template fields] --> B[Suki fills from the visit]
B --> C[You read section_structured_values]
style A fill:#FFF394,stroke:#D4A017,color:#000000
style B fill:#FFF394,stroke:#D4A017,color:#000000
style C fill:#FFF394,stroke:#D4A017,color:#000000
```
### Common use cases
Seed Embedded Form templates, record the visit, then read the filled values when the note is ready.
Send text already in the chart with the templates for that section.
Update the section list if the fields need to change before submit.
Pull Embedded Forms together with diagnoses and orders when your UI needs both.
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.
| `type` | What you send | When to use it | What you get back |
| - | - | - | - |
| `"string"` | A plain text block in `text` | You already have section text to seed, such as prior note history or text already in the chart | This is input context for the section. It is not returned as Embedded Form fills |
| `"structured"` | A template with `template_id` and `fields` | You want Suki to fill specific fields for that section from the ambient visit | Filled key/value pairs in `section_structured_values`, matched by `template_id` and field `key` |
```mermaid actions={false} theme={"theme":{"light":"one-light","dark":"material-theme-darker"}}
flowchart TD
A[Section with a LOINC code] --> B[precharted_content list]
B --> C["type: string"]
B --> D["type: structured"]
C --> E[Plain text for that section]
D --> F[Embedded Form template]
F --> G[Suki fills fields from the visit]
G --> H[Read section_structured_values]
style A fill:#FFF394,stroke:#D4A017,color:#000000
style B fill:#FFF394,stroke:#D4A017,color:#000000
style C fill:#e3e0e0,stroke:#8b8a8a,color:#000000
style E fill:#e3e0e0,stroke:#8b8a8a,color:#000000
style D fill:#FFF394,stroke:#D4A017,color:#000000
style F fill:#FFF394,stroke:#D4A017,color:#000000
style G fill:#FFF394,stroke:#D4A017,color:#000000
style H fill:#FFF394,stroke:#D4A017,color:#000000
```
### 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](/headless-web-sdk/guides/seed-and-read-embedded-forms).
## Next steps
**[Seed and read Embedded Forms](/headless-web-sdk/guides/seed-and-read-embedded-forms)** - Seed, update, read filled values, offline behavior, and examples.
**[SessionContext](/headless-web-sdk/api-reference/types/session-context)** - Full session context shape, including `precharted_content`.
**[Platform client and provider](/headless-web-sdk/api-reference/platform-client)** - `setSessionContext`, `updateSessionContext`, and structured data methods.
**[Manage ambient session](/headless-web-sdk/guides/hooks/ambient-session-hook)** - Start, pause, and submit recording.
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.