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

> Get answers for the blanks in your note templates from the patient visit, returned with the ambient note

export const QuickSummary = ({title = "Quick summary", updated, children}) => <div className="quick-summary-wrapper">
    <div className="quick-summary-header">
      <span className="quick-summary-icon" aria-hidden="true" />
      <span className="quick-summary-title">{title}</span>
    </div>
    <div className="quick-summary-content">{children}</div>
    {updated ? <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">{updated}</span>
      </div> : null}
  </div>;

<QuickSummary updated="October 2026">
  Embedded Forms let Suki fill in the blanks in your note templates, such as which symptoms the patient has or how long they have had them, from the patient visit. You send the blanks on session context before you end the ambient session, and after the note is ready Suki returns an answer for each one, so your app can fill in the template without anyone copying answers out of the note text.
</QuickSummary>

| Term | Meaning |
| :- | :- |
| Embedded Forms | Custom fields on a note section that Suki fills from the ambient visit and returns as key/value pairs. |
| `precharted_content` | List on `sections[]` in session context. Each entry is `type: "string"` (prior section text) or `type: "structured"` (an Embedded Form template). |
| Section structured data | The read endpoints and the `section_structured_values` field that return filled Embedded Form values. |

<Info>
  **Embedded Forms are supported by:** Ambient APIs and Headless Web SDK

  * **Ambient APIs:** You send templates on [Seed ambient session context](/api-reference/ambient-sessions/context), run the ambient session as usual, and read the filled values from the section structured data endpoints. This page and [Seed and read Embedded Forms](/documentation/how-to/ambient-clinical-notes/seed-and-read-embedded-forms) cover the API flow.
  * **Headless Web SDK:** You send the same templates with `setSessionContext` and read them with the structured data hooks. Refer to [Embedded Forms in the Headless Web SDK](/headless-web-sdk/guides/embedded-forms-overview).
</Info>

Embedded Forms let you define custom fields within a note section that Suki fills from the ambient conversation alongside the note text.

For example, a History of Present Illness (HPI) template can include fields for symptom onset, duration, and severity. Choice fields can have a predefined list of accepted values. A severity field, for example, might accept `Mild`, `Moderate`, or `Severe`.

You send these field definitions to Suki as part of the ambient session context. Suki uses the conversation to generate the note section and fill in the corresponding values. When the note is ready, your app can read these values from `section_structured_values` and use them to populate the matching fields in the clinical template.

When you use Embedded Forms, clinicians get the following benefits:

* **Reduce manual entry:** Clinicians don't have to re-enter information they've already discussed with the patient.
* **Work with structured data:** Your app can use the returned values directly instead of extracting them from the generated note text.
* **Keep existing templates:** Clinicians can continue using the custom fields in their clinical note templates.

## Common use cases

<CardGroup cols={2}>
  <Card title="Fill Template Fields from a Visit" icon="clipboard" href="/documentation/how-to/ambient-clinical-notes/seed-and-read-embedded-forms#seed-embedded-forms-on-session-context" arrow="true">
    Get an answer for each blank in a note template, such as symptoms or duration, after the visit.
  </Card>

  <Card title="Include Prior Section Text" icon="file-lines" href="/documentation/how-to/ambient-clinical-notes/seed-and-read-embedded-forms#seed-embedded-forms-on-session-context" arrow="true">
    Send history that is already in the chart so Suki considers it when it writes the section.
  </Card>

  <Card title="Read Fields with Diagnoses and Orders" icon="notes-medical" href="/documentation/how-to/ambient-clinical-notes/seed-and-read-embedded-forms#read-the-filled-values" arrow="true">
    Get the template answers in the same call as diagnoses and orders.
  </Card>

  <Card title="Record the Visit Again" icon="arrows-rotate" href="/documentation/how-to/ambient-clinical-notes/seed-and-read-embedded-forms#change-templates-after-a-recording" arrow="true">
    Record the visit again with updated templates and read the new answers.
  </Card>
</CardGroup>

## How Embedded Forms work

