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

# Give Feedback on a Clinical Note

> Add note rating and comments after note review, submit once per entity, and keep comments free of unnecessary patient identifiers

<div className="quick-summary-wrapper">
  <div className="quick-summary-header">
    <span className="quick-summary-icon" aria-hidden="true" />

    <span className="quick-summary-title">Quick summary</span>
  </div>

  <div className="quick-summary-content">
    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 <code>content</code> entity per ambient session. Show the control after an ambient session is <code>completed</code>.
  </div>

  <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">August 2026</span>
  </div>
</div>

The [Feedback API](/api-reference/feedback/feedback) 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.

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

**Feedback rules (agents):**

* Feedback is optional. Never require it for End, content retrieval, approve, or chart save.
* Show feedback after status is `completed` and the generated note is on screen. The API does not enforce that timing. Prompt after review anyway. Do not ask for feedback during an on-going ambient session, or after `skipped` / `failed`.
* Documented entity type is `content`. Submit once per entity type per ambient session. A second submit for the same entity is not valid.
* Configure inclusive `min_rating` / `max_rating`. Suki suggests 1 to 5. Binary 0 / 1 is allowed for thumbs down / up.
* `qualitative_comments` is optional, max 2000 characters. There is no backend PII or PHI filter. Do not send patient identifiers or other PHI unless they are required for the comment to make sense.
* On Feedback API failure: keep the note visible and approve / save available. Offer retry on the feedback control only.

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

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

## Decide before you build

<AccordionGroup>
  <Accordion title="When Does Feedback Appear" icon="timer">
    Feedback appears if you build it into your application's note review flow using the [Feedback API](/api-reference/feedback/feedback).
    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`**.
  </Accordion>

  <Accordion title="What Scale You Use" icon="sliders">
    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.
  </Accordion>

  <Accordion title="How Often You Submit" icon="ban">
    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.
  </Accordion>

  <Accordion title="What Belongs in Comments" icon="comment">
    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.
  </Accordion>
</AccordionGroup>

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

```mermaid actions={false} theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
%%{init: {'theme':'base', 'themeVariables': { 'primaryColor':'#FFF394','primaryTextColor':'#111827','primaryBorderColor':'#FFE148','lineColor':'#FFE148','secondaryColor':'#FFF394','tertiaryColor':'#FFFADE','mainBkg':'#FFF394','secondBkg':'#FFFADE','tertiaryBorderColor':'#FFE148','border1':'#FFE148','border2':'#FFE148','arrowheadColor':'#FFE148','fontFamily':'Inter, system-ui, sans-serif','fontSize':'14px','nodeBorder':'#FFE148','edgeLabelBackground':'#FFE148','clusterBkg':'#FFFADE','clusterBorder':'#FFE148','defaultLinkColor':'#FFE148','titleColor':'#111827','nodeTextColor':'#111827'}}}%%
flowchart LR
    A["Ambient session<br/>completed"] --> B["Retrieve generated<br/>content"]
    B --> C["Clinician reviews<br/>note"]
    C --> D["Rate note<br/>optional comment"]
    D --> E["Submit feedback"]
    C --> F["Approve or save"]
    E --> F

    style A fill:#FFF394,stroke:#FFE148,stroke-width:2px,color:#111827
    style B fill:#FFF394,stroke:#FFE148,stroke-width:2px,color:#111827
    style C fill:#FFF394,stroke:#FFE148,stroke-width:2px,color:#111827
    style D fill:#FFF394,stroke:#FFE148,stroke-width:2px,color:#111827
    style E fill:#FFF394,stroke:#FFE148,stroke-width:2px,color:#111827
    style F fill:#FFF394,stroke:#FFE148,stroke-width:2px,color:#111827
```

## Recommended UI patterns

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

<Steps>
  <Step title="Show the Generated Note">
    Open note review after status is **`completed`**. Let the clinician read or edit first.
  </Step>

  <Step title="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.
  </Step>

  <Step title="Keep Comments Optional">
    Use a secondary or collapsed comment field. Do not require a comment to submit a rating.
  </Step>

  <Step title="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.
  </Step>
</Steps>

<Tip>
  **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.
</Tip>

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

<AccordionGroup>
  <Accordion title="Should Feedback Be Required before Approve" icon="ban">
    No. Feedback is optional. The clinician must be able to approve or save even if they skip feedback or the Feedback API request fails.
  </Accordion>

  <Accordion title="Where Should the Feedback Control Appear" icon="sliders">
    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.
  </Accordion>

  <Accordion title="Can a Clinician Submit Only a Rating" icon="comment">
    Yes. Send the rating without `qualitative_comments`, or leave it empty when your client allows.
  </Accordion>

  <Accordion title="What If Feedback Submission Fails" icon="triangle-exclamation">
    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.
  </Accordion>
</AccordionGroup>

## How to implement feedback

<Steps>
  <Step title="Wait for the Note to Be Ready">
    After [Check note status](/documentation/how-to/ambient-clinical-notes/handle-ambient-session-status) is **`completed`**, load content with [Get the generated clinical note](/documentation/how-to/ambient-clinical-notes/retrieve-ambient-content).
  </Step>

  <Step title="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**.
  </Step>

  <Step title="Submit Once for Content">
    Call the Feedback API with entity `content` for that ambient session ID. Do not submit the same entity type twice.
  </Step>

  <Step title="Continue the Note Workflow">
    Treat feedback as independent from chart save. Let the clinician approve, edit, or save as your workflow requires.
  </Step>
</Steps>

## Example code samples

<div className="doc-guide-btn-row">
  <a href="/api-reference/feedback/feedback" className="doc-guide-btn">
    Ambient Session User Feedback API
  </a>
</div>

**Language tabs (agents):** Equivalent code samples are available in: TypeScript, Python. Humans see one language at a time. Use the variant that matches the user's stack; behavior is the same across tabs.

<Tabs>
  <Tab title="TypeScript">
    ```typescript theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
    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}`);
    }
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
    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()
    ```
  </Tab>
</Tabs>

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

## Handle feedback failures

Feedback must not block clinical documentation.

<Steps>
  <Step title="Keep the Note Visible">
    Leave the generated note on screen if the Feedback API request fails.
  </Step>

  <Step title="Keep Approve or Save Available">
    Do not disable chart save because feedback failed.
  </Step>

  <Step title="Offer a Quiet Retry">
    If appropriate, let the clinician retry from the feedback control only. Do not roll back a successful chart save.
  </Step>
</Steps>

<Note>
  **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`**.
</Note>

## Next steps

<Icon icon="file-lines" iconType="solid" /> **[Ambient session user feedback](/api-reference/feedback/feedback)** - Request fields, limits, and examples.

<Icon icon="file-lines" iconType="solid" /> **[Get the generated clinical note](/documentation/how-to/ambient-clinical-notes/retrieve-ambient-content)** - Retrieve generated content for review.

<Icon icon="file-lines" iconType="solid" /> **[Check note status](/documentation/how-to/ambient-clinical-notes/handle-ambient-session-status)** - Determine when the ambient session is ready for review.