Create Form Filling Session

Create a Form filling session and obtain a session identifier for subsequent calls

POST /api/v1/form-filling/session/create

cURL

cURL

curl --request POST \
  --url https://sdp.suki.ai/api/v1/form-filling/session/create \
  --header 'Content-Type: application/json' \
  --header 'sdp_suki_token: <sdp_suki_token>' \
  --header 'sdp_provider_id: <sdp_provider_id>' \
  --data '{}'

201

{
  "ambient_session_id": "123dfg-456dfg-789dfg-012dfg"
}

Use this endpoint to create a Form filling session. Suki returns a Form filling ambient_session_id. Use that value for context, streaming, end, status, structured data, feedback, and related session operations. You can create a Form filling session with an empty request body. Suki generates ambient_session_id for you.

Add a field when you need the behavior it enables:

• ambient_session_id: Supply your own Form filling session ID (Must be a valid UUID). If you omit it, Suki generates one and returns it.
• correlation_id: Supply a client value for tracing or correlating the session in your own systems.

All fields are optional when creating a standalone Form filling session.

Both Form filling and the Ambient APIs use the field name ambient_session_id, but the values identify different sessions. Do not pass an Ambient API session ID here. Use only the Form filling ambient_session_id returned from this endpoint for Form filling REST calls and for /ws/stream.

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

from typing import Any, Optional, TypedDict, cast

import requests

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


class CreateFormFillingSessionRequest(TypedDict, total=False):
    ambient_session_id: str
    correlation_id: str


class CreateFormFillingSessionResponse(TypedDict):
    ambient_session_id: str


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 _post_json_expect(url: str, headers: dict[str, str], payload: dict[str, Any], expect_status: int) -> dict[str, Any]:
    r = requests.post(url, json=payload, 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 login_for_suki_token(partner_id: str, partner_token: str, *, provider_id: Optional[str] = None) -> str:
    """POST /api/v1/auth/login -> suki_token (HTTP 200)."""
    url = f"{BASE_URL}/api/v1/auth/login"
    body: dict[str, Any] = {"partner_id": partner_id, "partner_token": partner_token}
    if provider_id is not None:
        body["provider_id"] = provider_id
    data = _post_json_expect(url, {"Content-Type": "application/json"}, body, 200)
    token = data.get("suki_token")
    if not isinstance(token, str) or not token:
        raise ValueError(f"{url}: 200 response missing suki_token")
    return token


def create_form_filling_session(
    suki_token: str,
    body: Optional[CreateFormFillingSessionRequest] = None,
) -> CreateFormFillingSessionResponse:
    """POST /api/v1/form-filling/session/create (sdp_suki_token header required). HTTP 201."""
    url = f"{BASE_URL}/api/v1/form-filling/session/create"
    headers = {"sdp_suki_token": suki_token, "sdp_provider_id": "<sdp_provider_id>", "Content-Type": "application/json"}
    data = _post_json_expect(url, headers, dict(body or {}), 201)
    sid = data.get("ambient_session_id")
    if not isinstance(sid, str) or not sid:
        raise ValueError(f"{url}: 201 response missing ambient_session_id")
    return cast(CreateFormFillingSessionResponse, {"ambient_session_id": sid})


if __name__ == "__main__":
    try:
        token = login_for_suki_token("<partner_id>", "<partner_token>")
        session = create_form_filling_session(token, {})
        print(session["ambient_session_id"])
    except (ApiHttpError, ValueError) as e:
        print(e)

TypeScript

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

type AuthenticationRequest = {
  partner_id: string;
  partner_token: string;
  provider_id?: string;
};

type AuthenticationResponse = { suki_token: string };

type CreateFormFillingSessionRequest = {
  ambient_session_id?: string;
  correlation_id?: string;
};

type CreateFormFillingSessionResponse = { ambient_session_id: string };

/** POST helper: reads body once, checks status, returns parsed JSON object on success. */
async function postJsonExpect<T extends Record<string, unknown>>(
  url: string,
  init: RequestInit,
  expectStatus: number,
): Promise<T> {
  const res = await fetch(url, init);
  const text = await res.text();
  let data: unknown;
  try {
    data = text ? JSON.parse(text) : {};
  } catch {
    throw new Error(`HTTP ${res.status} ${url}: invalid JSON`);
  }
  if (res.status !== expectStatus) {
    const msg =
      data && typeof data === "object" && "message" in data
        ? String((data as { message?: string }).message)
        : text.slice(0, 500);
    throw new Error(`HTTP ${res.status} ${url}: ${msg || "(no body)"}`);
  }
  if (!data || typeof data !== "object") {
    throw new Error(`${url}: expected JSON object`);
  }
  return data as T;
}

async function loginForSukiToken(body: AuthenticationRequest): Promise<string> {
  const url = `${BASE_URL}/api/v1/auth/login`;
  const data = await postJsonExpect<AuthenticationResponse>(url, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify(body),
  }, 200);
  if (!data.suki_token) throw new Error(`${url}: missing suki_token`);
  return data.suki_token;
}

async function createFormFillingSession(
  sukiToken: string,
  body: CreateFormFillingSessionRequest = {},
): Promise<CreateFormFillingSessionResponse> {
  const url = `${BASE_URL}/api/v1/form-filling/session/create`;
  const data = await postJsonExpect<CreateFormFillingSessionResponse>(url, {
    method: "POST",
    headers: {
      sdp_suki_token: sukiToken, sdp_provider_id: "<sdp_provider_id>",
      "Content-Type": "application/json",
    },
    body: JSON.stringify(body),
  }, 201);
  if (!data.ambient_session_id) throw new Error(`${url}: missing ambient_session_id`);
  return data;
}

async function main(): Promise<void> {
  try {
    const token = await loginForSukiToken({
      partner_id: "<partner_id>",
      partner_token: "<partner_token>",
    });
    const session = await createFormFillingSession(token, {});
    console.log(session.ambient_session_id);
  } catch (e) {
    console.error(e instanceof Error ? e.message : e);
  }
}

void main();

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"

Body

application/json

Optional form-filling session ID and correlation metadata. Suki generates a form-filling session ID when omitted.

ambient_session_id · string

Optional - Form-filling session ID in UUID format. Suki generates one when omitted and returns it in the ambient_session_id response field. Do not pass an ambient clinical documentation session ID.

Example:

"123dfg-456dfg-789dfg-012dfg"

correlation_id · string

Optional - Client-supplied identifier for tracing or correlating requests.

Example:

"123dfg-456dfg-789dfg-012dfg"

Response

201

application/json

Resource created successfully.

New form-filling session ID returned after create.

ambient_session_id · string

Form-filling session ID for subsequent form-filling API calls. Despite the field name, this is not an ambient clinical documentation session ID.

Example:

"123dfg-456dfg-789dfg-012dfg"