Get Ambient Session Structured Data

Retrieve structured clinical data from completed Ambient session

GET /api/v1/ambient/session/{ambient_session_id}/structured-data

cURL

cURL

curl --request GET \
  --url https://sdp.suki.ai/api/v1/ambient/session/<ambient_session_id>/structured-data \
  --header 'sdp_suki_token: <sdp_suki_token>' \
  --header 'sdp_provider_id: <sdp_provider_id>'

200

{
  "structured_data": {
    "diagnoses": {
      "values": [
        {
          "codes": [
            {
              "code": "30422",
              "description": "Essential hypertension",
              "type": "IMO"
            },
            {
              "code": "85",
              "description": "CMS-HCC model category 85",
              "type": "HCC"
            }
          ],
          "diagnosis_note": "The management of essential hypertension remains unchanged from previous plans, as it was not the focus of today's visit.",
          "laterality_indicator": 4,
          "post_coord_lex_flag": 1
        }
      ]
    },
    "orders": {
      "medication_orders": {
        "partial_values": [
          {
            "dosage": {
              "quantity": 1,
              "raw_value": "1 tablet",
              "unit": "TAB"
            },
            "drug_name": "Acetaminophen 500mg Tab",
            "duration_in_days": 7,
            "end_date": "2026-01-08T00:00:00Z",
            "format": {
              "raw_value": "Tablet"
            },
            "frequency": {
              "raw_value": "once daily",
              "structured_value": "ONE_A_DAY"
            },
            "instructions": "Take with food",
            "linked_diagnosis_codes": [
              {
                "code": "I10",
                "type": "ICD10"
              }
            ],
            "medication_code": {
              "code": "860975",
              "type": "RXCUI"
            },
            "medication_timing": {
              "raw_value": "morning",
              "structured_value": "IN_THE_MORNING"
            },
            "number_of_refills": 3,
            "quantity_dispensed": "1 box",
            "route": {
              "raw_value": "Oral"
            },
            "start_date": "2026-01-01T00:00:00Z",
            "status": "ACTIVE",
            "strength": {
              "raw_value": "500mg"
            }
          }
        ],
        "values": [
          {
            "dosage": {
              "quantity": 1,
              "raw_value": "1 tablet",
              "unit": "TAB"
            },
            "drug_name": "Acetaminophen 500mg Tab",
            "duration_in_days": 7,
            "end_date": "2026-01-08T00:00:00Z",
            "format": {
              "raw_value": "Tablet"
            },
            "frequency": {
              "raw_value": "once daily",
              "structured_value": "ONE_A_DAY"
            },
            "instructions": "Take with food",
            "linked_diagnosis_codes": [
              {
                "code": "I10",
                "type": "ICD10"
              }
            ],
            "medication_code": {
              "code": "860975",
              "type": "RXCUI"
            },
            "medication_timing": {
              "raw_value": "morning",
              "structured_value": "IN_THE_MORNING"
            },
            "number_of_refills": 3,
            "quantity_dispensed": "1 box",
            "route": {
              "raw_value": "Oral"
            },
            "start_date": "2026-01-01T00:00:00Z",
            "status": "ACTIVE",
            "strength": {
              "raw_value": "500mg"
            }
          }
        ]
      }
    }
  }
}

Updated:

• Diagnosis output now includes HCC codes alongside ICD10, IMO, and SNOMED.
• You now get Medication orders in the structured data output for an ambient session.

Use this endpoint to get the cumulative structured data associated with the specified ambient session.

Retrieve diagnosis codes after Session status is completed. The codes are generated by then and do not change, so one request is enough.

Diagnosis codes in structured data

When Problem-Based Charting (PBC) is enabled, each diagnosis in structured_data.diagnoses.values includes a flat codes array:

{
  "codes": [
    {
      "type": "ICD10",
      "code": "E11.22",
      "description": "Type 2 diabetes mellitus with diabetic chronic kidney disease"
    },
    {
      "type": "HCC",
      "code": "18",
      "description": "Diabetes with chronic complications"
    }
  ]
}

Each code object contains type, code, and description. The array can also contain IMO and SNOMED entries.

Parse codes as an array. codes.values is not part of the partner contract.

Code types

Following are the code types Suki can return in the codes array:

type	Description
ICD10	ICD-10-CM diagnosis code
IMO	IMO term code
SNOMED	SNOMED CT code, when available
HCC	Hierarchical Condition Category, when a mapping exists for the diagnosis. Derived from the ICD-10-CM code.

• HCC entries use description in the format CMS-HCC model category <code>, such as CMS-HCC model category 65. HCC codes are returned only in structured data. Do not send HCC codes in session context.

• ICD-10 is not always returned. If your UI displays ICD chips, display them only when codes[] contains an entry with type set to ICD10. Continue to display diagnosis_note when codes are incomplete.

To load the generated note into a chart, refer to Load the note. For more information about ICD-10 and HCC codes, see Diagnosis codes.

• An ICD-10-CM diagnosis may not have an HCC code if it does not map to an HCC model category.

• After an ambient session completes, use the session endpoint to retrieve its content. If a note spans multiple ambient sessions, use Note structured data.

• For the complete workflow, refer to Load the note guide.

Code examples

