Seed and Read Embedded Forms

This guide shows how to send Embedded Form templates with the Ambient APIs and read the filled values after the visit. For what Embedded Forms are and when to send string versus structured content, refer to Embedded Forms.

Prerequisites

A working ambient integration that can create a session, seed context, stream audio, end the session, and check status. Refer to Create an ambient clinical note.
A valid Suki Token. Refer to Partner authentication.
The LOINC codes of the note sections you want to fill. Refer to Note sections.
A stable template_id for each template and a stable key for each field, so you can match the filled values back to your form.

Workflow overview

Seed Embedded Forms

Complete these steps after you create the ambient session and before you end the session.

Create the Ambient Session

Call Create ambient session and save the ambient_session_id from the response. You need it for every call in this guide, and session context can only be sent after the session exists.Send a stable encounter_id for the visit when you create the session. The encounter endpoint uses it to return the latest completed recording for the visit, and you send the same encounter_id again if the clinician records the visit a second time.

Check Supported Field Types

Every field in a template needs a type. Before you seed context, call Structured data field types and check that each field in your template uses a type from the list. The response returns structured_data_field_types, where each item has a type and a description. The same list is also returned on System Information.Today the list includes text, radio, multi_select, and date.

Suki maintains this list, so read it from the API instead of hard-coding field types in your integration.

Seed Embedded Forms on Session Context

Call Seed ambient session context after you create the session and before you end the session. Each item in sections has a loinc that identifies the note section. To fill fields on that section, add a precharted_content list next to the loinc.Each entry in precharted_content is one of two types. A structured entry is an Embedded Form template with the fields you want Suki to fill. A string entry is text that is already in the chart for that section, such as prior history, and Suki considers it when it writes the section. You can send both on the same section.

object

Prior text for the section.

Hide properties

"string"

required

Marks this entry as prior text.

string

required

The text you already have for the section, for example "Patient reported low mood and poor sleep at the last visit."

object

An Embedded Form template.

Hide properties

"structured"

required

Marks this entry as an Embedded Form template.

string

required

Your stable ID for the template. The same value comes back on the filled values. A template without template_id is skipped.

array

required

Fields for Suki to fill.

Show field properties

string

Optional: Your ID for the field. Suki returns it unchanged on the filled value.

string

required

Stable machine name for the field. The same value comes back on the filled value.

string

Optional: What the field asks for, for example "How long have the symptoms been present?" You can include other field id values as {id} placeholders, for example "Patient has had {slot-symptoms} for {slot-duration}". Used for filling only and not returned.

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

required

Field type.

string[]

Required for radio and multi_select. The choices Suki can pick from, for example ["recently", "in the last two weeks", "for over 6 months"]. Used for filling only and not returned.

Each entry is either string or structured, so do not mix text and fields in one entry. An entry with any other type is skipped. Send each LOINC once in sections. If the same LOINC appears more than once, Suki keeps the first one and drops the rest.
Skipping fields: Suki also skips a single field, and keeps the other fields in that template, when the field has no key, no type, a type it does not support, or when it is a radio or multi_select with no options. The request still succeeds. The whole template is dropped only when template_id is missing, or when every field in it was skipped.

Request: seed context with prior text and one templateThis request seeds the History of Present Illness section (10164-2) with prior text and a template that has three fields: symptoms (multi_select), how long the symptoms have lasted (radio), and when they started (date). It also adds Assessment and Plan (51847-2) without a template, so Suki writes that section without filling any fields.

Python
TypeScript

import requests

BASE_URL = "https://sdp.suki.ai"
ambient_session_id = "<ambient_session_id>"

headers = {
    "sdp_suki_token": "<sdp_suki_token>",
    "sdp_provider_id": "<sdp_provider_id>",  # Required for single_auth partners
    "Content-Type": "application/json",
}

