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

# Get Ambient Encounter Section Structured Data

> Retrieve filled Embedded Form values from the latest completed ambient session for an encounter

Use this endpoint to get the filled [Embedded Form](/documentation/concepts/ambient-clinical-notes/embedded-forms) values for an <Tooltip tip="One patient visit or appointment with a healthcare provider. In Suki, an encounter can group one or more ambient sessions so related recordings and notes stay tied to the same clinical visit." cta="View in Glossary" href="/Glossary/e">encounter</Tooltip>.

Use the [Session Section Structured Data endpoint](/api-reference/ambient-content/section-structured-data) to get values for one recording. Use this endpoint to get values from the latest completed recording for the visit.

<Info>
  This endpoint does not merge values from earlier recordings.
</Info>

<Note>
  For when to read by session or by encounter, and what happens when the visit is recorded again, refer to [Seed and read Embedded Forms](/documentation/how-to/ambient-clinical-notes/seed-and-read-embedded-forms#change-templates-after-a-recording).
</Note>

## Code examples

**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":"one-light","dark":"material-theme-darker"}}
    import requests

    encounter_id = "<encounter_id>"
    url = f"https://sdp.suki.ai/api/v1/ambient/encounter/{encounter_id}/structured-data/section-structured-data"

    headers = {
        "sdp_suki_token": "<sdp_suki_token>",
        "sdp_provider_id": "<sdp_provider_id>",
    }

    response = requests.get(url, headers=headers)

    if response.status_code == 200:
        # Values from the latest completed ambient session for this encounter
        for section in response.json().get("section_structured_values") or []:
            print(f"Section {section.get('loinc_code')}")
            for form in section.get("forms") or []:
                print(f"  Template {form.get('template_id')}")
                for field in form.get("values") or []:
                    print(f"    {field.get('key')}: {field.get('value')}")
    else:
        print(f"Failed to get encounter section structured data: {response.status_code}")
        print(response.json())
    ```
  </Tab>

  <Tab title="TypeScript">
    ```typescript theme={"theme":{"light":"one-light","dark":"material-theme-darker"}}
    const encounterId = "<encounter_id>";
    const response = await fetch(
      `https://sdp.suki.ai/api/v1/ambient/encounter/${encounterId}/structured-data/section-structured-data`,
      {
        headers: {
          sdp_suki_token: "<sdp_suki_token>",
          sdp_provider_id: "<sdp_provider_id>",
        },
      }
    );

    if (response.ok) {
      const body = await response.json();
      // Values from the latest completed ambient session for this encounter
      (body.section_structured_values ?? []).forEach((section: any) => {
        console.log(`Section ${section.loinc_code}`);
        section.forms?.forEach((form: any) => {
          console.log(`  Template ${form.template_id}`);
          form.values?.forEach((field: any) => {
            console.log(`    ${field.key}: ${JSON.stringify(field.value ?? null)}`);
          });
        });
      });
    } else {
      const error = await response.json();
      console.error(`Failed to get encounter section structured data: ${response.status}`, error);
    }
    ```
  </Tab>
</Tabs>


## OpenAPI

````yaml GET /api/v1/ambient/encounter/{encounter_id}/structured-data/section-structured-data
openapi: 3.0.1
info:
  title: Suki Developer Platform
  description: >-
    REST and WebSocket APIs for the Suki Developer Platform. Authenticate with
    Login or Register to obtain a Suki access token, then integrate ambient
    clinical documentation, form filling, transcription, content rewrite, and
    reference metadata endpoints.
  contact: {}
  version: '1.0'
servers:
  - url: https://sdp.suki.ai
    description: >-
      Production base URL for Suki Developer Platform REST APIs. WebSocket
      endpoints use the same host with `wss://`.
security:
  - SukiTokenAuth: []
paths:
  /api/v1/ambient/encounter/{encounter_id}/structured-data/section-structured-data:
    get:
      tags:
        - /api/v1/ambient/encounter
      summary: Get encounter section structured data
      description: >-
        Returns Embedded Form results from the latest completed ambient session
        for the encounter, grouped by section LOINC. Results from earlier
        sessions on the same encounter are not merged in.
      parameters:
        - name: encounter_id
          in: path
          description: >-
            UUID for the patient encounter (visit). Use the `encounter_id` from
            session create or the UUID you assigned when grouping multiple
            sessions under one visit.
          required: true
          schema:
            type: string
        - $ref: '#/components/parameters/ProviderIdHeader'
      responses:
        '200':
          description: Request succeeded.
          content:
            application/json:
              schema:
                $ref: >-
                  #/components/schemas/controllers.EncounterSectionStructuredDataResponse
              example:
                section_structured_values:
                  - loinc_code: 10164-2
                    forms:
                      - template_id: hpi-mood-v1
                        values:
                          - id: slot-symptoms
                            key: symptoms
                            value:
                              - low mood
                              - poor sleep
                          - id: slot-duration
                            key: symptom_duration
                            value: in the last two weeks
                          - id: slot-onset
                            key: onset_date
                            value: null
        '400':
          description: Bad request. The request body or parameters failed validation.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/controllers.BadRequestError'
        '401':
          description: Unauthorized. The Suki access token is missing, expired, or invalid.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/controllers.AuthenticationError'
        '404':
          description: Not found. The session, encounter, or resource ID does not exist.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/controllers.NotFoundError'
        '500':
          description: Internal server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/controllers.InternalServerError'
      security:
        - SukiTokenAuth: []
      x-codeSamples:
        - lang: bash
          label: cURL
          source: |-
            curl --request GET \
              --url https://sdp.suki.ai/api/v1/ambient/encounter/<encounter_id>/structured-data/section-structured-data \
              --header 'sdp_suki_token: <sdp_suki_token>' \
              --header 'sdp_provider_id: <sdp_provider_id>'
components:
  parameters:
    ProviderIdHeader:
      name: sdp_provider_id
      in: header
      description: >-
        **Optional** for standard partners.


        **Required** for:


        - **Bearer authentication.** Use the same `provider_id` returned by the
        Login or Register API.

        - **Single Auth Token authentication.** Include the same `provider_id`
        on every request as `sdp_provider_id`.
      required: false
      schema:
        type: string
        example: provider-123
  schemas:
    controllers.EncounterSectionStructuredDataResponse:
      type: object
      description: >-
        Response body for the
        /encounter/{encounter_id}/structured-data/section-structured-data
        endpoint
      properties:
        section_structured_values:
          type: array
          description: >-
            Embedded Form results from the latest completed ambient session for
            the encounter, grouped by section LOINC.
          items:
            $ref: '#/components/schemas/controllers.SectionStructuredData'
    controllers.BadRequestError:
      description: Bad Request Response
      type: object
      properties:
        code:
          type: integer
          example: 400
        message:
          type: string
          example: invalid request
    controllers.AuthenticationError:
      description: Authentication Failure Response
      type: object
      properties:
        code:
          type: integer
          example: 401
        message:
          type: string
          example: invalid token
    controllers.NotFoundError:
      description: Not Found Response
      type: object
      properties:
        code:
          type: integer
          example: 404
        message:
          type: string
          example: not found
    controllers.InternalServerError:
      description: Internal Server Error Response
      type: object
      properties:
        code:
          type: integer
          example: 500
        message:
          type: string
          example: internal server error
    controllers.SectionStructuredData:
      type: object
      description: Embedded Form results for one note section.
      properties:
        loinc_code:
          type: string
          description: LOINC code of the note section you seeded.
          example: 10164-2
        forms:
          type: array
          description: One entry for each Embedded Form template filled on this section.
          items:
            $ref: '#/components/schemas/controllers.SectionStructuredDataForm'
    controllers.SectionStructuredDataForm:
      type: object
      description: Filled values for one Embedded Form template.
      properties:
        template_id:
          type: string
          description: The `template_id` you sent on the seed request.
          example: hpi-mood-v1
        values:
          type: array
          description: Filled values for the template fields.
          items:
            $ref: '#/components/schemas/controllers.SectionStructuredDataValue'
    controllers.SectionStructuredDataValue:
      type: object
      description: >-
        One filled field. Returns `id`, `key`, and `value` only. The seed
        `type`, `options`, and `context` are not returned.
      properties:
        id:
          type: string
          description: The field `id` you sent, if any.
          example: slot-duration
        key:
          type: string
          description: The field `key` you sent.
          example: symptom_duration
        value:
          description: >-
            The filled value. A string for `text` and `radio`, a list of strings
            for `multi_select`, or `null` when the visit did not support a
            value.
          example: in the last two weeks
  securitySchemes:
    SukiTokenAuth:
      type: apiKey
      in: header
      name: sdp_suki_token
      description: >-
        Suki access token (`suki_token`) from Login or Register. Expires after
        one hour.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.