Skip to main content
Quick summary
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.
Last updated:August 2026
The Update ambient session 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.

​
When to use POST vs PATCH

Choose the method based on when the information becomes available: 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 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.
Complete context updates before you end the Ambient session. Updates sent after End do not shape note generation for that session.

​
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.
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.
If Medication orders or emr.target_emr become available after the session starts, use PATCH to send those fields before ending the session.
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.
If the clinician has confirmed the patient, sections, and known problems before recording starts, prefer POST seed with the full context payload.

​
What to send

Update context follows the same send and do-not-send rules as Provide visit context.

Send

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)

Do Not Send

Do not include:
  • HCC codes
  • verbosity
  • section_format
See Diagnosis codes and Note Personalization.
If you are building your own ambient experience with the Ambient APIs or Headless modalities, connect chart changes to the active ambient session.
1

Create the Ambient Session

Create the session and keep the returned ambient_session_id.
2

Seed Context When Available

If you have the full prepare-visit payload, send it with Seed ambient session context.
3

Start and Continue the Visit

Keep the Ambient session active while the clinician records the visit.
4

Update Context as Information Changes

When chart data changes, call Update ambient session 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.
5

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

​
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.
Update Ambient Session Context API

​
Common FAQs

Yes. You need the ambient_session_id from the create request, and the Ambient session must not have ended.
No. Send only the fields that changed or became available.
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.
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.
No. Complete context updates before ending the session. Updates sent after End do not shape note generation for that session.
No. Do not send HCC codes, verbosity, or section_format in update context. The same exclusions apply to seed context.
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.

​
Next steps

Update ambient session context API - PATCH request schema and examples. Provide visit context - Prepare and send context when you have visit information at the start. Complete an ambient visit - Finish capture after required context updates are complete. Medication orders - Medication order fields you can update during the visit.
Last modified on August 20, 2026