Get Form Filling Structured Data

GET

api

form-filling

session

{ambient_session_id}

structured-data

cURL

curl --request GET \
  --url https://sdp.suki.ai/api/v1/form-filling/session/<ambient_session_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/form-filling/session/{ambient_session_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/form-filling/session/{ambient_session_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/form-filling/session/{ambient_session_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/form-filling/session/{ambient_session_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/form-filling/session/{ambient_session_id}/structured-data")
  .header("sdp_suki_token", "<api-key>")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://sdp.suki.ai/api/v1/form-filling/session/{ambient_session_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": {
    "generated_values": [
      {
        "correlation_id": "20965414-929a-4f71-a3e5-b92bec07d086",
        "created_at": "2026-01-01T00:00:00Z",
        "data": {
          "additionalProp1": {}
        },
        "form_template_id": "019d4cdc-9319-7d81-ae2e-fd6de7f1b4f0-template",
        "id": "019d4cdc-9319-7d81-ae2e-fd6de7f1b4f0",
        "metadata": {
          "additionalProp1": {}
        },
        "patient_id": "patient-123",
        "status": "MEDICAL_FORM_STATUS_COMPLETED",
        "title": "Adult Vitals",
        "type": "VITALS_ASSESSMENT"
      }
    ],
    "non_generated_values": [
      {
        "form_template_id": "019d4cdc-9319-7d81-ae2e-fd6de7f1b4f0"
      }
    ]
  }
}

{
  "code": 400,
  "message": "invalid request"
}

{
  "code": 401,
  "message": "invalid token"
}

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

Use this endpoint to get the cumulative associated with the specified . You receive the structured data in the response of this endpoint. The response contains the following fields:

generated_values: Form data with template IDs for which Suki was able to generate the structured data
non_generated_values: Form_Template_IDs for which Suki was not able to generate the structured data.

Code examples

The code examples below use placeholders and the stage host sdp.suki-stage.com only as examples. For credentials, base URLs, where to run Python or TypeScript, CORS, and cURL, refer to Using code examples in your integration in the API Reference Guidelines.

Python
TypeScript

from typing import Any, TypedDict, cast

import requests

BASE_URL = "https://sdp.suki-stage.com"


class MedicalFormInstanceSummary(TypedDict, total=False):
    form_template_id: str


class FormFillingStructuredData(TypedDict, total=False):
    generated_values: list[MedicalFormInstanceSummary]
    non_generated_values: list[MedicalFormInstanceSummary]


class FormFillingStructuredDataResponse(TypedDict):
    structured_data: FormFillingStructuredData


class ApiHttpError(RuntimeError):
    """Wrong HTTP status; OpenAPI errors usually include JSON with message + code."""

    def __init__(self, status: int, url: str, detail: str) -> None:
        super().__init__(f"HTTP {status} {url}: {detail}")
        self.status = status
        self.url = url


def _get_expect_json_object(url: str, headers: dict[str, str], expect_status: int) -> dict[str, Any]:
    r = requests.get(url, headers=headers, timeout=60)
    if r.status_code == expect_status:
        data = r.json()
        if isinstance(data, dict):
            return data
        raise ApiHttpError(expect_status, url, "response JSON was not an object")

    detail = ""
    try:
        err = r.json()
        if isinstance(err, dict) and isinstance(err.get("message"), str):
            detail = err["message"]
    except ValueError:
        detail = (r.text or "")[:500]
    raise ApiHttpError(r.status_code, url, detail or "(no body)")


def get_form_filling_structured_data(suki_token: str, ambient_session_id: str) -> FormFillingStructuredDataResponse:
    """GET /api/v1/form-filling/session/{ambient_session_id}/structured-data (sdp_suki_token header required). HTTP 200."""
    url = f"{BASE_URL}/api/v1/form-filling/session/{ambient_session_id}/structured-data"
    data = _get_expect_json_object(url, {"sdp_suki_token": suki_token, "sdp_provider_id": "<sdp_provider_id>"}, 200)
    sd = data.get("structured_data")
    if not isinstance(sd, dict):
        raise ValueError(f"{url}: 200 response missing structured_data object")
    return cast(FormFillingStructuredDataResponse, {"structured_data": sd})


if __name__ == "__main__":
    try:
        out = get_form_filling_structured_data("YOUR_SUKI_TOKEN", "YOUR_AMBIENT_SESSION_ID")
        print(out["structured_data"])
    except (ApiHttpError, ValueError) as e:
        print(e)

