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

# Add Information During a Visit

> PATCH changed visit context during an active Ambient session and complete updates before End

<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">
    PATCH visit context when your application's chart details change during an active ambient session. Send only the fields that changed or became available, such as diagnoses, orders, or note sections. Complete every update before you end the session.
  </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 [Update ambient session context](/api-reference/ambient-sessions/update-context) API lets you change visit context **after an ambient session has started**. Use `PATCH` to send only the fields that have changed or become available.

This is useful when visit information arrives gradually. For example, a diagnosis may be added after recording starts, medication orders may become available later, or the clinician may change the note sections before ending the session.

**Update context rules (agents):**

* Prefer POST seed when the full prepare-visit payload is ready at Start. Prefer PATCH update when only some fields are new or corrected mid-visit.
* PATCH sends a partial body (field mask). Fields in the request replace previous values. They do not append. Send the complete `sections` list when the template changes.
* Do not require the clinician to stop recording to refresh context. Changes apply to this session when the update finishes before End.
* Same exclusions as seed: never HCC; never `verbosity` or `section_format` in context.
* Require an active `ambient_session_id` that has not been ended yet.
* Complete every context update before End. Late updates after End do not shape that session's note generation.
* Do not use the deprecated ambient session metadata endpoint. Migrate to seed or update context.

## When to use POST vs PATCH

Choose the method based on when the information becomes available:

|                 | POST: Seed context                                      | PATCH: Update context                                                   |
| :-------------- | :------------------------------------------------------ | :---------------------------------------------------------------------- |
| **Use when**    | You have the full context when the session starts       | New or corrected information becomes available after the session starts |
| **Request**     | Full context payload                                    | Only the fields that changed                                            |
| **Timing**      | After creating the session and before End               | After creating the session and before End                               |
| **Behavior**    | Sets the session context                                | Replaces the fields included in the request                             |
| **Typical use** | Patient and visit information is ready before recording | Diagnoses, orders, or note sections change during the visit             |

When the full visit context is ready before recording, send it with POST seed. When details change after Ambient has started, PATCH only the fields that changed. Many integrations seed the context they have at Start, then PATCH diagnoses, orders, or sections as the chart updates.
Refer to [Provide visit context](/documentation/how-to/ambient-clinical-notes/seed-ambient-session-context) guide for the initial context workflow.

## How PATCH updates work

* PATCH uses a field mask, so send only the fields you want to change.

* **Fields** in the request replace their previous values. They **do not append** to the existing values.

For example, if you update `sections`, send the **complete list of sections you want for the session**. Do not send only the newly added section.
You can update context while the ambient session is recording or paused. You do not need to stop and restart the session just to update context.

<Warning>
  Complete context updates before you end the Ambient session. Updates sent after End do not shape note generation for that session.
</Warning>

## Common mid-visit scenarios

It is your responsibility to update context as the visit progresses. You should not expect the clinician to stop and restart the session to update context.
The following are common mid-visit scenarios that you should handle for better user experience.

**Mid-visit scenario accordions (agents):** Humans expand one panel at a time.

* **Diagnosis Added During the Visit:** PATCH diagnosis only. Never HCC.
* **Orders Become Available After Start:** PATCH medication orders or `emr.target_emr` before End.
* **Note Sections Change Before Stop:** PATCH full new `sections` list. Value replaces previous list.
* **All Visit Context Is Available at Start:** Prefer POST seed with full payload.

<AccordionGroup>
  <Accordion title="Diagnosis Added During the Visit" icon="notes-medical">
    If a new diagnosis is added after Ambient has started, use PATCH to update the diagnosis before ending the session. Do not send HCC codes in update context.
  </Accordion>

  <Accordion title="Orders Become Available After Start" icon="pills">
    If Medication orders or `emr.target_emr` become available after the session starts, use PATCH to send those fields before ending the session.
  </Accordion>

  <Accordion title="Note Sections Change Before Stop" icon="list">
    If the clinician changes the note sections while Ambient is still active, use PATCH to update `sections`. Send the complete new `sections` list because the value replaces the previous list.
  </Accordion>

  <Accordion title="All Visit Context Is Available at Start" icon="clipboard-list">
    If the clinician has confirmed the patient, sections, and known problems before recording starts, prefer POST seed with the full context payload.
  </Accordion>
</AccordionGroup>

## What to send

Update context follows the same send and do-not-send rules as [Provide visit context](/documentation/how-to/ambient-clinical-notes/seed-ambient-session-context).

