> ## 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 Note Structured Data

> Retrieve accumulated diagnoses and orders across Ambient sessions in a note

Use this endpoint to get accumulated <Tooltip tip="Machine-readable clinical facts extracted from conversations, such as diagnoses, medications, allergies, vitals, and related codes." cta="View in Glossary" href="/Glossary/s">structured data</Tooltip> (diagnoses and orders) across sessions in a note.

Use `composition_id` from [Create ambient session](/api-reference/ambient-sessions/create) as `note_id`.

<Note>
  This note-level endpoint accumulates diagnoses and orders across ambient sessions in the note.

  If you need the latest diagnoses and orders from the most recent session for that encounter ID, use the [Get ambient Encounter Structured Data](/api-reference/ambient-content/encounter-structured-data) endpoint.
</Note>

## Code examples

<Tabs>
  <Tab title="Python">
    ```python expandable theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
    import json
    import requests

    BASE_URL = "https://sdp.suki.ai"

    # Use composition_id from Create Ambient Session as note_id
    note_id = "<composition_id>"

    # Get sdp_suki_token from Login: POST /api/v1/auth/login
    sdp_suki_token = "<sdp_suki_token>"

    # Required for single_auth partners
    sdp_provider_id = "<sdp_provider_id>"

    url = f"{BASE_URL}/api/v1/ambient/note/{note_id}/structured-data"

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

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

    print("HTTP status:", response.status_code)

    try:
        response_body = response.json()
    except ValueError:
        print("Response was not JSON:")
        print(response.text)
        raise SystemExit(1)

    print("Response body:")
    print(json.dumps(response_body, indent=2))

    if response.status_code == 200:
        structured_data = response_body.get("structured_data") or {}

        diagnoses = (structured_data.get("diagnoses") or {}).get("values") or []
        print(f"Diagnoses found: {len(diagnoses)}")

        for diagnosis in diagnoses:
            print("diagnosis_note:", diagnosis.get("diagnosis_note"))
            print("laterality_indicator:", diagnosis.get("laterality_indicator"))
            print("post_coord_lex_flag:", diagnosis.get("post_coord_lex_flag"))

            for code in diagnosis.get("codes") or []:
                print("  code:", code.get("code"))
                print("  description:", code.get("description"))
                print("  type:", code.get("type"))
            print("---")

        medication_orders = (
            (structured_data.get("orders") or {}).get("medication_orders") or {}
        )
        submittable_orders = medication_orders.get("values") or []
        partial_orders = medication_orders.get("partial_values") or []

        print(f"Submittable medication orders: {len(submittable_orders)}")
        for order in submittable_orders:
            medication_code = order.get("medication_code") or {}
            print("drug_name:", order.get("drug_name"))
            print("status:", order.get("status"))
            print("medication_code:", medication_code.get("code"))
            print("medication_code_type:", medication_code.get("type"))
            print("---")

        print(f"Partial medication orders: {len(partial_orders)}")
        for order in partial_orders:
            medication_code = order.get("medication_code") or {}
            print("drug_name:", order.get("drug_name"))
            print("status:", order.get("status"))
            print("medication_code:", medication_code.get("code"))
            print("medication_code_type:", medication_code.get("type"))
            print("---")
    else:
        print("Get Note Structured Data failed.")
        if isinstance(response_body, dict):
            print("code:", response_body.get("code"))
            print("message:", response_body.get("message"))
    ```
  </Tab>

  <Tab title="TypeScript">
    ```typescript expandable theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
    const BASE_URL = "https://sdp.suki.ai";

    // Use composition_id from Create Ambient Session as note_id
    const noteId = "<composition_id>";

    // Get sdp_suki_token from Login: POST /api/v1/auth/login
    const sdpSukiToken = "<sdp_suki_token>";

    // Required for single_auth partners
    const sdpProviderId = "<sdp_provider_id>";

    type Code = {
      code?: string;
      description?: string;
      type?: string;
    };

    type Diagnosis = {
      diagnosis_note?: string;
      laterality_indicator?: number;
      post_coord_lex_flag?: number;
      codes?: Code[];
    };

    type MedicationCode = {
      code?: string;
      type?: string;
    };

    type MedicationOrder = {
      drug_name?: string;
      status?: string;
      medication_code?: MedicationCode;
    };

    type GetNoteStructuredDataResponse = {
      structured_data?: {
        diagnoses?: {
          values?: Diagnosis[];
        };
        orders?: {
          medication_orders?: {
            values?: MedicationOrder[];
            partial_values?: MedicationOrder[];
          };
        };
      };
    };

    type ApiErrorResponse = {
      code?: number;
      message?: string;
    };

    const response = await fetch(
      `${BASE_URL}/api/v1/ambient/note/${noteId}/structured-data`,
      {
        method: "GET",
        headers: {
          sdp_suki_token: sdpSukiToken,
          sdp_provider_id: sdpProviderId,
        },
      }
    );

    const responseText = await response.text();
    let responseBody: GetNoteStructuredDataResponse | ApiErrorResponse | unknown;

    try {
      responseBody = responseText ? JSON.parse(responseText) : {};
    } catch {
      console.error("Response was not JSON:");
      console.error(responseText);
      throw new Error("Get Note Structured Data returned non-JSON response");
    }

    console.log("HTTP status:", response.status);
    console.log("Response body:", JSON.stringify(responseBody, null, 2));

    if (response.status === 200) {
      const payload = responseBody as GetNoteStructuredDataResponse;
      const structuredData = payload.structured_data || {};

      const diagnoses = structuredData.diagnoses?.values || [];
      console.log(`Diagnoses found: ${diagnoses.length}`);

      for (const diagnosis of diagnoses) {
        console.log("diagnosis_note:", diagnosis.diagnosis_note);
        console.log("laterality_indicator:", diagnosis.laterality_indicator);
        console.log("post_coord_lex_flag:", diagnosis.post_coord_lex_flag);

        for (const code of diagnosis.codes || []) {
          console.log("  code:", code.code);
          console.log("  description:", code.description);
          console.log("  type:", code.type);
        }
        console.log("---");
      }

      const medicationOrders = structuredData.orders?.medication_orders || {};
      const submittableOrders = medicationOrders.values || [];
      const partialOrders = medicationOrders.partial_values || [];

      console.log(`Submittable medication orders: ${submittableOrders.length}`);
      for (const order of submittableOrders) {
        console.log("drug_name:", order.drug_name);
        console.log("status:", order.status);
        console.log("medication_code:", order.medication_code?.code);
        console.log("medication_code_type:", order.medication_code?.type);
        console.log("---");
      }

      console.log(`Partial medication orders: ${partialOrders.length}`);
      for (const order of partialOrders) {
        console.log("drug_name:", order.drug_name);
        console.log("status:", order.status);
        console.log("medication_code:", order.medication_code?.code);
        console.log("medication_code_type:", order.medication_code?.type);
        console.log("---");
      }
    } else {
      const error = responseBody as ApiErrorResponse;
      console.error("Get Note Structured Data failed.");
      console.error("code:", error.code);
      console.error("message:", error.message);
    }
    ```
  </Tab>