const BASE_URL = "https://sdp.suki-stage.com";

type MedicalFormInstanceSummary = {
  form_template_id?: string;
};

type FormFillingStructuredData = {
  generated_values?: MedicalFormInstanceSummary[];
  non_generated_values?: MedicalFormInstanceSummary[];
};

type FormFillingStructuredDataResponse = {
  structured_data: FormFillingStructuredData;
};

class ApiHttpError extends Error {
  status: number;
  url: string;
  constructor(status: number, url: string, detail: string) {
    super(`HTTP ${status} ${url}: ${detail}`);
    this.status = status;
    this.url = url;
  }
}

async function getExpectJsonObject(url: string, headers: Record<string, string>, expectStatus: number) {
  const res = await fetch(url, { method: "GET", headers });
  const text = await res.text();
  const json = text ? JSON.parse(text) : {};

  if (res.status !== expectStatus) {
    const msg = typeof (json as any)?.message === "string" ? (json as any).message : text?.slice(0, 500) || "(no body)";
    throw new ApiHttpError(res.status, url, msg);
  }
  if (json && typeof json === "object" && !Array.isArray(json)) return json as Record<string, unknown>;
  throw new ApiHttpError(res.status, url, "response JSON was not an object");
}

export async function getFormFillingStructuredData(
  sukiToken: string,
  ambientSessionId: string
): Promise<FormFillingStructuredDataResponse> {
  const url = `${BASE_URL}/api/v1/form-filling/session/${ambientSessionId}/structured-data`;
  const data = await getExpectJsonObject(url, { sdp_suki_token: sukiToken, sdp_provider_id: "<sdp_provider_id>" }, 200);
  const sd = data.structured_data;
  if (!sd || typeof sd !== "object" || Array.isArray(sd)) {
    throw new Error(`${url}: 200 response missing structured_data object`);
  }
  return { structured_data: sd as FormFillingStructuredData };
}

// Example usage
const out = await getFormFillingStructuredData("YOUR_SUKI_TOKEN", "YOUR_AMBIENT_SESSION_ID");
console.log(out.structured_data);

Authorizations

sdp_suki_token

string

header

required

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.

Headers

sdp_provider_id

string

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.

Example:

"provider-123"

Path Parameters

ambient_session_id

string

required

Form-filling session ID. The path parameter is named ambient_session_id, but this value identifies the form-filling session, not an ambient clinical documentation session. Use the ID returned from Create Form Filling Session, or the UUID you supplied in that request.

Response

Request succeeded.

Structured medical form output for a form-filling session.

structured_data

object

Medical form instances for a form-filling session (full generated values and sparse non-generated entries).

Show child attributes

Last modified on June 30, 2026

Get Form Filling Session Status

Get Form Filling Session Recording

⌘I

cURL

curl --request GET \
  --url https://sdp.suki.ai/api/v1/form-filling/session/<ambient_session_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/form-filling/session/{ambient_session_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/form-filling/session/{ambient_session_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/form-filling/session/{ambient_session_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/form-filling/session/{ambient_session_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/form-filling/session/{ambient_session_id}/structured-data")
  .header("sdp_suki_token", "<api-key>")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://sdp.suki.ai/api/v1/form-filling/session/{ambient_session_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": {
    "generated_values": [
      {
        "correlation_id": "20965414-929a-4f71-a3e5-b92bec07d086",
        "created_at": "2026-01-01T00:00:00Z",
        "data": {
          "additionalProp1": {}
        },
        "form_template_id": "019d4cdc-9319-7d81-ae2e-fd6de7f1b4f0-template",
        "id": "019d4cdc-9319-7d81-ae2e-fd6de7f1b4f0",
        "metadata": {
          "additionalProp1": {}
        },
        "patient_id": "patient-123",
        "status": "MEDICAL_FORM_STATUS_COMPLETED",
        "title": "Adult Vitals",
        "type": "VITALS_ASSESSMENT"
      }
    ],
    "non_generated_values": [
      {
        "form_template_id": "019d4cdc-9319-7d81-ae2e-fd6de7f1b4f0"
      }
    ]
  }
}

{
  "code": 400,
  "message": "invalid request"
}

{
  "code": 401,
  "message": "invalid token"
}

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

​Code examples

Authorizations

Headers

Path Parameters

Response

Code examples