Give Feedback on a Clinical Note

Quick summary

After the clinician reviews a generated clinical note from an ambient session, offer a rating and comment feature. This feature is optional and does not block approving or saving the note. Submit once for the content entity per ambient session. Show the control after an ambient session is completed.

Last updated:August 2026

The Feedback API lets your product collect a rating and optional comment about generated ambient clinical notes. Feedback is optional. It is not required to end an ambient session, retrieve content, approve a note, or save the note to the EHR. If you build your own ambient experience, add feedback to the note review flow. Show it after the note is ready, keep it lightweight, and let the clinician continue to approve or save the note without submitting feedback. When you collect feedback well, it helps clinicians to:

Rate the note while the visit is still fresh.
Leave a short comment when something was wrong or especially good.
Finish review without a second, confusing feedback screen later.

What you build for feedback to work

A rating control on the note review screen (Suki suggests a 1 to 5 scale).
An optional comment field (max 2000 characters). Do not prompt for PII or PHI unless it is required to understand the feedback.
A way to skip feedback and continue to approve / save.
One submit for the content entity per ambient session.

These patterns apply when you build your own ambient experience with the Ambient APIs or the Headless modalities. The headed Web SDK already provides the Ambient UI, so you do not need to recreate these feedback patterns.

Why collect feedback

Feedback gives Suki information about how clinicians assess generated ambient content. Ratings and comments are reviewed and used to help improve AI-generated clinical content over time.

What the clinician submits	How it helps
A rating on the generated note	Indicates whether the note was ready to use or needed substantial editing
An optional comment	Adds context a score alone cannot (missing detail, wrong section, strong HPI)

Treat feedback as secondary to the note workflow. Do not require a successful Feedback API call before approve, sign, or chart save.

Decide before you build

When Does Feedback Appear

Feedback appears if you build it into your application’s note review flow using the Feedback API. A good time to show the feedback control is after the ambient session is completed and the generated note is visible. That is when the clinician can judge the note and provide feedback.The API does not reject feedback sent earlier, but there is nothing useful to rate until the note is ready. Do not request feedback while the session is Generating, or after skipped / failed.

What Scale You Use

Configure min_rating and max_rating in the Feedback API request. The range is inclusive.Suki suggests 1 to 5:

Field	Example
`min_rating`	`1`
`max_rating`	`5`
`rating`	`4`

For a binary thumbs down / up experience, use 0 / 1. Your app maps the clinician’s selection to the request values.

How Often You Submit

For a given ambient session, submit feedback for each entity type only once. The documented entity type for this flow is content.After a successful submit, disable or hide the feedback control for that entity. A second submission for the same entity type is not valid.

What Belongs in Comments

Comments are optional (max 2000 characters). They can describe a missing detail, an incorrect section, heavy edits, or content that was especially accurate.There is no formal PII or PHI filter on qualitative_comments. Do not send patient identifiers or other PHI unless that detail is required for the feedback to be understood. Comments improve the product and model. They are not a second clinical note.

How feedback fits into the visit

Collect feedback after the generated note is available and the clinician has had a chance to review it. Feedback is independent of chart save. The clinician can approve or save without submitting feedback.

Recommended UI patterns

Place feedback on the same screen where the clinician reviews the generated note. Keep the experience to a few seconds.

Show the Generated Note

Open note review after status is completed. Let the clinician read or edit first.

Show a Compact Rating Control

Place Rate this note near approve / save on the same screen. Prefer 1 to 5 (stars or numbered buttons), or thumbs down / up when your product needs binary scoring.

Keep Comments Optional

Use a secondary or collapsed comment field. Do not require a comment to submit a rating.

Submit Once, Then Confirm

When the clinician taps Submit feedback, POST once for entity content. Show a brief thank-you, disable or hide the control, and leave them on review so they can approve or save.

Keep feedback lightweight: ask once after review, keep the control compact, accept rating-only submissions, keep approve / save available without feedback, and avoid repeatedly prompting clinicians who skip.