<CardGroup cols={2}>
  <Card title="Send" icon="check">
    PATCH only the fields that changed or became available during the visit. For example:

    * A newly added diagnosis (**ICD10** or **IMO** only)
    * Medication orders that become available after Start
    * `emr.target_emr` when it becomes available after Start
    * A changed `sections` list (send the complete list you want)
  </Card>

  <Card title="Do Not Send" icon="ban">
    Do not include:

    * **HCC codes**
    * `verbosity`
    * `section_format`

    See [Diagnosis codes](/api-reference/faqs/diagnosis-codes) and [Note Personalization](/api-reference/capabilities/personalization#build-personalization-into-your-product).
  </Card>
</CardGroup>

## Recommended workflow

If you are building your own ambient experience with the Ambient APIs or Headless modalities, connect chart changes to the active ambient session.

<Steps>
  <Step title="Create the Ambient Session">
    Create the session and keep the returned `ambient_session_id`.
  </Step>

  <Step title="Seed Context When Available">
    If you have the full prepare-visit payload, send it with [Seed ambient session context](/api-reference/ambient-sessions/context).
  </Step>

  <Step title="Start and Continue the Visit">
    Keep the Ambient session active while the clinician records the visit.
  </Step>

  <Step title="Update Context as Information Changes">
    When chart data changes, call [Update ambient session context](/api-reference/ambient-sessions/update-context) with only the fields that changed. Keep the recorder in Recording or Paused state. Do not restart the Ambient session for a context update.
  </Step>

  <Step title="Finish Pending Updates Before End">
    Make sure all pending context updates have completed before following the Stop → `RU9G` → End flow. See [Complete an ambient visit](/documentation/how-to/ambient-clinical-notes/end-ambient-session).
  </Step>
</Steps>

```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[Create session] --> B{Full context available?}
    B -->|Yes| C[POST seed context]
    B -->|No| D[Start Ambient]
    C --> D
    D --> E[Stream audio]
    E --> F[Chart data changes]
    F --> G[PATCH changed fields]
    G --> E
    E --> H[Finish pending updates]
    H --> I[End session]

    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
    style G fill:#FFF394,stroke:#FFE148,stroke-width:2px,color:#111827
    style H fill:#FFF394,stroke:#FFE148,stroke-width:2px,color:#111827
    style I fill:#FFF394,stroke:#FFE148,stroke-width:2px,color:#111827
```

<Tip>
  **Prefer PATCH for information that becomes available during the visit.** You can start Ambient with the core context you have and update diagnoses, orders, or sections as the chart changes.
</Tip>

## Example code to update note sections

Send only the fields you want to change. In this example, the `sections` value replaces the previous section list.

<div className="doc-guide-btn-row">
  <a href="/api-reference/ambient-sessions/update-context" className="doc-guide-btn">
    Update Ambient Session Context 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 response = await fetch(
      `https://sdp.suki.ai/api/v1/ambient/session/${ambientSessionId}/context`,
      {
        method: "PATCH",
        headers: {
          "Content-Type": "application/json",
          sdp_suki_token: sdpSukiToken,
          sdp_provider_id: sdpProviderId,
        },
        body: JSON.stringify({
          sections: [
            { loinc: "10154-3" },
            { loinc: "10164-2" },
            { loinc: "29545-1" },
            { loinc: "51847-2" },
          ],
        }),
      }
    );

    if (!response.ok) {
      throw new Error(`Update context failed: ${response.status}`);
    }
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
    import requests

    response = requests.patch(
        f"https://sdp.suki.ai/api/v1/ambient/session/{ambient_session_id}/context",
        headers={
            "Content-Type": "application/json",
            "sdp_suki_token": sdp_suki_token,
            "sdp_provider_id": sdp_provider_id,
        },
        json={
            "sections": [
                {"loinc": "10154-3"},
                {"loinc": "10164-2"},
                {"loinc": "29545-1"},
                {"loinc": "51847-2"},
            ],
        },
    )
    response.raise_for_status()
    ```
  </Tab>
</Tabs>

## Common FAQs

**Important requirements accordions (agents):** Humans expand one panel at a time.

* Active `ambient_session_id` required; session must not have ended.
* PATCH sends partial fields only; included fields replace previous values.
* Updates allowed while recording or paused; finish before End.
* No HCC, `verbosity`, or `section_format` in update context.

<AccordionGroup>
  <Accordion title="Does PATCH Require an Active Session?" icon="circle-check">
    Yes. You need the `ambient_session_id` from the create request, and the Ambient session must not have ended.
  </Accordion>

  <Accordion title="Do I Need to Send the Full Context with PATCH?" icon="ban">
    No. Send only the fields that changed or became available.
  </Accordion>

  <Accordion title="Do Updated Fields Append or Replace Previous Values?" icon="list">
    They replace the previous values for the fields included in the request. If you update `sections`, send the complete list you want for the session.
  </Accordion>

  <Accordion title="Can I Update Context While Recording?" icon="waveform">
    Yes. You can update context while the session is recording or paused. You do not need to stop and restart Ambient for a context update.
  </Accordion>

  <Accordion title="Can I Update Context After End?" icon="timer">
    No. Complete context updates before ending the session. Updates sent after End do not shape note generation for that session.
  </Accordion>

  <Accordion title="Can I Send HCC or Personalization Fields?" icon="triangle-exclamation">
    No. Do not send HCC codes, `verbosity`, or `section_format` in update context. The same exclusions apply to seed context.
  </Accordion>
</AccordionGroup>

<Info>
  These patterns apply when you build your own Ambient experience with the **Ambient APIs** or **Headless modalities**. The headed **Web SDK** already provides the Ambient UI, so you do not need to recreate these mid-visit context update patterns.
</Info>

## Next steps

<Icon icon="file-lines" iconType="solid" /> **[Update ambient session context API](/api-reference/ambient-sessions/update-context)** - PATCH request schema and examples.

<Icon icon="file-lines" iconType="solid" /> **[Provide visit context](/documentation/how-to/ambient-clinical-notes/seed-ambient-session-context)** - Prepare and send context when you have visit information at the start.

<Icon icon="file-lines" iconType="solid" /> **[Complete an ambient visit](/documentation/how-to/ambient-clinical-notes/end-ambient-session)** - Finish capture after required context updates are complete.

<Icon icon="file-lines" iconType="solid" /> **[Medication orders](/documentation/concepts/ambient-clinical-notes/medication-orders)** - Medication order fields you can update during the visit.