Provide Visit Context

Seed patient, note sections, diagnoses, and related visit fields after create, and finish context before the ambient session ends

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. You can skip context for a first API-only integration. Seed specialty, visit type, sections, and known diagnoses when you want Suki to use this information for better note generation.

Prerequisites

• An ambient session that has already been created, with a stored ambient_session_id. See Create an ambient clinical note.
• A valid Suki Token. See Partner authentication.
• The visit values you plan to send (patient, note sections, diagnoses, or related fields). Use Info APIs when you need supported catalogs.

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:

1. Collect the visit information available to your application.
2. Create the ambient session.
3. Seed the visit context with POST, or update it with PATCH as additional information becomes available.
4. Complete context updates before ending the session.
5. 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)
Prior section text or fields you want Suki to fill on a section	sections[].precharted_content in session context. See Embedded Forms
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

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

2. Optionally Review Known Diagnoses

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

3. Create, Then Seed

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

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

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

2. Build the Context Payload

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

3. POST Seed Context

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

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

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

TypeScript

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

Related feature guides

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.

Embedded Forms

Send template fields on a section and read the filled values after the visit.

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.

Troubleshooting

Context problems usually show up as rejected fields, a full seed that wiped mid-visit values, or diagnoses carried forward with the wrong code types.

Context Sent on Create Instead of After Create

Create the ambient session first, then seed or update context. Do not put patient demographics, LOINC sections, diagnoses, or note style on the create request.

POST Seed Wiped Fields You Meant to Keep

POST replaces the entire context. If you already seeded earlier and only a few fields changed, use PATCH instead so you send only what changed.

HCC Codes Rejected or Copied into the Next Session

Seed ICD10 or IMO diagnoses only. Never send HCC in context. If you copy structured-data diagnoses into the next ambient context, strip HCC first.

Verbosity or Section Format Sent in Context

Do not send verbosity or section_format in context. Those belong in personalization, not seed or update context.

Context Updated After End

Finish every context call before End. Updates sent after End do not shape note generation for that session.

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.