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

# Provide Visit Context

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

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

[Create an ambient clinical note](/documentation/how-to/ambient-clinical-notes/create-ambient-session) 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](/api-reference/ambient-sessions/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](/documentation/how-to/ambient-clinical-notes/update-ambient-session-context) 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.

**Context seed rules (agents):**

* Seed after create and before End. Prefer a prepare-visit or start ambient confirmation so clinicians see what will shape the note.
* Do not put patient, sections, diagnoses, verbosity, or `section_format` on create. Those belong in context or personalization.
* Send provider specialty and role, patient and visit fields, LOINC `sections`, known diagnoses (ICD10 or IMO only), EMR target, and medication orders context when you use them.
* Context fields are optional in the API. If you omit `sections`, Suki generates all supported note sections. Prefer explicit sections when your chart uses a fixed template.
* POST seed replaces the entire context for that session. PATCH update replaces only the fields you send. When you change `sections`, send the complete list.
* Never send HCC in context. HCC is output-only on structured data. If re-seeding from structured data, strip HCC first.
* Never send `verbosity` or `section_format` in context. Those belong in [Note Personalization](/api-reference/capabilities/personalization#build-personalization-into-your-product) / user preferences.
* For notes that open in Web SDK, include `patient_id`, `name`, `dob`, and `sex` so the patient profile can render.
* Use POST seed for a full prepare-visit payload. Use PATCH update when only some fields change mid-visit. Both must finish before End.

<Tip>
  If the note may open later in Web SDK, seed `patient_id`, `name`, `dob`, and `sex`. See [Seed patient context for Web SDK](/documentation/cookbooks/seed-patient-context-for-web-sdk). For mid-visit changes only, use [Add information during a visit](/documentation/how-to/ambient-clinical-notes/update-ambient-session-context).
</Tip>

## 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](/api-reference/user-preferences/preferences) / [Note Personalization](/api-reference/capabilities/personalization#build-personalization-into-your-product) |
| Session or note identifiers                                            | [Create](/api-reference/ambient-sessions/create), not context                                                                                                                 |
| HCC codes                                                              | Do not send. Read them from structured-data output only                                                                                                                       |

<CardGroup cols={2}>
  <Card title="Send" icon="check">
    **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
  </Card>

  <Card title="Do Not Send" icon="ban">
    **What to exclude:**

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

    **Why:**

    * HCC is structured-data output only. See [Diagnosis codes](/api-reference/faqs/diagnosis-codes).
    * Note style belongs in personalization, not visit context.
  </Card>
</CardGroup>

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

## When to seed

<AccordionGroup>
  <Accordion title="Prepare Visit before or during Capture" icon="clipboard-list">
    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.
  </Accordion>

  <Accordion title="Web SDK May Open the Note Later" icon="browser">
    Include `patient_id`, `name`, `dob`, and `sex` so the patient profile can render. See [Use interoperable ambient notes across modalities](/documentation/how-to/ambient-clinical-notes/use-ambient-across-modalities).
  </Accordion>

  <Accordion title="Clinician Changes Note Style" icon="sliders">
    Verbosity and section format are not context. Use [Note Personalization](/api-reference/capabilities/personalization#build-personalization-into-your-product).
  </Accordion>

  <Accordion title="Re-Seeding Diagnoses from Structured Data" icon="triangle-exclamation">
    Filter before re-seeding. Never send HCC. Keep ICD10 or IMO only. See [Diagnosis codes](/api-reference/faqs/diagnosis-codes).
  </Accordion>
</AccordionGroup>

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

```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[Open chart] --> B[Confirm patient and sections]
    B --> C[Optional: known diagnoses]
    C --> D[Create ambient session]
    D --> E[Seed or update context]
    E --> F[Stream audio]
    F --> G[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 D fill:#FFF394,stroke:#FFE148,stroke-width:2px,color:#111827
    style E fill:#FFF394,stroke:#FFE148,stroke-width:2px,color:#111827
    style G fill:#FFF394,stroke:#FFE148,stroke-width:2px,color:#111827
```

## 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](/documentation/how-to/ambient-clinical-notes/update-ambient-session-context).

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

## 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](/documentation/concepts/ambient-clinical-notes/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](/api-reference/user-preferences/preferences), not this context body                               |

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

  <Step title="Optionally Review Known Diagnoses">
    If you seed known problems, show codes and descriptions the clinician already trusts. Do not invent diagnoses for context.
  </Step>

  <Step title="Create, Then Seed">
    Call create, then POST the context body. Use PATCH later if more fields arrive. See [Add information during a visit](/documentation/how-to/ambient-clinical-notes/update-ambient-session-context).
  </Step>

  <Step title="Stream, Then End">
    Open `/ws/stream`, capture the visit, and finish any last context updates **before** End.
  </Step>
</Steps>

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

<AccordionGroup>
  <Accordion title="Can Context Arrive after Streaming Starts" icon="timer">
    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](/documentation/how-to/ambient-clinical-notes/update-ambient-session-context).
  </Accordion>

  <Accordion title="Where Does Note Verbosity Belong" icon="sliders">
    In personalization / user preferences, not in the context body. Do not send `verbosity` or `section_format` here.
  </Accordion>

  <Accordion title="Can I Seed HCC from Structured Data" icon="ban">
    No. Strip HCC before any re-seed. Keep ICD10 or IMO only. See [Diagnosis codes](/api-reference/faqs/diagnosis-codes).
  </Accordion>

  <Accordion title="What If Web SDK Opens the Note Later" icon="browser">
    Seed `patient_id`, `name`, `dob`, and `sex` so the patient profile can render across modalities.
  </Accordion>
</AccordionGroup>

## How to implement seed context

<Steps>
  <Step title="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](/documentation/how-to/ambient-clinical-notes/create-ambient-session).
  </Step>

  <Step title="Build the Context Payload">
    Include provider, patient, `sections`, and any diagnoses or orders your product uses. Exclude HCC and personalization fields.
  </Step>

  <Step title="POST Seed Context">
    Call [Seed ambient session context](/api-reference/ambient-sessions/context) for that `ambient_session_id`. POST replaces the entire context for the session.
  </Step>

  <Step title="Stream, Update If Needed, Then End">
    Open `/ws/stream`. PATCH update if chart data arrives mid-visit. Complete context before End.
  </Step>
</Steps>

## Example: seed sections and patient before streaming

<div className="doc-guide-btn-row">
  <a href="/api-reference/ambient-sessions/context" className="doc-guide-btn">
    Seed Ambient Session Context API
  </a>
</div>

**Language tabs (agents):** Equivalent code samples are available in: Python, TypeScript. 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="Python">
    ```python theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
    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()
    ```
  </Tab>

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

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

## Available cookbooks

<div className="hp-io-method-grid tut-hub-card-grid" data-cookbook-related-grid>
  <a className="hp-io-method-card tut-hub-method-card" href="/documentation/cookbooks/seed-patient-context-for-web-sdk">
    <div className="tut-hub-card-media tut-hub-card-media--blue" aria-hidden="true" />

    <div className="hp-io-method-card-body">
      <div className="tut-hub-card-badges">
        <span className="hp-wn-badge hp-wn-badge-new">Ambient</span>
        <span className="hp-wn-badge cookbook-hub-badge-surface cookbook-hub-badge-surface--api">API</span>
      </div>

      <h3 className="hp-io-method-card-title">Seed Patient Context for Web SDK</h3>

      <p className="hp-io-method-card-desc cookbook-hub-card-desc">
        Seed patient\_id, name, dob, and sex for the headed profile.
      </p>

      <div className="hp-io-method-card-meta tut-hub-card-foot" aria-label="5 min">
        <div className="tut-hub-card-foot-meta">
          <span className="hp-io-method-card-meta-time">5 min</span>
        </div>
      </div>
    </div>
  </a>
</div>

## Related feature guides

<CardGroup cols={2}>
  <Card title="Note Sections" icon="list" href="/documentation/concepts/ambient-clinical-notes/note-sections" arrow={true}>
    Choose LOINC sections for the ambient note template.
  </Card>

  <Card title="Specialties" icon="stethoscope" href="/documentation/concepts/ambient-clinical-notes/specialties" arrow={true}>
    Pass specialty context for documentation style.
  </Card>

  <Card title="Medication Orders" icon="pills" href="/documentation/concepts/ambient-clinical-notes/medication-orders" arrow={true}>
    Send medication orders context when you use orders.
  </Card>

  <Card title="Problem-Based Charting" icon="notes-medical" href="/api-reference/capabilities/problem-based-charting" arrow={true}>
    Organize notes around problems and coded diagnoses.
  </Card>
</CardGroup>

## Implementation checklist

<Note>
  * 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](/documentation/concepts/ambient-clinical-notes/note-sections).
</Note>

## Next steps

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

<Icon icon="file-lines" iconType="solid" /> **[Add information during a visit](/documentation/how-to/ambient-clinical-notes/update-ambient-session-context)** - PATCH when fields arrive mid-visit.

<Icon icon="file-lines" iconType="solid" /> **[Create an ambient clinical note](/documentation/how-to/ambient-clinical-notes/create-ambient-session)** - Create the session, then seed context.

<Icon icon="file-lines" iconType="solid" /> **[Use Info APIs](/documentation/how-to/ambient-clinical-notes/use-ambient-info-apis)** - Supported specialties, visit types, and LOINCs.

<Icon icon="file-lines" iconType="solid" /> **[Note Personalization](/api-reference/capabilities/personalization#build-personalization-into-your-product)** - Note style outside context.