Get Ambient Encounter Structured Data

GET

api

ambient

encounter

{encounter_id}

structured-data

cURL

curl --request GET \
  --url https://sdp.suki.ai/api/v1/ambient/encounter/<encounter_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/encounter/{encounter_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/encounter/{encounter_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/encounter/{encounter_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/encounter/{encounter_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/encounter/{encounter_id}/structured-data")
  .header("sdp_suki_token", "<api-key>")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://sdp.suki.ai/api/v1/ambient/encounter/{encounter_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 encounter.

Use this endpoint to get the 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 ICD10, IMO, SNOMED (when available), and HCC codes in the codes array. HCC values are derived from the ICD-10-CM code using the CMS-HCC V28 model. The description for HCC entries uses the format CMS-HCC model category <code>. HCC codes are returned in structured data output only. Do not send them in session context. For a comparison of ICD-10 and HCC codes and how Suki returns them, refer to Diagnosis codes FAQs.

Code examples

Python
TypeScript

import requests

encounter_id = "123dfg-456dfg-789dfg-012dfg"
url = f"https://sdp.suki-stage.com/api/v1/ambient/encounter/{encounter_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("Encounter 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 []:
            print(f"Order (submittable): {order.get('drug_name')} - {order.get('status')}")
        for order in med_orders.get("partial_values") or []:
            print(f"Order (partial): {order.get('drug_name')} - {order.get('status')}")
else:
    print(f"Failed to get encounter structured data: {response.status_code}")
    print(response.json())

const encounterId = '123dfg-456dfg-789dfg-012dfg';
const response = await fetch(
  `https://sdp.suki-stage.com/api/v1/ambient/encounter/${encounterId}/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('Encounter 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) => {
      console.log(`Order (submittable): ${order.drug_name} - ${order.status}`);
    });
    (medOrders.partial_values || []).forEach((order: any) => {
      console.log(`Order (partial): ${order.drug_name} - ${order.status}`);
    });
  }
} else {
  const error = await response.json();
  console.error(`Failed to get encounter structured data: ${response.status}`, error);
}

Authorizations

sdp_suki_token

string

header

required

Suki access token for the authenticated provider. Obtain this by calling Login or Register with a valid partner_token. Pass the suki_token value from the JSON response as the sdp_suki_token header on REST requests and non-browser WebSocket upgrades. Browser WebSocket clients pass the token in Sec-WebSocket-Protocol instead. Tokens expire after one hour; call Login again to refresh.

Headers

sdp_provider_id

string

Optional - Stable identifier for the active provider. Omit for standard partners whose partner_token identifies the user. Required for Bearer partners and Single Auth Token authentication where multiple providers share one partner_token. Use the same provider_id you sent on Login or Register.

Example:

"provider-123"

Path Parameters

encounter_id

string

required

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.

Response

Request succeeded.

Response body for the /encounter/{encounter_id}/structured-data endpoint

structured_data

object

Show child attributes

Last modified on June 30, 2026

Get Ambient Session Structured Data

User Preferences API

⌘I

cURL

curl --request GET \
  --url https://sdp.suki.ai/api/v1/ambient/encounter/<encounter_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/encounter/{encounter_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/encounter/{encounter_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/encounter/{encounter_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/encounter/{encounter_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/encounter/{encounter_id}/structured-data")
  .header("sdp_suki_token", "<api-key>")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://sdp.suki.ai/api/v1/ambient/encounter/{encounter_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