<Steps>
  <Step title="Send the Form">
    After you create the session, put the templates in `precharted_content` on each section. Finish seed or update context before you end the session. You can send templates after streaming has started, including just before you end.
  </Step>

  <Step title="Suki Listens and Drafts">
    Stream audio and end the session the same way you do today. Suki writes the note narrative for that section and finds the answers for each field from the same conversation.
  </Step>

  <Step title="Get Clean Values Back">
    Once the note is ready, Suki returns each answer as its own value, for example `severity` as `"moderate"`. Read `section_structured_values` from the session or encounter section structured data after the session status is `completed`, or when your SUCCESS webhook arrives.
  </Step>

  <Step title="Auto-Fill Your Form">
    Your app places those values into the matching fields in the EHR. When a question was not mentioned during the visit, that field comes back as `null` or is left out, and you treat it as empty for the clinician to complete.
  </Step>
</Steps>

```mermaid actions={false} theme={"theme":{"light":"one-light","dark":"material-theme-darker"}}
flowchart LR
    A[1. Create ambient session] --> B[2. Seed context with templates]
    B --> C[3. Stream audio]
    C --> D[4. End session]
    D --> E[5. Suki writes the note and fills the fields]
    E --> F[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 D fill:#FFF394,stroke:#D4A017,color:#000000
    style E fill:#FFF394,stroke:#D4A017,color:#000000
    style F fill:#FFF394,stroke:#D4A017,color:#000000
```

<Warning>
  Send your templates after you create the session and finish seed or update context **before you end the session**. You can seed or update after streaming has started, including just before you end. Suki fills the values after note generation finishes, not while the audio is streaming. To use different templates after a recording, start a new ambient session on the same encounter.
</Warning>

<Note>
  If Suki cannot fill your fields for a session, the note, diagnoses, and orders still generate as usual.
</Note>

## Prior text and Embedded Form templates

Each item in `precharted_content` is either prior text for the section or an Embedded Form template, and you 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 on a section when your note needs more than one set of fields.

| `type` | What you send | When to use it | What you get back |
| :- | :- | :- | :- |
| `"string"` | A block of text in `text` | You already have text for the section, such as prior history or text already in the chart | Nothing separate. Suki considers the text with the visit conversation when it writes that section |
| `"structured"` | A template with `template_id` and `fields` | You want Suki to fill specific fields for that section from the visit | Filled values 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 (LOINC)"] --> B[precharted_content]
    B --> C["type: string"]
    B --> D["type: structured"]
    C --> E[Prior text Suki considers for the section]
    D --> F[Template with fields]
    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