</Tabs>


## OpenAPI

````yaml GET /api/v1/ambient/note/{note_id}/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, 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/note/{note_id}/structured-data:
    get:
      tags:
        - /api/v1/ambient/note
      summary: Gets the structured data for a note.
      parameters:
        - $ref: '#/components/parameters/ProviderIdHeader'
        - name: note_id
          in: path
          required: true
          description: >-
            Note identifier. Use the `composition_id` returned from Ambient
            session create.
          schema:
            type: string
      responses:
        '200':
          description: Success Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/controllers.GetNoteStructuredDataResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/controllers.BadRequestError'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/controllers.AuthenticationError'
        '404':
          description: Not Found
          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: []
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.GetNoteStructuredDataResponse:
      description: Accumulated diagnoses and orders across sessions in the note.
      type: object
      properties:
        structured_data:
          description: Structured data (diagnoses, orders) sourced from the composition.
          allOf:
            - $ref: '#/components/schemas/controllers.StructuredData'
    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.StructuredData:
      type: object
      properties:
        diagnoses:
          $ref: '#/components/schemas/controllers.Diagnoses'
        orders:
          $ref: '#/components/schemas/controllers.Orders'
    controllers.Diagnoses:
      type: object
      properties:
        values:
          description: list of diagnoses
          type: array
          items:
            $ref: '#/components/schemas/controllers.DiagnosisResponse'
    controllers.Orders:
      type: object
      properties:
        medication_orders:
          description: Medication orders structured data
          allOf:
            - $ref: '#/components/schemas/controllers.MedicationOrders'
    controllers.DiagnosisResponse:
      type: object
      properties:
        codes:
          description: Codes associated with the diagnosis
          type: array
          items:
            $ref: '#/components/schemas/controllers.Code'
        diagnosis_note:
          description: Diagnosis note
          type: string
          example: >-
            The management of essential hypertension remains unchanged from
            previous plans, as it was not the focus of today's visit.
        laterality_indicator:
          description: Laterality indicator
          type: integer
          example: 4
        post_coord_lex_flag:
          description: Post-coordination lexical flag
          type: integer
          example: 1
    controllers.MedicationOrders:
      type: object
      properties:
        partial_values:
          description: >-
            Medication Orders that are not submittable (Criteria decided based
            on target_emr provided in EmrContext)
          type: array
          items:
            $ref: '#/components/schemas/controllers.MedicationOrderResponse'
        values:
          description: >-
            Emr Submittable medication Orders (Criteria decided based on
            target_emr provided in EmrContext)
          type: array
          items:
            $ref: '#/components/schemas/controllers.MedicationOrderResponse'
    controllers.Code:
      type: object
      properties:
        code:
          description: Code value
          type: string
          example: '30422'
        description:
          description: Description of the code
          type: string
          example: Essential hypertension
        type:
          type: string
          enum:
            - UNSPECIFIED
            - IMO
            - ICD10
            - SNOMED
          example: IMO
    controllers.MedicationOrderResponse:
      type: object
      properties:
        dosage:
          description: Amount per administration
          allOf:
            - $ref: '#/components/schemas/controllers.Dosage'
        drug_name:
          description: Full medication name
          type: string
          example: Acetaminophen 500mg Tab
        duration_in_days:
          description: Duration in days
          type: integer
          example: 7
        end_date:
          description: End date-time (RFC3339)
          type: string
          example: '2026-01-08T00:00:00Z'
        format:
          description: Physical dosage form
          allOf:
            - $ref: '#/components/schemas/controllers.Format'
        frequency:
          description: Administration frequency
          allOf:
            - $ref: '#/components/schemas/controllers.Frequency'
        instructions:
          description: Free-form instructions
          type: string
          example: Take with food
        linked_diagnosis_codes:
          description: Linked ICD10 diagnosis codes
          type: array
          items:
            $ref: '#/components/schemas/controllers.LinkedDiagnosisCode'
        medication_code:
          description: Standardized medication code
          allOf:
            - $ref: '#/components/schemas/controllers.MedicationCode'
        medication_timing:
          description: Timing modifiers
          allOf:
            - $ref: '#/components/schemas/controllers.MedicationTiming'
        number_of_refills:
          description: Number of refills
          type: integer
          example: 3
        quantity_dispensed:
          description: Quantity dispensed
          type: string
          example: 1 box
        route:
          description: Administration route
          allOf:
            - $ref: '#/components/schemas/controllers.Route'
        start_date:
          description: Start date-time (RFC3339)
          type: string
          example: '2026-01-01T00:00:00Z'
        status:
          description: Order status
          type: string
          enum:
            - ACTIVE
            - DISCONTINUED
            - REFILLED
          example: ACTIVE
        strength:
          description: Medication strength/concentration
          allOf:
            - $ref: '#/components/schemas/controllers.Strength'
    controllers.Dosage:
      type: object
      properties:
        quantity:
          description: (Optional) Dosage quantity
          type: number
          example: 1
        raw_value:
          description: (Optional) Raw dosage text
          type: string
          example: 1 tablet
        unit:
          description: (Optional) Dosage unit
          type: string
          example: TAB
    controllers.Format:
      type: object
      properties:
        raw_value:
          description: (Optional) Raw medication form
          type: string
          example: Tablet
    controllers.Frequency:
      type: object
      properties:
        raw_value:
          description: (Optional) Raw frequency text
          type: string
          example: once daily
        structured_value:
          description: (Optional) Frequency enum
          type: string
          example: ONE_A_DAY
    controllers.LinkedDiagnosisCode:
      type: object
      properties:
        code:
          description: (*Required) Diagnosis code value
          type: string
          example: I10
        type:
          description: (*Required) Diagnosis coding system
          type: string
          example: ICD10
    controllers.MedicationCode:
      type: object
      properties:
        code:
          description: (*Required) Medication code value
          type: string
          example: '860975'
        type:
          description: (*Required) Medication coding system
          type: string
          enum:
            - RXCUI
            - NDC
          example: RXCUI
    controllers.MedicationTiming:
      type: object
      properties:
        raw_value:
          description: (Optional) Raw timing text
          type: string
          example: morning
        structured_value:
          description: (Optional) Medication timing enum
          type: string
          example: IN_THE_MORNING
    controllers.Route:
      type: object
      properties:
        raw_value:
          description: (Optional) Raw administration route
          type: string
          example: Oral
    controllers.Strength:
      type: object
      properties:
        raw_value:
          description: (Optional) Raw strength value
          type: string
          example: 500mg
  securitySchemes:
    SukiTokenAuth:
      type: apiKey
      in: header
      name: sdp_suki_token
      description: >-
        Suki access token (`suki_token`) from Login or Register. Expires after
        one hour.

````