> ## 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** - 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.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:
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.
````