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

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 July 23, 2026

Get Ambient Session Structured Data

List Encounter Notes

⌘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