Create Form Filling Session

Use this endpoint to create a form-filling ambient session. Suki will return a from filling ambient session identifier (id) in response for subsequent calls. You must use the returned session identifier (id) to perform other operations for that session for example checking session status, retrieving structured data, submitting feedback, ending the session, and more.

Important:In the documentation, both the Form Filling session ID and the Suki Ambient API session ID are referred to as ambient_session_id. However, these are two different identifiers and should not be treated as the same value.

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, 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, "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)

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,
      "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();

Headers

sdp_suki_token

string

required

sdp_suki_token

Body

application/json

CreateFormFillingSessionRequest

Request body for /form-filling/session/create

ambient_session_id

string

Optional - Associate this form-filling session with an existing ambient session when applicable.

Example:

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

correlation_id

string

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

Example:

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

Response

Success Response

Response body for /form-filling/session/create

ambient_session_id

string

Form-filling session id for subsequent calls.

Example:

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

Documentation Index

​Code examples

Headers

Body

Response

Code examples