Get Note Structured Data

GET

api

ambient

note

{note_id}

structured-data

Gets the structured data for a note.

curl --request GET \
  --url https://sdp.suki.ai/api/v1/ambient/note/{note_id}/structured-data \
  --header 'sdp_suki_token: <api-key>'

import requests

url = "https://sdp.suki.ai/api/v1/ambient/note/{note_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/note/{note_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/note/{note_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/note/{note_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/note/{note_id}/structured-data")
  .header("sdp_suki_token", "<api-key>")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://sdp.suki.ai/api/v1/ambient/note/{note_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"
            }
          ],
          "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": 404,
  "message": "not found"
}

{
  "code": 500,
  "message": "internal server error"
}

Use this endpoint to get accumulated (diagnoses and orders) across sessions in a note. Use composition_id from Create ambient session as note_id.

This note-level endpoint accumulates diagnoses and orders across ambient sessions in the note.If you need the latest diagnoses and orders from the most recent session for that encounter ID, use the Get ambient Encounter Structured Data endpoint.

Code examples

Python
TypeScript

import json
import requests

BASE_URL = "https://sdp.suki.ai"

# Use composition_id from Create Ambient Session as note_id
note_id = "<composition_id>"

# Get sdp_suki_token from Login: POST /api/v1/auth/login
sdp_suki_token = "<sdp_suki_token>"

# Required for single_auth partners
sdp_provider_id = "<sdp_provider_id>"

url = f"{BASE_URL}/api/v1/ambient/note/{note_id}/structured-data"

headers = {
    "sdp_suki_token": sdp_suki_token,
    "sdp_provider_id": sdp_provider_id,
}

response = requests.get(url, headers=headers, timeout=60)

print("HTTP status:", response.status_code)

try:
    response_body = response.json()
except ValueError:
    print("Response was not JSON:")
    print(response.text)
    raise SystemExit(1)

print("Response body:")
print(json.dumps(response_body, indent=2))

if response.status_code == 200:
    structured_data = response_body.get("structured_data") or {}

    diagnoses = (structured_data.get("diagnoses") or {}).get("values") or []
    print(f"Diagnoses found: {len(diagnoses)}")

    for diagnosis in diagnoses:
        print("diagnosis_note:", diagnosis.get("diagnosis_note"))
        print("laterality_indicator:", diagnosis.get("laterality_indicator"))
        print("post_coord_lex_flag:", diagnosis.get("post_coord_lex_flag"))

        for code in diagnosis.get("codes") or []:
            print("  code:", code.get("code"))
            print("  description:", code.get("description"))
            print("  type:", code.get("type"))
        print("---")

    medication_orders = (
        (structured_data.get("orders") or {}).get("medication_orders") or {}
    )
    submittable_orders = medication_orders.get("values") or []
    partial_orders = medication_orders.get("partial_values") or []

    print(f"Submittable medication orders: {len(submittable_orders)}")
    for order in submittable_orders:
        medication_code = order.get("medication_code") or {}
        print("drug_name:", order.get("drug_name"))
        print("status:", order.get("status"))
        print("medication_code:", medication_code.get("code"))
        print("medication_code_type:", medication_code.get("type"))
        print("---")

    print(f"Partial medication orders: {len(partial_orders)}")
    for order in partial_orders:
        medication_code = order.get("medication_code") or {}
        print("drug_name:", order.get("drug_name"))
        print("status:", order.get("status"))
        print("medication_code:", medication_code.get("code"))
        print("medication_code_type:", medication_code.get("type"))
        print("---")
else:
    print("Get Note Structured Data failed.")
    if isinstance(response_body, dict):
        print("code:", response_body.get("code"))
        print("message:", response_body.get("message"))

const BASE_URL = "https://sdp.suki.ai";

// Use composition_id from Create Ambient Session as note_id
const noteId = "<composition_id>";

// Get sdp_suki_token from Login: POST /api/v1/auth/login
const sdpSukiToken = "<sdp_suki_token>";

// Required for single_auth partners
const sdpProviderId = "<sdp_provider_id>";

type Code = {
  code?: string;
  description?: string;
  type?: string;
};

