Note Management

Quick summary

After you submit an ambient session, the Headed Web SDK generates a clinical note in the background. When the note is ready, the SDK returns the generated content, which you can save to your EHR.

Receive the note using the onNoteSubmit prop (React only) or the note-submission:success event (React and JavaScript). The response includes the note ID, encounter ID, note content organized into sections, and the LOINC code for each section. If medication orders are enabled, the response also includes an orders object. The generated note title matches the visitType value provided when the session was initialized.

Last updated:July 2026

After submitting an ambient session, the Headed Web SDK generates a clinical note in the background. Once ready, you can retrieve the note content and save it to your EHR. When Medication orders are enabled, the note submission payload also returns structured Medication orders under orders. Refer to Medication orders JSON schema for the orders payload structure and field definitions.

Common integration patterns and use cases

Design note handling around how your application receives submitted content and writes it into the EHR. The Web SDK generates the note after submit; your application listens for the payload and persists it. The following patterns show common ways to manage notes with the Web SDK:

Receive Notes in React

Pass onNoteSubmit to SukiAssistant, or subscribe to note-submission:success with useSuki().on, then map noteId, encounterId, and contents into your EHR write path.

Receive Notes in JavaScript

Subscribe to note-submission:success on the SDK client, read each section’s title, content, and loinc_code, then save the payload in your application.

Title Notes with Visit Type

Pass visitType in ambientOptions at mount or through setAmbientOptions so the in-product note list uses that value as the note title instead of the generic Note label.

Handle Medication Orders on Submit

When medication orders are enabled and LOINC 52471-0 is in ambientOptions.sections, read orders.medication_orders from the same submission payload and persist it with the note.

Account for Offline Generation Delay

Expect slower note generation after offline sessions because the full audio uploads after reconnect. Keep your submit handler ready for delayed note-submission:success events.

Map PBC Diagnosis Fields

When a section includes diagnosis, read the diagnosis fields from that section in contents and map them into your charting model with the note text.

Note generation

Note generation happens automatically after session submission. Generation time depends on connectivity:

Online: Faster generation since audio is processed in real-time during the conversation
Offline: Slower generation since the entire audio file must upload first after connection is restored

For more details, see the Offline mode guide.

Receiving note content

When a note is successfully submitted, the Headed Web SDK provides the note content to your application. When Medication orders are enabled, the same response includes an orders object. Receive the payload using either method:

onNoteSubmit prop (React only, recommended)
note-submission:success event (React and JavaScript)

JavaScript

const unsubscribeNoteSubmission = sdkClient.on("note-submission:success", (note) => {
  console.log("Note ID:", note.noteId);
  console.log("Encounter ID:", note.encounterId);
  console.log("Note contents:", note.contents);
  
  // Save to your EHR
  note.contents.forEach((section) => {
    console.log(`Section: ${section.title}`);
    console.log(`Content: ${section.content}`);
    console.log(`LOINC Code: ${section.loinc_code}`);
  });
});

Note titles in the Web SDK UI

When you pass visitType in ambientOptions at session init (for example in mount, ambientOptions on SukiAssistant, or setAmbientOptions), the Web SDK uses that value as the title for the generated note in the in-product patient note list. The generated note title will match the visitType value. This helps clinicians distinguish multiple notes created on the same day.

The generated note will have Created At Timestamp instead of Today date.

If visitType is omitted, the UI keeps the previous generic title behavior and the note title will show as Note.

Use values that match your integration contract (refer to the visitTypes reference for more information on available enum values). For the full ambientOptions available parameters, refer to the AmbientOptions reference guide.

Response structure

When a note is successfully submitted, you receive a response object with the following structure:

JSON

{
  "noteId": "82467ba8-71bc-46e2-8232-20d4d5629973",
  "encounterId": "encounter-12345",

  "contents": [
    {
      "title": "History",
      "content": "The patient is a 50-year-old female who has been experiencing fever for the last 10 days...",
      "loinc_code": "18233-4",
      "diagnosis": null
    },
    {
      "title": "Review of Systems",
      "content": "- No additional symptoms or pertinent negatives discussed during the encounter.",
      "loinc_code": "10164-2",
      "diagnosis": null
    },
    {
      "title": "Assessment and Plan",
      "content": "Viral hepatitis B with hepatic coma",
      "loinc_code": "51847-2",
      "diagnosis": {
        "icdCode": "B19.11",
        "icdDescription": "Unspecified viral hepatitis B with hepatic coma",
        "snomedCode": "26206000",
        "snomedDescription": "Hepatic coma due to viral hepatitis B",
        "hccCode": "HCC-1",
        "panelRanking": 1,
        "billable": true,
        "problemLabel": "Unspecified viral hepatitis B with hepatic coma"
      }
    }
  ],
  "orders": { // New in v3.2.0
    "medication_orders": {
      "values": [],
      "partial_values": []
    }
  }
}

Response fields

string

Unique identifier for the generated note

string

Unique identifier for the encounter associated with the note

Array<NoteContent>

Array of note sections. Each section contains:

title: Section title (e.g., “History of Present Illness”)
content: Section content in plain text
loinc_code: LOINC code for the section (optional)
diagnosis: Diagnosis information if applicable (optional). Refer to Diagnosis for complete structure.

object

Structured orders returned when medication orders are enabled. Refer to Medication orders JSON schema for field definitions.

orders is included only when Medication orders are enabled for your organization and you pass the Medications LOINC code 52471-0 in ambientOptions.sections. Refer to Medication orders integration to configure medication orders.

For complete type definitions, refer to NoteContent and Diagnosis.

Next steps

Learn about Token refresh to keep sessions alive Explore Error handling for note submission failures

Get Started

Concepts & Feature Guides

API Reference

Resources

Note Management

Common integration patterns and use cases

Receive Notes in React

Receive Notes in JavaScript

Title Notes with Visit Type

Handle Medication Orders on Submit

Account for Offline Generation Delay

Map PBC Diagnosis Fields

Note generation

Receiving note content

Note titles in the Web SDK UI

Response structure

Response fields

Next steps

​Common integration patterns and use cases

Receive Notes in React

Receive Notes in JavaScript

Title Notes with Visit Type

Handle Medication Orders on Submit

Account for Offline Generation Delay

Map PBC Diagnosis Fields

​Note generation

​Receiving note content

​Note titles in the Web SDK UI

​Response structure

​Response fields

​Next steps

Common integration patterns and use cases

Note generation

Receiving note content

Note titles in the Web SDK UI

Response structure

Response fields

Next steps