payload = {
    "sections": [
        {
            "loinc": "10164-2",  # History of Present Illness
            "precharted_content": [
                {
                    "type": "string",  # Prior text already in the chart
                    "text": "Patient reported low mood and poor sleep at the last visit.",
                },
                {
                    "type": "structured",  # Embedded Form template
                    "template_id": "hpi-mood-v1",  # Comes back on the filled values
                    "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"],
                        },
                        {"id": "slot-onset", "key": "onset_date", "type": "date"},
                    ],
                },
            ],
        },
        {"loinc": "51847-2"},  # Assessment and Plan, no template
    ],
}

response = requests.post(
    f"{BASE_URL}/api/v1/ambient/session/{ambient_session_id}/context",
    headers=headers,
    json=payload,
    timeout=60,
)

if response.status_code == 200:
    print("Embedded Form templates seeded.")
else:
    print(f"Seed context failed: {response.status_code}")
    print(response.text)

const BASE_URL = "https://sdp.suki.ai";
const ambientSessionId = "<ambient_session_id>";

const payload = {
  sections: [
    {
      loinc: "10164-2", // History of Present Illness
      precharted_content: [
        {
          type: "string", // Prior text already in the chart
          text: "Patient reported low mood and poor sleep at the last visit.",
        },
        {
          type: "structured", // Embedded Form template
          template_id: "hpi-mood-v1", // Comes back on the filled values
          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"],
            },
            { id: "slot-onset", key: "onset_date", type: "date" },
          ],
        },
      ],
    },
    { loinc: "51847-2" }, // Assessment and Plan, no template
  ],
};

const response = await fetch(
  `${BASE_URL}/api/v1/ambient/session/${ambientSessionId}/context`,
  {
    method: "POST",
    headers: {
      sdp_suki_token: "<sdp_suki_token>",
      sdp_provider_id: "<sdp_provider_id>", // Required for single_auth partners
      "Content-Type": "application/json",
    },
    body: JSON.stringify(payload),
  }
);

if (response.ok) {
  console.log("Embedded Form templates seeded.");
} else {
  console.error(`Seed context failed: ${response.status}`, await response.text());
}

Response: A successful request returns 200 with no response body. A missing or unsupported LOINC returns 400.

POST replaces the entire session context. If you also send patient, visit, diagnoses, or orders context, include them in the same POST body. Refer to Provide visit context.

Correct templates before you end the session

If a template changes after you seed context, for example the clinician picks a different template during the visit, call Update ambient session context with sections in the PATCH body. Finish the update before you end the session. You can update after streaming has started, including just before you end. PATCH does not merge your change into the previous sections list. It replaces the whole list, so send every section and every precharted_content entry you want to keep, not only the one that changed. Request body: update context with the full sections list This PATCH body adds fatigue to the symptoms options and keeps Assessment and Plan. Because the new list replaces the old one, this body also removes the prior text and the other two fields from the seed request. Send them again if you still need them.

{
  "sections": [
    {
      "loinc": "10164-2",
      "precharted_content": [
        {
          "type": "structured",
          "template_id": "hpi-mood-v1",
          "fields": [
            { "id": "slot-symptoms", "key": "symptoms", "type": "multi_select", "options": ["low mood", "poor sleep", "anxiety", "fatigue"] }
          ]
        }
      ]
    },
    { "loinc": "51847-2" }
  ]
}

Response: A successful request returns 200 with the updated session context.

Finish all Embedded Form changes before you end the session. You can seed or update after streaming has started, including just before you end. To use different templates after a recording completes, start a new ambient session on the same encounter. Refer to Change templates after a recording.

Stream and end the session

Stream audio and end the session the same way you do today. Refer to Stream ambient audio in your product and End ambient session. Suki fills the template fields after it finishes generating the note, not while audio is streaming. There are no values to read until the session completes.

Read the filled values

After Session status is completed, or after your SUCCESS webhook arrives, read the filled values in section_structured_values. Use the session endpoint when you want the values from the recording that just finished, and the encounter endpoint when you want the values for the visit, which come from its latest completed recording only. If your chart also needs diagnoses and orders, the session and encounter structured data endpoints return the same values in structured_data.section_structured_values.