type Diagnosis = {
  diagnosis_note?: string;
  laterality_indicator?: number;
  post_coord_lex_flag?: number;
  codes?: Code[];
};

type MedicationCode = {
  code?: string;
  type?: string;
};

type MedicationOrder = {
  drug_name?: string;
  status?: string;
  medication_code?: MedicationCode;
};

type GetNoteStructuredDataResponse = {
  structured_data?: {
    diagnoses?: {
      values?: Diagnosis[];
    };
    orders?: {
      medication_orders?: {
        values?: MedicationOrder[];
        partial_values?: MedicationOrder[];
      };
    };
  };
};

type ApiErrorResponse = {
  code?: number;
  message?: string;
};

const response = await fetch(
  `${BASE_URL}/api/v1/ambient/note/${noteId}/structured-data`,
  {
    method: "GET",
    headers: {
      sdp_suki_token: sdpSukiToken,
      sdp_provider_id: sdpProviderId,
    },
  }
);

const responseText = await response.text();
let responseBody: GetNoteStructuredDataResponse | ApiErrorResponse | unknown;

try {
  responseBody = responseText ? JSON.parse(responseText) : {};
} catch {
  console.error("Response was not JSON:");
  console.error(responseText);
  throw new Error("Get Note Structured Data returned non-JSON response");
}

console.log("HTTP status:", response.status);
console.log("Response body:", JSON.stringify(responseBody, null, 2));

if (response.status === 200) {
  const payload = responseBody as GetNoteStructuredDataResponse;
  const structuredData = payload.structured_data || {};

  const diagnoses = structuredData.diagnoses?.values || [];
  console.log(`Diagnoses found: ${diagnoses.length}`);

  for (const diagnosis of diagnoses) {
    console.log("diagnosis_note:", diagnosis.diagnosis_note);
    console.log("laterality_indicator:", diagnosis.laterality_indicator);
    console.log("post_coord_lex_flag:", diagnosis.post_coord_lex_flag);

    for (const code of diagnosis.codes || []) {
      console.log("  code:", code.code);
      console.log("  description:", code.description);
      console.log("  type:", code.type);
    }
    console.log("---");
  }

  const medicationOrders = structuredData.orders?.medication_orders || {};
  const submittableOrders = medicationOrders.values || [];
  const partialOrders = medicationOrders.partial_values || [];

  console.log(`Submittable medication orders: ${submittableOrders.length}`);
  for (const order of submittableOrders) {
    console.log("drug_name:", order.drug_name);
    console.log("status:", order.status);
    console.log("medication_code:", order.medication_code?.code);
    console.log("medication_code_type:", order.medication_code?.type);
    console.log("---");
  }

  console.log(`Partial medication orders: ${partialOrders.length}`);
  for (const order of partialOrders) {
    console.log("drug_name:", order.drug_name);
    console.log("status:", order.status);
    console.log("medication_code:", order.medication_code?.code);
    console.log("medication_code_type:", order.medication_code?.type);
    console.log("---");
  }
} else {
  const error = responseBody as ApiErrorResponse;
  console.error("Get Note Structured Data failed.");
  console.error("code:", error.code);
  console.error("message:", error.message);
}

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

note_id

string

required

Note identifier. Use the composition_id returned from Ambient session create.

Response

Success Response

Accumulated diagnoses and orders across sessions in the note.

structured_data

object

Structured data (diagnoses, orders) sourced from the composition.

Show child attributes

Last modified on July 23, 2026

Get Note Context

User Preferences API

⌘I

Gets the structured data for a note.

curl --request GET \
  --url https://sdp.suki.ai/api/v1/ambient/note/{note_id}/structured-data \
  --header 'sdp_suki_token: <api-key>'

import requests

url = "https://sdp.suki.ai/api/v1/ambient/note/{note_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/note/{note_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/note/{note_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/note/{note_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/note/{note_id}/structured-data")
  .header("sdp_suki_token", "<api-key>")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://sdp.suki.ai/api/v1/ambient/note/{note_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"
            }
          ],
          "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": 404,
  "message": "not found"
}

{
  "code": 500,
  "message": "internal server error"
}

​Code examples

Authorizations

Headers

Path Parameters

Response

Code examples