```

### Which value types to send

* Send **`string`** when you have existing section text and you are not asking Suki to fill separate fields.
* Send **`structured`** when you want filled values back for your own fields.
* Send **both** as separate entries on the same section when you have prior text and fields for that LOINC.

<Warning>
  Do not put `text` and `fields` in one entry. Each entry is either `string` or `structured`.
</Warning>

## What a structured field template looks like

A template has a `template_id` that you choose and keep stable, so you can match the filled results back to your form, and a `fields` list. Every field needs a `key` and a `type`. You can also send an `id` that Suki returns unchanged, a `context` that tells Suki what the field asks for and can include other field `id` values as `{id}` placeholders, and `options` for fields where the clinician picks from a list.

| Field type | What Suki fills | Send `options` |
| :- | :- | :- |
| `text` | A free-text answer | No |
| `radio` | One choice from your options | Yes |
| `multi_select` | One or more choices from your options | Yes |
| `date` | A date for the field | No |

<Note>
  * The table lists the field types Suki supports today. Suki may support more types in the future. Before sending your template, check the [Structured data field types](/api-reference/info/structured-data-field-types) API for the latest list. Do not hard-code the list in your integration.

  * If a field is invalid or unsupported, Suki **skips it** and keeps the other fields but the request still succeeds. Suki skips a field if it is missing a `key` or `type`, uses an unsupported `type`, or has no `options` for a `radio` or `multi_select` field. Suki drops the entire template only if it is missing a `template_id` or all its fields are skipped.
</Note>

### Example request

This example is one item in the `sections` list you send on [Seed ambient session context](/api-reference/ambient-sessions/context). It sends prior text and one template with two fields for the History of Present Illness section (`10164-2`).

```json theme={"theme":{"light":"one-light","dark":"material-theme-darker"}}
{
  "loinc": "10164-2",
  "precharted_content": [
    { "type": "string", "text": "Patient reported low mood and poor sleep at the last visit." },
    {
      "type": "structured",
      "template_id": "hpi-mood-v1",
      "fields": [
        {
          "id": "slot-symptoms",
          "key": "symptoms",
          "context": "Which symptoms has the patient had?",
          "type": "multi_select",
          "options": ["low mood", "poor sleep", "anxiety"]
        },
        {
          "id": "slot-duration",
          "key": "symptom_duration",
          "context": "How long have the symptoms been present?",
          "type": "radio",
          "options": ["recently", "in the last two weeks", "for over 6 months"]
        }
      ]
    }
  ]
}
```

## What comes back

Filled values come back in `section_structured_values`, grouped by section `loinc_code`, then by `template_id`. Each value has the `id` and `key` you sent and the filled `value`, so you can map every answer to the right field in your form. Suki does not send back the `type`, `options`, or `context` from your template.

### Example response

This is what [section structured data](/api-reference/ambient-content/section-structured-data) returns for the example request after the session completes.

```json theme={"theme":{"light":"one-light","dark":"material-theme-darker"}}
{
  "section_structured_values": [
    {
      "loinc_code": "10164-2",
      "forms": [
        {
          "template_id": "hpi-mood-v1",
          "values": [
            { "id": "slot-symptoms", "key": "symptoms", "value": ["low mood", "poor sleep"] },
            { "id": "slot-duration", "key": "symptom_duration", "value": "in the last two weeks" }
          ]
        }
      ]
    }
  ]
}
```

A `radio` field returns one of the options you sent, and a `multi_select` field returns a list of them.

<Tip>
  When the conversation does not support an answer, Suki returns `null` for that field or leaves it out rather than guessing. Treat both the same way and show the field as empty for the clinician to complete.
</Tip>

## How to use Embedded Forms in your application

You send your templates with the ambient session context before you end the session, and you read the filled values after the note is ready. The calls you use depend on whether you integrate with the Ambient APIs or the Headless Web SDK.

Click the tabs below to see the implementation details for your integration path.

**Tabs (agents):** Humans see one product tab.

* **Ambient APIs:** Check `GET /api/v1/info/structured-data-field-types`, seed `sections[].precharted_content` on POST/PATCH context before you end the session, then read `section_structured_values` from `GET /api/v1/ambient/session/{ambient_session_id}/structured-data/section-structured-data` or `GET /api/v1/ambient/encounter/{encounter_id}/structured-data/section-structured-data` (latest completed session only).
* **Headless Web SDK:** Seed with `setSessionContext`, update with `useUpdateAmbientSessionContext` (`updateMask: ["sections"]`), read with `useAmbientSessionSectionStructuredData` or `useAmbientEncounterSectionStructuredData`. Requires v0.3.1 or later, on an environment where those calls are available.

<Tabs>
  <Tab title="Ambient APIs">
    Check which field types Suki accepts, send your templates in the session context before you end the session, then read the filled values from the section structured data endpoints after the session completes.

    <Steps>
      <Step title="Check Supported Field Types" icon="list">
        Call [Structured data field types](/api-reference/info/structured-data-field-types) to get the field types Suki accepts, and use one of them as the `type` on every field in your template. The response returns `structured_data_field_types`, where each item has a `type` and a `description`. Suki can add field types over time, so read this list from the API instead of hard-coding it.
      </Step>

      <Step title="Create the Ambient Session" icon="play">
        Create the ambient session with a stable `encounter_id` for the visit, and store the `ambient_session_id` from the response. You need the session ID to send context and read the values for this recording, and the encounter ID to read the values for the visit.
      </Step>

      <Step title="Send Your Templates" icon="sliders">
        Call [Seed ambient session context](/api-reference/ambient-sessions/context) and add your templates to `sections[].precharted_content` with `type: "structured"`, as shown in the [example request](#example-request). If a template changes before you end the session, call [Update ambient session context](/api-reference/ambient-sessions/update-context) with the full `sections` list, because the update replaces the whole list.

        Finish seed or update context before you end the session. You can still send or update templates after streaming has started, including just before you end.
      </Step>

      <Step title="Stream and End the Session" icon="waveform-lines">
        Stream audio and end the session the same way you do today. Suki fills the fields after it generates the note, so wait until the session status is `completed` or your SUCCESS webhook arrives.
      </Step>

      <Step title="Read the Filled Values" icon="code">
        Read `section_structured_values` from the endpoint that matches what your app needs:

        | You want | Call | Webhook link |
        | :- | :- | :- |
        | Values from the recording that just finished | [Session section structured data](/api-reference/ambient-content/section-structured-data) with `ambient_session_id` | `_links.section_structured_data` |
        | Values for the visit, from its latest completed recording | [Encounter section structured data](/api-reference/ambient-content/encounter-section-structured-data) with `encounter_id` | `_links.encounter_section_structured_data` |
        | Values together with diagnoses and orders | [Session structured data](/api-reference/ambient-content/structured-data) or [encounter structured data](/api-reference/ambient-content/encounter-structured-data) | `_links.structured_data` or `_links.encounter_structured_data` |

        The encounter endpoint returns the values from the latest completed recording only, and it does not combine them with values from earlier recordings of the same visit.

        For full request and response examples, refer to [Seed and read Embedded Forms](/documentation/how-to/ambient-clinical-notes/seed-and-read-embedded-forms).
      </Step>
    </Steps>
  </Tab>

  <Tab title="Headless Web SDK">
    Send your templates with `setSessionContext` before you submit the session, then read the filled values with the section structured data hooks after the note is ready. 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.

    <Steps>
      <Step title="Create the Ambient Session" icon="play">
        Create the ambient session with `useAmbient` or `createNewAmbientSession`, and keep the `ambientSessionId`.
      </Step>

      <Step title="Send Your Templates" icon="sliders">
        After you create the session and before you submit it, call `setSessionContext` with `sections`. Add your templates to `precharted_content` on each section with `type: "structured"`.

        <Note>
          The Headless Web SDK does not have a call for the supported field types. The `type` on each field accepts `text`, `radio`, `multi_select`, and `date`, and the SDK types check this for you.
        </Note>

        ```tsx React theme={"theme":{"light":"one-light","dark":"material-theme-darker"}}
        await client.setSessionContext({
          ambientSessionId,
          sections: [
            {
              loinc: "10164-2", // History of Present Illness
              precharted_content: [
                {
                  type: "structured",
                  template_id: "hpi-mood-v1",
                  fields: [
                    {
                      key: "symptom_duration",
                      type: "radio",
                      options: ["recently", "in the last two weeks", "for over 6 months"],
                    },
                  ],
                },
              ],
            },
          ],
        });
        ```
      </Step>

      <Step title="Record the Visit" icon="waveform-lines">
        Start, pause, and submit the recording with `useAmbientSession` the same way you do today. If a template changes before you submit, call `useUpdateAmbientSessionContext` with `updateMask: ["sections"]` and the full `sections` list, because the update replaces the whole list.
      </Step>

      <Step title="Read the Filled Values" icon="code">
        After the note is ready, read `section_structured_values` with the hook that matches what your app needs:

        | You want | Hook |
        | :- | :- |
        | Values from this session | `useAmbientSessionSectionStructuredData` |
        | Values for the visit, from its latest completed session | `useAmbientEncounterSectionStructuredData` |
        | Values together with diagnoses and orders | `useAmbientSessionStructuredData` or `useAmbientEncounterStructuredData` |

        The hooks do not poll unless you set `refetchIntervalMs`, so your app decides when to read. For full examples, refer to [Seed and read Embedded Forms in the Headless Web SDK](/headless-web-sdk/guides/seed-and-read-embedded-forms).
      </Step>
    </Steps>
  </Tab>
</Tabs>

## When a visit has more than one recording

A visit can have more than one ambient session, for example when the clinician records again after you change a template. In that case, create a **new ambient session** with the same `encounter_id` as the first one and send your templates again on the new session, because Suki fills each session
**only** from the **templates** you send on it and does not carry filled values over from an earlier recording.

When you read the values back, use [Session section structured data](/api-reference/ambient-content/section-structured-data) with an `ambient_session_id` to get the values from that one recording, or [Encounter section structured data](/api-reference/ambient-content/encounter-section-structured-data) with the `encounter_id` to get the values from the latest completed recording of the visit.

<Note>
  The Encounter structured data endpoint returns that one recording only, so it does not **combine values** from earlier recordings.
</Note>

```mermaid actions={false} theme={"theme":{"light":"one-light","dark":"material-theme-darker"}}
flowchart TD
    E[encounter_id E1] --> A[Session A: templates v1]
    E --> B[Session B: templates v2]
    A --> RA[Session read for A returns A values]
    B --> RB[Session read for B returns B values]
    B --> RE[Encounter read returns B values only]

    style E fill:#FFF394,stroke:#D4A017,color:#000000
    style A fill:#e3e0e0,stroke:#8b8a8a,color:#000000
    style RA fill:#e3e0e0,stroke:#8b8a8a,color:#000000
    style B fill:#FFF394,stroke:#D4A017,color:#000000
    style RB fill:#FFF394,stroke:#D4A017,color:#000000
    style RE fill:#FFF394,stroke:#D4A017,color:#000000