You need	Call	Webhook link
Embedded Forms for the recording that just finished	Session section structured data	`_links.section_structured_data`
Embedded Forms for the latest completed recording of the visit	Encounter section structured data	`_links.encounter_section_structured_data`
Embedded Forms with diagnoses and orders in one call	Session structured data or encounter structured data, field `structured_data.section_structured_values`	`_links.structured_data` or `_links.encounter_structured_data`

Note structured data does not include Embedded Forms. Use the session or encounter endpoints above.

The response groups the filled values by section, then by template. Each section has a loinc_code and a forms list, each form has the template_id you sent, and each filled value has the id and key you sent with its value. Request: read the session values and build a lookup This request reads the values for one session. It then builds a lookup keyed by loinc_code, template_id, and the field id (or key when you did not send an id), so your app can find the answer for any field directly.

Python
TypeScript

import requests

BASE_URL = "https://sdp.suki.ai"
ambient_session_id = "<ambient_session_id>"

headers = {
    "sdp_suki_token": "<sdp_suki_token>",
    "sdp_provider_id": "<sdp_provider_id>",
}

response = requests.get(
    f"{BASE_URL}/api/v1/ambient/session/{ambient_session_id}/structured-data/section-structured-data",
    headers=headers,
    timeout=60,
)
response.raise_for_status()

# Build a lookup: (loinc, template_id, field id or key) -> value
filled = {}
for section in response.json().get("section_structured_values") or []:
    for form in section.get("forms") or []:
        for field in form.get("values") or []:
            field_ref = field.get("id") or field.get("key")
            filled[(section.get("loinc_code"), form.get("template_id"), field_ref)] = field.get("value")

value = filled.get(("10164-2", "hpi-mood-v1", "slot-duration"))
print("Symptom duration:", value if value is not None else "(not filled)")

type FilledValue = { id?: string; key: string; value?: string | string[] | null };
type SectionStructuredData = {
  loinc_code?: string;
  forms?: Array<{ template_id?: string; values?: FilledValue[] }>;
};

const BASE_URL = "https://sdp.suki.ai";
const ambientSessionId = "<ambient_session_id>";

const response = await fetch(
  `${BASE_URL}/api/v1/ambient/session/${ambientSessionId}/structured-data/section-structured-data`,
  {
    headers: {
      sdp_suki_token: "<sdp_suki_token>",
      sdp_provider_id: "<sdp_provider_id>",
    },
  }
);
if (!response.ok) {
  throw new Error(`Read failed: ${response.status}`);
}

const body: { section_structured_values?: SectionStructuredData[] } = await response.json();

// Build a lookup: loinc|template_id|field id or key -> value
const filled = new Map<string, FilledValue["value"]>();
for (const section of body.section_structured_values ?? []) {
  for (const form of section.forms ?? []) {
    for (const field of form.values ?? []) {
      filled.set(`${section.loinc_code}|${form.template_id}|${field.id ?? field.key}`, field.value);
    }
  }
}

const duration = filled.get("10164-2|hpi-mood-v1|slot-duration");
console.log("Symptom duration:", duration ?? "(not filled)");

Example response This is the response for the seed request above. The onset_date field comes back as null because the visit did not cover when the symptoms started.

{
  "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" },
            { "id": "slot-onset", "key": "onset_date", "value": null }
          ]
        }
      ]
    }
  ]
}

Map values back to your form

Match each filled value to your form with loinc_code, template_id, and the field id or key you sent. The response has id, key, and value only. It does not return the type, options, or context you sent, so keep your own copy of the template if your UI needs them.

text returns a string.
radio returns one of the options you sent, as a string.
multi_select returns a list of the options you sent. If your template shows them as one sentence, join them in your app with the separator your locale uses.
No answer comes back as null, or the field is left out. Treat both the same way and leave the field empty for the clinician to complete.

If the clinician already filled a field by hand during the visit, keep the clinician’s value and skip the Suki value for that field.

Change templates after a recording