UI element	What the clinician sees	Your application responsibility
Rating control	Stars, 1 to 5, or thumbs	Map selection to `min_rating`, `max_rating`, and `rating`
Optional comment	Short free-text field	Cap at 2000 characters. Do not prompt for PII or PHI unless it is required to understand the feedback
Submit feedback	One clear action	POST once for entity `content`. Disable or hide after success
Skip / dismiss	Continue without rating	Allow approve / save without feedback
Confirmation	Brief thank-you	Confirm locally. Return the clinician to note review

Should Feedback Be Required before Approve

No. Feedback is optional. The clinician must be able to approve or save even if they skip feedback or the Feedback API request fails.

Where Should the Feedback Control Appear

On the note review screen near Approve / Save, where the clinician is already judging note quality. Avoid a separate post-visit email or a second page after they leave the chart.

Can a Clinician Submit Only a Rating

Yes. Send the rating without qualitative_comments, or leave it empty when your client allows.

What If Feedback Submission Fails

Keep note review and Approve / Save available. Offer a quiet retry on the feedback control only. Do not prevent or roll back chart save because feedback failed.

How to implement feedback

Wait for the Note to Be Ready

After Check note status is completed, load content with Get the generated clinical note.

Show Rating and Optional Comment

Add the control to the note review screen near Approve / Save. Use a clear label such as Rate this note.

Submit Once for Content

Call the Feedback API with entity content for that ambient session ID. Do not submit the same entity type twice.

Continue the Note Workflow

Treat feedback as independent from chart save. Let the clinician approve, edit, or save as your workflow requires.

Example code samples

Ambient Session User Feedback API

TypeScript
Python

const sessionId = ambientSessionId;
const entity = "content";

const response = await fetch(
  `https://sdp.suki.ai/api/v1/ambient/session/${sessionId}/${entity}/feedback`,
  {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      sdp_suki_token: sdpSukiToken,
      sdp_provider_id: sdpProviderId,
    },
    body: JSON.stringify({
      ratingFeedback: {
        min_rating: 1,
        max_rating: 5,
        rating: 4,
      },
      qualitative_comments: "HPI was accurate; A/P needed light edits.",
    }),
  }
);

if (!response.ok) {
  throw new Error(`Submit feedback failed: ${response.status}`);
}

import requests

session_id = ambient_session_id
entity = "content"

response = requests.post(
    f"https://sdp.suki.ai/api/v1/ambient/session/{session_id}/{entity}/feedback",
    headers={
        "Content-Type": "application/json",
        "sdp_suki_token": sdp_suki_token,
        "sdp_provider_id": sdp_provider_id,
    },
    json={
        "ratingFeedback": {
            "min_rating": 1,
            "max_rating": 5,
            "rating": 4,
        },
        "qualitative_comments": "HPI was accurate; A/P needed light edits.",
    },
)

response.raise_for_status()

Submit feedback for each entity type only once per ambient session. Do not retry a successful submission for the same content entity. A second submission is not valid.

Handle feedback failures

Feedback must not block clinical documentation.

Keep the Note Visible

Leave the generated note on screen if the Feedback API request fails.

Keep Approve or Save Available

Do not disable chart save because feedback failed.

Offer a Quiet Retry

If appropriate, let the clinician retry from the feedback control only. Do not roll back a successful chart save.

Implementation checklist:

Show feedback after completed and note is visible.
Provide a rating control (1 to 5 unless you need another supported range).
Keep comments optional (max 2000). Do not send patient identifiers unless the comment needs them.
Submit content once.
Allow skip.
Never block Approve / Save on feedback failure.
Never show feedback for skipped or failed.

Next steps

Ambient session user feedback - Request fields, limits, and examples. Get the generated clinical note - Retrieve generated content for review. Check note status - Determine when the ambient session is ready for review.

Get Started

Concepts & Feature Guides

Resources

FAQs & Support

Give Feedback on a Clinical Note

Why collect feedback

Decide before you build

How feedback fits into the visit

Recommended UI patterns

How to implement feedback

Example code samples

Handle feedback failures

Next steps

​Why collect feedback

​Decide before you build

​How feedback fits into the visit

​Recommended UI patterns

​How to implement feedback

​Example code samples

​Handle feedback failures

​Next steps

Why collect feedback

Decide before you build

How feedback fits into the visit

Recommended UI patterns

How to implement feedback

Example code samples

Handle feedback failures

Next steps