Get Ambient Session Structured Data

GET

api

ambient

session

{ambient_session_id}

structured-data

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>'

import requests

url = "https://sdp.suki.ai/api/v1/ambient/session/{ambient_session_id}/structured-data"

headers = {"sdp_suki_token": "<api-key>"}

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

print(response.text)

const options = {method: 'GET', headers: {sdp_suki_token: '<api-key>'}};

fetch('https://sdp.suki.ai/api/v1/ambient/session/{ambient_session_id}/structured-data', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://sdp.suki.ai/api/v1/ambient/session/{ambient_session_id}/structured-data",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "sdp_suki_token: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://sdp.suki.ai/api/v1/ambient/session/{ambient_session_id}/structured-data"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("sdp_suki_token", "<api-key>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.get("https://sdp.suki.ai/api/v1/ambient/session/{ambient_session_id}/structured-data")
  .header("sdp_suki_token", "<api-key>")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://sdp.suki.ai/api/v1/ambient/session/{ambient_session_id}/structured-data")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["sdp_suki_token"] = '<api-key>'

response = http.request(request)
puts response.read_body

{
  "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"
            }
          }
        ]
      }
    }
  }
}

{
  "code": 400,
  "message": "invalid request"
}

{
  "code": 401,
  "message": "invalid token"
}

{
  "code": 500,
  "message": "internal server error"
}

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 associated with the specified .

Diagnosis codes in structured data

When Problem-Based Charting (PBC) is enabled, each diagnosis in structured_data.diagnoses.values can include multiple codes in the codes array:

`type`	Description
`ICD10`	ICD-10-CM diagnosis code
`IMO`	IMO term code
`SNOMED`	SNOMED CT code (when available)
`HCC`	CMS-HCC model category derived from the ICD-10-CM code.

HCC entries use description in the format CMS-HCC model category <code> (for example, CMS-HCC model category 65). HCC codes are returned in structured data output only. Do not send them in session context.

If an ICD-10-CM HCC diagnosis code does not map to an HCC model category, Suki looks for general HCC codes that match the diagnosis description. If no match is found, the diagnosis is returned without an HCC code.
For how ICD-10 and HCC codes differ and how Suki returns them, refer to Diagnosis codes FAQs.

Code examples

Python
TypeScript

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

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

Request succeeded.

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

structured_data

object

Show child attributes

Last modified on July 23, 2026

Get Ambient Encounter Content

Get Ambient Encounter Structured Data

⌘I

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>'

import requests

url = "https://sdp.suki.ai/api/v1/ambient/session/{ambient_session_id}/structured-data"

headers = {"sdp_suki_token": "<api-key>"}

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

print(response.text)

const options = {method: 'GET', headers: {sdp_suki_token: '<api-key>'}};

fetch('https://sdp.suki.ai/api/v1/ambient/session/{ambient_session_id}/structured-data', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://sdp.suki.ai/api/v1/ambient/session/{ambient_session_id}/structured-data",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "sdp_suki_token: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://sdp.suki.ai/api/v1/ambient/session/{ambient_session_id}/structured-data"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("sdp_suki_token", "<api-key>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.get("https://sdp.suki.ai/api/v1/ambient/session/{ambient_session_id}/structured-data")
  .header("sdp_suki_token", "<api-key>")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://sdp.suki.ai/api/v1/ambient/session/{ambient_session_id}/structured-data")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["sdp_suki_token"] = '<api-key>'

response = http.request(request)
puts response.read_body

{
  "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"
            }
          }
        ]
      }
    }
  }
}

{
  "code": 400,
  "message": "invalid request"
}

{
  "code": 401,
  "message": "invalid token"
}

{
  "code": 500,
  "message": "internal server error"
}

​Diagnosis codes in structured data

​Code examples

Authorizations

Headers

Path Parameters

Response

Diagnosis codes in structured data

Code examples