> ## 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 Ambient Encounter Structured Data
> Retrieve structured clinical data from completed encounter
**Updated:**
* Diagnosis output now includes [HCC codes](https://www.aapc.com/resources/what-is-hierarchical-condition-category?srsltid=AfmBOopcl-dIWrRrQFq58LGS72p58BakTdoWdEHv0P9z89c3XBXuJAOY) alongside ICD10, IMO, and SNOMED.
* You now get **Medication orders** in the structured data output for an encounter.
Use this endpoint to get the structured data associated with the specified encounter.
## 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 `.
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](/api-reference/faqs/diagnosis-codes#what-is-the-difference-between-icd-10-and-hcc-codes).
## Code examples
```python theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
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_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())
```
```typescript theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
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_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);
}
```
## OpenAPI
````yaml GET /api/v1/ambient/encounter/{encounter_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/encounter/{encounter_id}/structured-data:
get:
tags:
- /api/v1/ambient/encounter
summary: Get encounter structured data
description: >-
Returns structured clinical data aggregated across all ambient sessions
for the encounter. Use the `encounter_id` from session create.
parameters:
- name: encounter_id
in: path
description: >-
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.
required: true
schema:
type: string
- $ref: '#/components/parameters/ProviderIdHeader'
responses:
'200':
description: Request succeeded.
content:
application/json:
schema:
$ref: >-
#/components/schemas/controllers.EncounterStructuredDataResponse
example:
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
'400':
description: Bad request. The request body or parameters failed validation.
content:
application/json:
schema:
$ref: '#/components/schemas/controllers.BadRequestError'
'401':
description: Unauthorized. The Suki access token is missing, expired, or invalid.
content:
application/json:
schema:
$ref: '#/components/schemas/controllers.AuthenticationError'
'500':
description: Internal server error.
content:
application/json:
schema:
$ref: '#/components/schemas/controllers.InternalServerError'
security:
- SukiTokenAuth: []
x-codeSamples:
- lang: bash
label: cURL
source: |-
curl --request GET \
--url https://sdp.suki.ai/api/v1/ambient/encounter//structured-data \
--header 'sdp_suki_token: ' \
--header 'sdp_provider_id: '
components:
parameters:
ProviderIdHeader:
name: sdp_provider_id
in: header
description: >-
**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.
required: false
schema:
type: string
example: provider-123
schemas:
controllers.EncounterStructuredDataResponse:
type: object
properties:
structured_data:
$ref: '#/components/schemas/controllers.StructuredData'
description: Response body for the /encounter/{encounter_id}/structured-data endpoint
controllers.BadRequestError:
type: object
properties:
code:
type: integer
example: 400
description: HTTP status code for the error.
message:
type: string
example: invalid request
description: Human-readable description of the validation or request error.
description: Error response when the request fails validation.
controllers.AuthenticationError:
type: object
properties:
code:
type: integer
example: 401
description: HTTP status code for the error.
message:
type: string
example: invalid token
description: Human-readable description of the authentication failure.
description: Error response when authentication fails.
controllers.InternalServerError:
type: object
properties:
code:
type: integer
example: 500
description: HTTP status code for the error.
message:
type: string
example: internal server error
description: Human-readable description of the server error.
description: Error response when the server encounters an unexpected error.
controllers.StructuredData:
type: object
properties:
diagnoses:
$ref: '#/components/schemas/controllers.Diagnoses'
orders:
$ref: '#/components/schemas/controllers.Orders'
controllers.Diagnoses:
type: object
properties:
values:
type: array
description: list of diagnoses
items:
$ref: '#/components/schemas/controllers.DiagnosisResponse'
controllers.Orders:
type: object
properties:
medication_orders:
type: object
description: Medication orders structured data
allOf:
- $ref: '#/components/schemas/controllers.MedicationOrders'
controllers.DiagnosisResponse:
type: object
properties:
codes:
type: array
description: >-
Codes associated with the diagnosis. Structured data output includes
ICD10, IMO, SNOMED (when available), and HCC. HCC values are derived
from the ICD-10-CM code using the CMS-HCC V28 model.
items:
$ref: '#/components/schemas/controllers.Code'
diagnosis_note:
type: string
description: Diagnosis note
example: >-
The management of essential hypertension remains unchanged from
previous plans, as it was not the focus of today's visit.
laterality_indicator:
type: integer
description: Laterality indicator
example: 4
post_coord_lex_flag:
type: integer
description: Post-coordination lexical flag
example: 1
controllers.MedicationOrders:
type: object
properties:
partial_values:
type: array
description: >-
Medication Orders that are not submittable (Criteria decided based
on target_emr provided in EmrContext)
items:
$ref: '#/components/schemas/controllers.MedicationOrderResponse'
values:
type: array
description: >-
Emr Submittable medication Orders (Criteria decided based on
target_emr provided in EmrContext)
items:
$ref: '#/components/schemas/controllers.MedicationOrderResponse'
controllers.Code:
type: object
properties:
code:
type: string
description: Code value for the diagnosis or medication coding system.
example: '30422'
description:
type: string
description: >-
Description of the code. For HCC codes, the description uses the
format `CMS-HCC model category `.
example: Essential hypertension
type:
type: string
description: >-
Diagnosis coding system for this code value. HCC codes are returned
in ambient structured data output when the ICD-10-CM diagnosis maps
to a CMS-HCC model category (V28).
example: IMO
enum:
- UNSPECIFIED
- IMO
- ICD10
- SNOMED
- HCC
controllers.MedicationOrderResponse:
type: object
properties:
dosage:
type: object
description: Amount per administration
allOf:
- $ref: '#/components/schemas/controllers.Dosage'
drug_name:
type: string
description: Full medication name
example: Acetaminophen 500mg Tab
duration_in_days:
type: integer
description: Duration in days
example: 7
end_date:
type: string
description: End date-time (RFC3339)
example: '2026-01-08T00:00:00Z'
format:
type: object
description: Physical dosage form
allOf:
- $ref: '#/components/schemas/controllers.Format'
frequency:
type: object
description: Administration frequency
allOf:
- $ref: '#/components/schemas/controllers.Frequency'
instructions:
type: string
description: Free-form instructions
example: Take with food
linked_diagnosis_codes:
type: array
description: Linked ICD10 diagnosis codes
items:
$ref: '#/components/schemas/controllers.LinkedDiagnosisCode'
medication_code:
type: object
description: Standardized medication code
allOf:
- $ref: '#/components/schemas/controllers.MedicationCode'
medication_timing:
type: object
description: Timing modifiers
allOf:
- $ref: '#/components/schemas/controllers.MedicationTiming'
number_of_refills:
type: integer
description: Number of refills
example: 3
quantity_dispensed:
type: string
description: Quantity dispensed
example: 1 box
route:
type: object
description: Administration route
allOf:
- $ref: '#/components/schemas/controllers.Route'
start_date:
type: string
description: Start date-time (RFC3339)
example: '2026-01-01T00:00:00Z'
status:
type: string
description: Order status
enum:
- ACTIVE
- DISCONTINUED
- REFILLED
example: ACTIVE
strength:
type: object
description: Medication strength or concentration
allOf:
- $ref: '#/components/schemas/controllers.Strength'
controllers.Dosage:
type: object
properties:
quantity:
type: number
description: (Optional) Dosage quantity
example: 1
raw_value:
type: string
description: (Optional) Raw dosage text
example: 1 tablet
unit:
type: string
description: (Optional) Dosage unit
example: TAB
controllers.Format:
type: object
properties:
raw_value:
type: string
description: (Optional) Raw medication form
example: Tablet
controllers.Frequency:
type: object
properties:
raw_value:
type: string
description: (Optional) Raw frequency text
example: once daily
structured_value:
type: string
description: (Optional) Frequency enum
example: ONE_A_DAY
controllers.LinkedDiagnosisCode:
type: object
properties:
code:
type: string
description: (*Required) Diagnosis code value
example: I10
type:
type: string
description: (*Required) Diagnosis coding system
example: ICD10
controllers.MedicationCode:
type: object
properties:
code:
type: string
description: (*Required) Medication code value
example: '860975'
type:
type: string
description: (*Required) Medication coding system
enum:
- RXCUI
- NDC
example: RXCUI
controllers.MedicationTiming:
type: object
properties:
raw_value:
type: string
description: (Optional) Raw timing text
example: morning
structured_value:
type: string
description: (Optional) Medication timing enum
example: IN_THE_MORNING
controllers.Route:
type: object
properties:
raw_value:
type: string
description: (Optional) Raw administration route
example: Oral
controllers.Strength:
type: object
properties:
raw_value:
type: string
description: (Optional) Raw strength value
example: 500mg
securitySchemes:
SukiTokenAuth:
type: apiKey
in: header
name: sdp_suki_token
description: >-
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.
````