Embedded Forms

Embedded Forms are supported by: Ambient APIs and Headless Web SDK

Ambient APIs: You send templates on Seed ambient session 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 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.

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

Fill Template Fields from a Visit

Get an answer for each blank in a note template, such as symptoms or duration, after the visit.

Include Prior Section Text

Send history that is already in the chart so Suki considers it when it writes the section.

Read Fields with Diagnoses and Orders

Get the template answers in the same call as diagnoses and orders.

Record the Visit Again

Record the visit again with updated templates and read the new answers.

How Embedded Forms work

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.

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.

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.

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.

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.

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

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`

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.

Do not put text and fields in one entry. Each entry is either string or structured.

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

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

Example request

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

{
  "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 returns for the example request after the session completes.

{
  "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.

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.

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.

Ambient APIs
Headless Web SDK

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.

Check Supported Field Types

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

Create the Ambient Session

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.

Send Your Templates

Call Seed ambient session context and add your templates to sections[].precharted_content with type: "structured", as shown in the example request. If a template changes before you end the session, call Update ambient session 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.

Stream and End the Session

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.

Read the Filled Values

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 with `ambient_session_id`	`_links.section_structured_data`
Values for the visit, from its latest completed recording	Encounter section structured data with `encounter_id`	`_links.encounter_section_structured_data`
Values together with diagnoses and orders	Session structured data or 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.

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.

Create the Ambient Session

Create the ambient session with useAmbient or createNewAmbientSession, and keep the ambientSessionId.

Send Your Templates

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

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.

React

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"],
            },
          ],
        },
      ],
    },
  ],
});

Record the Visit

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.

Read the Filled Values

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.

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 with an ambient_session_id to get the values from that one recording, or Encounter section structured data with the encounter_id to get the values from the latest completed recording of the visit.

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

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

Seed and Read Embedded Forms

Send templates on session context, then read the filled values after the note is ready.

Seed Ambient Session Context

Send precharted_content on each section, including prior text and Embedded Form templates.

Update Ambient Session Context

Replace the full sections list before you end the session.

Session Section Structured Data

Read filled values for one ambient session.

Encounter Section Structured Data

Read filled values from the latest completed session for the visit.

Structured Data Field Types

Check the field types you can send in a template.

Headless Web SDK Embedded Forms

Send and read the same fields with React hooks.

Get Started

Concepts & Feature Guides

Executives & Agents

FAQs & Support

Embedded Forms

Common use cases

Fill Template Fields from a Visit

Include Prior Section Text

Read Fields with Diagnoses and Orders

Record the Visit Again

How Embedded Forms work

Prior text and Embedded Form templates

Which value types to send

What a structured field template looks like

Example request

What comes back

Example response

How to use Embedded Forms in your application

When a visit has more than one recording

Integration scenarios

Known limitations

Seed and Read Embedded Forms

Seed Ambient Session Context

Update Ambient Session Context

Session Section Structured Data

Encounter Section Structured Data

Structured Data Field Types

Headless Web SDK Embedded Forms

​Common use cases

Fill Template Fields from a Visit

Include Prior Section Text

Read Fields with Diagnoses and Orders

Record the Visit Again

​How Embedded Forms work

​Prior text and Embedded Form templates

​Which value types to send

​What a structured field template looks like

​Example request

​What comes back

​Example response

​How to use Embedded Forms in your application

​When a visit has more than one recording

​Integration scenarios

​Known limitations

​Related APIs and how-tos

Seed and Read Embedded Forms

Seed Ambient Session Context

Update Ambient Session Context

Session Section Structured Data

Encounter Section Structured Data

Structured Data Field Types

Headless Web SDK Embedded Forms

Common use cases

How Embedded Forms work

Prior text and Embedded Form templates

Which value types to send

What a structured field template looks like

Example request

What comes back

Example response

How to use Embedded Forms in your application

When a visit has more than one recording

Integration scenarios

Known limitations

Related APIs and how-tos