Python

import requests

ambient_session_id = "123dfg-456dfg-789dfg-012dfg"
url = f"https://sdp.suki-stage.com/api/v1/ambient/session/{ambient_session_id}/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:
    structured_data = response.json()
    print("Structured Data:")
    if "structured_data" in structured_data:
        diagnoses = structured_data["structured_data"].get("diagnoses", {})
        if "values" in diagnoses:
            for diagnosis in diagnoses["values"]:
                print(f"Diagnosis Note: {diagnosis.get('diagnosis_note')}")

                # Additional diagnosis fields
                if diagnosis.get('laterality_indicator') is not None:
                    print(f"Laterality Indicator: {diagnosis.get('laterality_indicator')}")
                if diagnosis.get('post_coord_lex_flag') is not None:
                    print(f"Post-coordination Lexical Flag: {diagnosis.get('post_coord_lex_flag')}")

                # Diagnosis codes (ICD10, IMO, SNOMED, HCC)
                for code in diagnosis.get("codes", []):
                    print(f"  Code: {code.get('code')}")
                    print(f"    Description: {code.get('description')}")
                    print(f"    Type: {code.get('type')}")

                hcc_codes = [c for c in diagnosis.get("codes", []) if c.get("type") == "HCC"]
                if hcc_codes:
                    print(f"  HCC categories: {', '.join(c['code'] for c in hcc_codes)}")
                print("---")

        orders = structured_data["structured_data"].get("orders", {})
        med_orders = orders.get("medication_orders") or {}
        for order in med_orders.get("values") or []:
            med_code = order.get("medication_code") or {}
            print(f"Order (submittable): {order.get('drug_name')} - {order.get('status')}")
            print(f"  Medication code: {med_code.get('code')} ({med_code.get('type')})")
            print("---")
        for order in med_orders.get("partial_values") or []:
            med_code = order.get("medication_code") or {}
            print(f"Order (partial): {order.get('drug_name')} - {order.get('status')}")
            print(f"  Medication code: {med_code.get('code')} ({med_code.get('type')})")
            print("---")
else:
    print(f"Failed to get structured data: {response.status_code}")
    print(response.json())

TypeScript

const ambientSessionId = '123dfg-456dfg-789dfg-012dfg';
const response = await fetch(
  `https://sdp.suki-stage.com/api/v1/ambient/session/${ambientSessionId}/structured-data`,
  {
    headers: {
      'sdp_suki_token': '<sdp_suki_token>',
      'sdp_provider_id': '<sdp_provider_id>'
    }
  }
);

if (response.ok) {
  const structuredData = await response.json();
  console.log('Structured Data:');
  if (structuredData.structured_data) {
    const diagnoses = structuredData.structured_data.diagnoses || {};
    if (diagnoses.values) {
      diagnoses.values.forEach((diagnosis: any) => {
        console.log(`Diagnosis Note: ${diagnosis.diagnosis_note}`);

        // Additional diagnosis fields
        if (diagnosis.laterality_indicator !== undefined && diagnosis.laterality_indicator !== null) {
          console.log(`Laterality Indicator: ${diagnosis.laterality_indicator}`);
        }
        if (diagnosis.post_coord_lex_flag !== undefined && diagnosis.post_coord_lex_flag !== null) {
          console.log(`Post-coordination Lexical Flag: ${diagnosis.post_coord_lex_flag}`);
        }

        // Diagnosis codes (ICD10, IMO, SNOMED, HCC)
        diagnosis.codes?.forEach((code: any) => {
          console.log(`  Code: ${code.code}`);
          console.log(`    Description: ${code.description}`);
          console.log(`    Type: ${code.type}`);
        });

        const hccCodes = diagnosis.codes?.filter((code: any) => code.type === 'HCC') ?? [];
        if (hccCodes.length > 0) {
          console.log(`  HCC categories: ${hccCodes.map((c: any) => c.code).join(', ')}`);
        }
        console.log('---');
      });
    }

    const orders = structuredData.structured_data.orders || {};
    const medOrders = orders.medication_orders || {};
    (medOrders.values || []).forEach((order: any) => {
      const medCode = order.medication_code || {};
      console.log(`Order (submittable): ${order.drug_name} - ${order.status}`);
      console.log(`  Medication code: ${medCode.code} (${medCode.type})`);
      console.log('---');
    });
    (medOrders.partial_values || []).forEach((order: any) => {
      const medCode = order.medication_code || {};
      console.log(`Order (partial): ${order.drug_name} - ${order.status}`);
      console.log(`  Medication code: ${medCode.code} (${medCode.type})`);
      console.log('---');
    });
  }
} else {
  const error = await response.json();
  console.error(`Failed to get structured data: ${response.status}`, error);
}

Authorizations

sdp_suki_token · string · header · required

Suki access token (suki_token) from Login or Register. Expires after one hour.

Headers

sdp_provider_id · string

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.

Example:

"provider-123"

Path Parameters

ambient_session_id · string · required

UUID for the ambient session. Use the ambient_session_id returned from Create Ambient Session, or the UUID you supplied in that request.

Response

200

application/json

Request succeeded.

Response body for the /session/{ambient_session_id}/structured-data endpoint

structured_data · object

Show child attributes