Provide Visit Context

Quick summary

After you create an ambient session, use session context to tell Suki about this visit: patient, note sections, known diagnoses, and related orders when you use them. Do not put personalization or HCC codes in context. Finish seed or update context before you end the ambient session.

Last updated:August 2026

Create an ambient clinical note starts the recording and returns an ambient_session_id. It does not include information about the patient, the current visit, or how the note should be structured. Use Seed ambient session context to give Suki information about the current visit. Depending on your integration, this can include:

Patient information
Note sections to include
Known diagnoses
Specialty
Related orders

This context gives Suki additional information about the visit when generating the ambient note.

When to provide context

Provide context at the point in your workflow where your application has the visit information available:

Use POST to seed the context after create, when the information is available before or at the start of recording.
Use PATCH with Add information during a visit when information becomes available or changes during the visit.

Complete all context updates before you end the ambient session. Updates made after End do not affect the note generated for that session.

Keep context separate from other settings

Not all information belongs in visit context:

Information	Where it belongs
Patient and current visit details	Visit context
Requested note sections	Visit context
Known diagnoses	Visit context
`verbosity` and `section_format`	Preferences
HCC codes	Structured-data output

What your application needs

Your integration should:

Collect the visit information available to your application.
Create the ambient session.
Seed the visit context with POST, or update it with PATCH as additional information becomes available.
Complete context updates before ending the session.
Keep preferences and structured-data output separate from visit context.

If the note may open later in Web SDK, seed patient_id, name, dob, and sex. See Seed patient context for Web SDK. For mid-visit changes only, use Add information during a visit.

Choose what belongs in context

If you need to send…	Put it in
Patient, sections, diagnoses, specialty, EMR target, medication orders	Session context (POST seed or PATCH update)
Note verbosity or section format	User preferences / Note Personalization
Session or note identifiers	Create, not context
HCC codes	Do not send. Read them from structured-data output only

Send

What to include:

Provider specialty and role
Patient and visit fields
LOINC note sections
Known diagnoses (ICD10 or IMO only)
emr.target_emr and medication orders context when you use orders

When to send:

After create, when the prepare-visit payload is ready
Before End, including any mid-visit PATCH updates

Do Not Send

What to exclude:

HCC codes
verbosity
section_format

Why:

HCC is structured-data output only. See Diagnosis codes.
Note style belongs in personalization, not visit context.

If you copy structured-data diagnoses into the next ambient context, strip HCC first. Keep only code types your product is allowed to seed, such as ICD10 or IMO.

When to seed

Prepare Visit before or during Capture

Seed patient, sections, diagnoses, and visit fields after create and before End. Prefer a prepare-visit or start ambient confirmation so clinicians see what will shape the note.

Web SDK May Open the Note Later

Include patient_id, name, dob, and sex so the patient profile can render. See Use interoperable ambient notes across modalities.

Clinician Changes Note Style

Verbosity and section format are not context. Use Note Personalization.

Re-Seeding Diagnoses from Structured Data

Filter before re-seeding. Never send HCC. Keep ICD10 or IMO only. See Diagnosis codes.

Prepare-visit flow

Think of context as the clinical frame around the recording, not as ambient configuration for mic format or note verbosity. Clinicians should recognize the prepare step as part of the visit: confirm patient, confirm which sections this note needs, optionally review known problems, then Start.

When to use POST vs PATCH

	POST: Seed context	PATCH: Update context
Use when	The full prepare-visit payload is ready	New or corrected fields arrive after the session starts
Request	Full context payload	Only the fields that changed
Timing	After create and before End	After create and before End
Behavior	Replaces the entire session context	Replaces only the fields included in the request
Typical use	Patient, sections, and known problems at Start	Diagnoses, orders, or sections change mid-visit

When the full visit context is ready before recording, send it with POST seed. When details change after ambient session has started, PATCH only the fields that changed. See Add information during a visit.

If you change sections with PATCH, send the complete list you want for the session. PATCH replaces the previous list. It does not append one new section.

Recommended UI patterns

Specialty and role are often set once per provider and sent without a separate screen. Patient, sections, and optional diagnoses should be visible enough that clinicians trust what will shape the note.

Screen or control in your app	What the clinician does	What your backend sends
Patient chart / visit open	Opens the encounter	Patient id, name, dob, sex, and visit fields you already trust
Note template or section picker	Confirms which sections this note needs	`sections` as `{ "loinc": "…" }` (see Note sections)
Problem list / known diagnoses	Reviews diagnoses you already have	Diagnoses with ICD10 or IMO only. Never HCC
Specialty / role (often hidden)	Usually set once per provider	`provider.specialty`, `provider.provider_role`
EMR / orders (if you use them)	Optional	`emr.target_emr`, medication orders context
Settings (separate from this step)	Changes note style	User preferences, not this context body

Confirm Patient and Sections

On prepare-visit or start ambient, show the patient and the note sections this visit needs. Let the clinician correct the template before capture when your product allows it.

Optionally Review Known Diagnoses

If you seed known problems, show codes and descriptions the clinician already trusts. Do not invent diagnoses for context.

Create, Then Seed

Call create, then POST the context body. Use PATCH later if more fields arrive. See Add information during a visit.

Stream, Then End

Open /ws/stream, capture the visit, and finish any last context updates before End.

Recommended UX sequence: Open chart → confirm patient and sections → optionally show known diagnoses → Start recording. Call create, then seed or update context before you end the session.

Can Context Arrive after Streaming Starts

Yes. You can PATCH update while the ambient session is still open. All context must still finish before End. If you change sections, send the complete list. See Add information during a visit.

Where Does Note Verbosity Belong

In personalization / user preferences, not in the context body. Do not send verbosity or section_format here.

