> ## 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 Session Structured Data
> Retrieve structured clinical data from completed Ambient session
**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 ambient session.
Use this endpoint to get the cumulative structured data associated with the specified ambient session.
## 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 ` (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](/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
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_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 theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
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_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);
}
```
## OpenAPI
````yaml GET /api/v1/ambient/session/{ambient_session_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/session/{ambient_session_id}/structured-data:
get:
tags:
- /api/v1/ambient/session
summary: Get ambient session structured data
description: >-
Returns structured clinical data extracted from the ambient session,
including coded diagnoses and related fields when available.
parameters:
- name: ambient_session_id
in: path
description: >-
UUID for the ambient session. Use the `ambient_session_id` returned
from Create Ambient Session, or the UUID you supplied in that
request.
required: true
schema:
type: string
- $ref: '#/components/parameters/ProviderIdHeader'
responses:
'200':
description: Request succeeded.
content:
application/json:
schema:
$ref: '#/components/schemas/controllers.SessionStructuredDataResponse'
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/session//structured-data \
--header 'sdp_suki_token: ' \
--header 'sdp_provider_id: '
components:
parameters:
ProviderIdHeader:
name: sdp_provider_id
in: header
description: >-
**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`.
required: false
schema:
type: string
example: provider-123
schemas:
controllers.SessionStructuredDataResponse:
type: object
properties:
structured_data:
$ref: '#/components/schemas/controllers.StructuredData'
description: >-
Response body for the /session/{ambient_session_id}/structured-data
endpoint
controllers.BadRequestError:
description: Bad Request Response
type: object
properties:
code:
type: integer
example: 400
message:
type: string
example: invalid request
controllers.AuthenticationError:
description: Authentication Failure Response
type: object
properties:
code:
type: integer
example: 401
message:
type: string
example: invalid token
controllers.InternalServerError:
description: Internal Server Error Response
type: object
properties:
code:
type: integer
example: 500
message:
type: string
example: internal server error
controllers.StructuredData:
type: object
properties:
diagnoses:
$ref: '#/components/schemas/controllers.Diagnoses'
orders:
$ref: '#/components/schemas/controllers.Orders'
controllers.Diagnoses:
type: object
properties:
values:
description: list of diagnoses
type: array
items:
$ref: '#/components/schemas/controllers.DiagnosisResponse'
controllers.Orders:
type: object
properties:
medication_orders:
description: Medication orders structured data
allOf:
- $ref: '#/components/schemas/controllers.MedicationOrders'
controllers.DiagnosisResponse:
type: object
properties:
codes:
description: Codes associated with the diagnosis
type: array
items:
$ref: '#/components/schemas/controllers.Code'
diagnosis_note:
description: Diagnosis note
type: string
example: >-
The management of essential hypertension remains unchanged from
previous plans, as it was not the focus of today's visit.
laterality_indicator:
description: Laterality indicator
type: integer
example: 4
post_coord_lex_flag:
description: Post-coordination lexical flag
type: integer
example: 1
controllers.MedicationOrders:
type: object
properties:
partial_values:
description: >-
Medication Orders that are not submittable (Criteria decided based
on target_emr provided in EmrContext)
type: array
items:
$ref: '#/components/schemas/controllers.MedicationOrderResponse'
values:
description: >-
Emr Submittable medication Orders (Criteria decided based on
target_emr provided in EmrContext)
type: array
items:
$ref: '#/components/schemas/controllers.MedicationOrderResponse'
controllers.Code:
type: object
properties:
code:
description: Code value
type: string
example: '30422'
description:
description: Description of the code
type: string
example: Essential hypertension
type:
type: string
enum:
- UNSPECIFIED
- IMO
- ICD10
- SNOMED
example: IMO
controllers.MedicationOrderResponse:
type: object
properties:
dosage:
description: Amount per administration
allOf:
- $ref: '#/components/schemas/controllers.Dosage'
drug_name:
description: Full medication name
type: string
example: Acetaminophen 500mg Tab
duration_in_days:
description: Duration in days
type: integer
example: 7
end_date:
description: End date-time (RFC3339)
type: string
example: '2026-01-08T00:00:00Z'
format:
description: Physical dosage form
allOf:
- $ref: '#/components/schemas/controllers.Format'
frequency:
description: Administration frequency
allOf:
- $ref: '#/components/schemas/controllers.Frequency'
instructions:
description: Free-form instructions
type: string
example: Take with food
linked_diagnosis_codes:
description: Linked ICD10 diagnosis codes
type: array
items:
$ref: '#/components/schemas/controllers.LinkedDiagnosisCode'
medication_code:
description: Standardized medication code
allOf:
- $ref: '#/components/schemas/controllers.MedicationCode'
medication_timing:
description: Timing modifiers
allOf:
- $ref: '#/components/schemas/controllers.MedicationTiming'
number_of_refills:
description: Number of refills
type: integer
example: 3
quantity_dispensed:
description: Quantity dispensed
type: string
example: 1 box
route:
description: Administration route
allOf:
- $ref: '#/components/schemas/controllers.Route'
start_date:
description: Start date-time (RFC3339)
type: string
example: '2026-01-01T00:00:00Z'
status:
description: Order status
type: string
enum:
- ACTIVE
- DISCONTINUED
- REFILLED
example: ACTIVE
strength:
description: Medication strength/concentration
allOf:
- $ref: '#/components/schemas/controllers.Strength'
controllers.Dosage:
type: object
properties:
quantity:
description: (Optional) Dosage quantity
type: number
example: 1
raw_value:
description: (Optional) Raw dosage text
type: string
example: 1 tablet
unit:
description: (Optional) Dosage unit
type: string
example: TAB
controllers.Format:
type: object
properties:
raw_value:
description: (Optional) Raw medication form
type: string
example: Tablet
controllers.Frequency:
type: object
properties:
raw_value:
description: (Optional) Raw frequency text
type: string
example: once daily
structured_value:
description: (Optional) Frequency enum
type: string
example: ONE_A_DAY
controllers.LinkedDiagnosisCode:
type: object
properties:
code:
description: (*Required) Diagnosis code value
type: string
example: I10
type:
description: (*Required) Diagnosis coding system
type: string
example: ICD10
controllers.MedicationCode:
type: object
properties:
code:
description: (*Required) Medication code value
type: string
example: '860975'
type:
description: (*Required) Medication coding system
type: string
enum:
- RXCUI
- NDC
example: RXCUI
controllers.MedicationTiming:
type: object
properties:
raw_value:
description: (Optional) Raw timing text
type: string
example: morning
structured_value:
description: (Optional) Medication timing enum
type: string
example: IN_THE_MORNING
controllers.Route:
type: object
properties:
raw_value:
description: (Optional) Raw administration route
type: string
example: Oral
controllers.Strength:
type: object
properties:
raw_value:
description: (Optional) Raw strength value
type: string
example: 500mg
securitySchemes:
SukiTokenAuth:
type: apiKey
in: header
name: sdp_suki_token
description: >-
Suki access token (`suki_token`) from Login or Register. Expires after
one hour.
````