To record the same visit again with new or changed templates, create a new ambient session with the same encounter_id, seed the updated templates on that session, then stream and end it as usual. Do not try to update the finished session. Suki fills the new session only from the templates and text you send on it. It does not look up or reuse the values filled in the earlier session. If those earlier values should shape the new recording, read them from the earlier session and send what you need as prior text, or prefill them in your own UI. After Session B completes, the encounter endpoint returns Session B values only. Use the session endpoint with Session A’s ambient_session_id if you still need the earlier values.

Best practices

Use this checklist to confirm your integration handles Embedded Forms end to end:

Every call sends a valid Suki Token in sdp_suki_token. If you use Single Auth Token authentication, every call also sends sdp_provider_id.
You create the ambient session before you send any context.
You send a stable encounter_id when you create the session, and you send the same encounter_id when the clinician records the visit again.
Your templates are in sections[].precharted_content with type: "structured".
Every template has a stable template_id, and every field has a stable key.
You finish all context changes before you end the session. You can still seed or update after streaming has started.
After the session completes, you read the values from session or encounter section structured data, or from structured_data.section_structured_values.
You do not read Embedded Forms from note structured data.
When templates change after a recording, you start a new ambient session on the same encounter with the updated templates.
Empty or null values do not stop your workflow, and your app still uses the note content and the other structured data.

Troubleshooting

section_structured_values Is Empty

Check that the session status is completed before you read, and that you read from the session or encounter endpoints, not note structured data. Then check the seed request: each template needs type: "structured", a template_id, and at least one field with a key and a type. A template without template_id is skipped, and so is a template when every field in it was skipped. If the request was correct, the visit may not have covered any of your fields. The note still generates when no values are filled.

Some Fields Are null or Missing

Suki returns null, or leaves a field out, when the conversation does not support an answer. Leave that field empty for the clinician to complete. A field can also be missing because Suki skipped it on the way in. That happens when the field has no key, no type, a type Suki does not support, or it is a radio or multi_select with no options. The request still succeeds, and the other fields in that template are kept.

When to Finish Context Changes

Finish seed and update context before you end the session. You can still send or update templates after streaming has started, including just before you end. If you need different templates after the recording completes, create a new ambient session with the same encounter_id and send the templates on that session.

The Request Is Rejected with a LOINC Error

Every section needs a supported loinc. Check the code against Note sections or Supported LOINCs.

A Template or Section Is Missing After PATCH

PATCH replaces the full sections list. Send every section and every precharted_content entry you want to keep, not only the one that changed.

A Duplicate Section Was Ignored

Send each LOINC once in sections. When the same LOINC appears more than once, Suki keeps the first one. Put all prior text and templates for that section in one precharted_content list.

Encounter Read Shows Values from a Different Recording

The encounter endpoint returns the latest completed session for the encounter_id. To read one specific recording, call the session endpoint with that ambient_session_id.

The Response Does Not Include Options or Field Types

Read responses return id, key, and value only. Keep your own copy of the template for type, options, and labels.

Next steps

Embedded Forms - What Embedded Forms are and when to send string or structured content. Seed ambient session context - Full request body, including precharted_content. Get ambient session section structured data - Response shape for filled values. Webhook payload and response - SUCCESS links for section structured data. Get the generated clinical note - Load note content and structured data after the session ends.

Get Started

Concepts & Feature Guides

Executives & Agents

FAQs & Support

Seed and Read Embedded Forms

Prerequisites

Workflow overview

Seed Embedded Forms

Correct templates before you end the session

Stream and end the session

Read the filled values

Map values back to your form

Change templates after a recording

Best practices

Troubleshooting

Next steps

​Prerequisites

​Workflow overview

​Seed Embedded Forms

​Correct templates before you end the session

​Stream and end the session

​Read the filled values

​Map values back to your form

​Change templates after a recording

​Best practices

​Troubleshooting

​Next steps

Prerequisites

Workflow overview

Seed Embedded Forms

Correct templates before you end the session

Stream and end the session

Read the filled values

Map values back to your form

Change templates after a recording

Best practices

Troubleshooting

Next steps