Can I Seed HCC from Structured Data

No. Strip HCC before any re-seed. Keep ICD10 or IMO only. See Diagnosis codes.

What If Web SDK Opens the Note Later

Seed patient_id, name, dob, and sex so the patient profile can render across modalities.

How to implement seed context

Create the Ambient Session

Call create and store ambient_session_id. Do not send patient, sections, or note style on create. See Create an ambient clinical note.

Build the Context Payload

Include provider, patient, sections, and any diagnoses or orders your product uses. Exclude HCC and personalization fields.

POST Seed Context

Call Seed ambient session context for that ambient_session_id. POST replaces the entire context for the session.

Stream, Update If Needed, Then End

Open /ws/stream. PATCH update if chart data arrives mid-visit. Complete context before End.

Example: seed sections and patient before streaming

Seed Ambient Session Context API

Python
TypeScript

import requests

ambient_session_id = "<ambient_session_id>"

payload = {
    "provider": {
        "specialty": "<provider_specialty>",
        "provider_role": "<provider_role>",
    },
    "patient": {
        "patient_id": "<patient_id>",
        "name": {
            "given": ["<patient_given_name>"],
            "family": "<patient_family_name>",
        },
        "dob": "<patient_dob>",  # YYYY-MM-DD
        "sex": "<patient_sex>",  # male | female | other | unknown
    },
    "sections": [
        {"loinc": "10154-3"},  # Chief Complaint
        {"loinc": "10164-2"},  # History of Present Illness
        {"loinc": "29545-1"},  # Physical Exam
        {"loinc": "51847-2"},  # Assessment and Plan
    ],
    # Diagnoses: ICD10 or IMO only. Never HCC.
}

response = requests.post(
    f"https://sdp.suki.ai/api/v1/ambient/session/{ambient_session_id}/context",
    json=payload,
    headers={
        "sdp_suki_token": "<sdp_suki_token>",
        "sdp_provider_id": "<sdp_provider_id>",
    },
)
response.raise_for_status()

const ambientSessionId = "<ambient_session_id>";

const payload = {
  provider: {
    specialty: "<provider_specialty>",
    provider_role: "<provider_role>",
  },
  patient: {
    patient_id: "<patient_id>",
    name: {
      given: ["<patient_given_name>"],
      family: "<patient_family_name>",
    },
    dob: "<patient_dob>", // YYYY-MM-DD
    sex: "<patient_sex>", // male | female | other | unknown
  },
  sections: [
    { loinc: "10154-3" }, // Chief Complaint
    { loinc: "10164-2" }, // History of Present Illness
    { loinc: "29545-1" }, // Physical Exam
    { loinc: "51847-2" }, // Assessment and Plan
  ],
  // Diagnoses: ICD10 or IMO only. Never HCC.
};

const response = await fetch(
  `https://sdp.suki.ai/api/v1/ambient/session/${ambientSessionId}/context`,
  {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      sdp_suki_token: "<sdp_suki_token>",
      sdp_provider_id: "<sdp_provider_id>",
    },
    body: JSON.stringify(payload),
  }
);

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

Exact patient and provider field shapes must match the OpenAPI request body on the context endpoint. Use the API reference examples as the source of truth for nested property names. Validate enumerated values such as visit_type, encounter_type, provider_role, and emr.target_emr against the Ambient Info API catalogs when your application needs them.

Available cookbooks

AmbientAPI

Seed Patient Context for Web SDK

Seed patient_id, name, dob, and sex for the headed profile.

5 min

Note Sections

Choose LOINC sections for the ambient note template.

Specialties

Pass specialty context for documentation style.

Medication Orders

Send medication orders context when you use orders.

Problem-Based Charting

Organize notes around problems and coded diagnoses.

Implementation checklist

Create first. Seed or update context after create. Do not put patient, sections, or note style on create.
Finish every context call before End.
POST seed replaces the entire context. PATCH replaces only the fields you send.
Send ICD10 or IMO for diagnoses. Never send HCC in context.
Do not send verbosity or section_format in context.
For Web SDK later, seed patient_id, name, dob, and sex.
Map note sections with LOINC codes from Note sections.

Next steps

Seed ambient session context API - Full request body and examples. Add information during a visit - PATCH when fields arrive mid-visit. Create an ambient clinical note - Create the session, then seed context. Use Info APIs - Supported specialties, visit types, and LOINCs. Note Personalization - Note style outside context.

Get Started

Concepts & Feature Guides

Resources

FAQs & Support

Provide Visit Context

When to provide context

Keep context separate from other settings

What your application needs

Choose what belongs in context

Send

Do Not Send

When to seed

Prepare-visit flow

When to use POST vs PATCH

Recommended UI patterns

How to implement seed context

Example: seed sections and patient before streaming

Available cookbooks

Seed Patient Context for Web SDK

Note Sections

Specialties

Medication Orders

Problem-Based Charting

Implementation checklist

Next steps

​When to provide context

​Keep context separate from other settings

​What your application needs

​Choose what belongs in context

Send

Do Not Send

​When to seed

​Prepare-visit flow

​When to use POST vs PATCH

​Recommended UI patterns

​How to implement seed context

​Example: seed sections and patient before streaming

​Available cookbooks

​Seed Patient Context for Web SDK

​Related feature guides

Note Sections

Specialties

Medication Orders

Problem-Based Charting

​Implementation checklist

​Next steps

When to provide context

Keep context separate from other settings

What your application needs

Choose what belongs in context

When to seed

Prepare-visit flow

When to use POST vs PATCH

Recommended UI patterns

How to implement seed context

Example: seed sections and patient before streaming

Available cookbooks

Seed Patient Context for Web SDK

Related feature guides

Implementation checklist

Next steps