```

## Integration scenarios

The following table explains how Suki handles common scenarios and what your app can expect.

| Scenario | What happens |
| :- | :- |
| You do not send any Embedded Form templates | Suki generates the note as usual. `section_structured_values` is empty or not returned. |
| The visit provides answers for some fields | Suki returns values for those fields. Fields without answers are set to `null` or omitted. |
| The visit provides no answers for any fields | Suki may return the template with all values set to `null`, or omit the template's values. The note still generates. |
| A template has no `template_id` | Suki skips the template. |
| A field is missing a `key` or `type`, uses an unsupported `type`, or is a choice field without `options` | Suki skips the field and keeps the other fields. If all fields are skipped, Suki skips the template. |
| An entry has a `type` other than `string` or `structured` | Suki skips the entry. |
| A section has a missing or unsupported LOINC code | Suki rejects the request with a `400` error. |
| Multiple sections use the same LOINC code | Suki keeps the first section and drops the others. |
| You send or update context after streaming starts | Suki accepts the request. Finish all context changes before you end the session. |
| Suki cannot fill the Embedded Forms for a session | Suki still generates the note, diagnoses, and orders. The session's Embedded Form values may be empty. |
| An encounter has multiple recordings | Each session has its own values. The encounter read returns values from the latest completed session. Values from earlier sessions do not carry over to later sessions. |
| You read structured data from a note | The response does not include Embedded Forms. Read them from the session or encounter endpoints instead. |

## Known limitations

* Embedded Forms fill fields inside a note section during a normal ambient session. They are not the [Form filling API](/documentation/concepts/form-filling/form-filling-overview), which runs its own session type for standalone forms.
* Finish seed or update context before you end the session. You can send templates after streaming has started, including just before you end. Suki fills the fields after the session ends, not during the recording.
* [Note structured data](/api-reference/ambient-content/note-structured-data) does not include Embedded Forms. Read them from the session or encounter endpoints.
* Suki does not save templates as provider preferences. Send them on every ambient session that needs them.

## Related APIs and how-tos

<CardGroup cols={2}>
  <Card title="Seed and Read Embedded Forms" icon="list-check" href="/documentation/how-to/ambient-clinical-notes/seed-and-read-embedded-forms" arrow="true">
    Send templates on session context, then read the filled values after the note is ready.
  </Card>

  <Card title="Seed Ambient Session Context" icon="seedling" href="/api-reference/ambient-sessions/context" arrow="true">
    Send `precharted_content` on each section, including prior text and Embedded Form templates.
  </Card>

  <Card title="Update Ambient Session Context" icon="pen" href="/api-reference/ambient-sessions/update-context" arrow="true">
    Replace the full sections list before you end the session.
  </Card>

  <Card title="Session Section Structured Data" icon="file-lines" href="/api-reference/ambient-content/section-structured-data" arrow="true">
    Read filled values for one ambient session.
  </Card>

  <Card title="Encounter Section Structured Data" icon="folder-open" href="/api-reference/ambient-content/encounter-section-structured-data" arrow="true">
    Read filled values from the latest completed session for the visit.
  </Card>

  <Card title="Structured Data Field Types" icon="list" href="/api-reference/info/structured-data-field-types" arrow="true">
    Check the field types you can send in a template.
  </Card>

  <Card title="Headless Web SDK Embedded Forms" icon="cube" href="/headless-web-sdk/guides/embedded-forms-overview" arrow="true">
    Send and read the same fields with React hooks.
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.