Seed Form Filling Session Context

Use this endpoint to provide (seed) the for form-filling sessions. Providing detailed context helps Suki generate a more accurate and relevant .

The body of this request is optional. However, if you decide to provide context, you must provide valid values for the properties.

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

import requests

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


class FormFillingMetadata(TypedDict):
    form_template_id: str


class FormFillingContext(TypedDict):
    values: list[FormFillingMetadata]


class FormFillingSessionContext(TypedDict, total=False):
    # Optional, but if provided, `values` and `form_template_id` are required.
    form_filling: FormFillingContext


class ApiHttpError(RuntimeError):
    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,
) -> Optional[dict[str, Any]]:
    r = requests.post(url, json=payload, headers=headers, timeout=60)
    if r.status_code == expect_status:
        # OpenAPI does not define a response body for 200 here, so treat it as optional.
        if not r.text:
            return None
        try:
            data = r.json()
        except ValueError:
            return None
        return data if isinstance(data, dict) else None

    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:
    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
    r = requests.post(url, json=body, headers={"Content-Type": "application/json"}, timeout=60)
    if r.status_code != 200:
        raise ApiHttpError(r.status_code, url, (r.text or "")[:500] or "(no body)")
    data = r.json()
    token = data.get("suki_token") if isinstance(data, dict) else None
    if not isinstance(token, str) or not token:
        raise ValueError(f"{url}: 200 response missing suki_token")
    return token


def seed_form_filling_session_context(
    suki_token: str,
    ambient_session_id: str,
    body: Optional[FormFillingSessionContext] = None,
) -> None:
    url = f"{BASE_URL}/api/v1/form-filling/session/{ambient_session_id}/context"
    headers = {"sdp_suki_token": suki_token, "sdp_provider_id": "<sdp_provider_id>", "Content-Type": "application/json"}
    _post_json_expect(url, headers, dict(body or {}), 200)


if __name__ == "__main__":
    try:
        token = login_for_suki_token("<partner_id>", "<partner_token>")

        # Body is optional. Example shows one required form template ID inside `form_filling.values`.
        seed_form_filling_session_context(
            token,
            ambient_session_id="<ambient_session_id>",
            body={
                "form_filling": {
                    "values": [
                        {"form_template_id": "019d4cdc-9319-7d81-ae2e-fd6de7f1b4f0"},
                    ]
                }
            },
        )
        print("Context seeded.")
    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 FormFillingMetadata = { form_template_id: string };
type FormFillingContext = { values: FormFillingMetadata[] };
type FormFillingSessionContext = {
  // Optional, but if provided, `values` and `form_template_id` are required.
  form_filling?: FormFillingContext;
};

async function postJsonExpectOptional(
  url: string,
  init: RequestInit,
  expectStatus: number,
): Promise<{ json?: Record<string, unknown>; text?: string }> {
  const res = await fetch(url, init);
  const text = await res.text();

  if (res.status !== expectStatus) {
    let msg = text.slice(0, 500);
    try {
      const data: unknown = text ? JSON.parse(text) : null;
      if (data && typeof data === "object" && "message" in data) {
        msg = String((data as { message?: string }).message ?? msg);
      }
    } catch {
      // keep raw text
    }
    throw new Error(`HTTP ${res.status} ${url}: ${msg || "(no body)"}`);
  }

  // OpenAPI does not define a response body for 200 here, so treat it as optional.
  if (!text) return {};

  try {
    const data: unknown = JSON.parse(text);
    if (data && typeof data === "object") return { json: data as Record<string, unknown>, text };
    return { text };
  } catch {
    return { text };
  }
}

async function loginForSukiToken(body: AuthenticationRequest): Promise<string> {
  const url = `${BASE_URL}/api/v1/auth/login`;
  const { json } = await postJsonExpectOptional(
    url,
    {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify(body),
    },
    200,
  );

  const token = json?.suki_token;
  if (typeof token !== "string" || !token) throw new Error(`${url}: missing suki_token`);
  return token;
}

async function seedFormFillingSessionContext(
  sukiToken: string,
  ambientSessionId: string,
  body: FormFillingSessionContext = {},
): Promise<void> {
  const url = `${BASE_URL}/api/v1/form-filling/session/${ambientSessionId}/context`;
  await postJsonExpectOptional(
    url,
    {
      method: "POST",
      headers: {
        sdp_suki_token: sukiToken, sdp_provider_id: "<sdp_provider_id>",
        "Content-Type": "application/json",
      },
      body: JSON.stringify(body),
    },
    200,
  );
}

async function main(): Promise<void> {
  try {
    const token = await loginForSukiToken({
      partner_id: "<partner_id>",
      partner_token: "<partner_token>",
    });

    // Body is optional. Example shows one required form template ID inside `form_filling.values`.
    await seedFormFillingSessionContext(token, "<ambient_session_id>", {
      form_filling: {
        values: [{ form_template_id: "019d4cdc-9319-7d81-ae2e-fd6de7f1b4f0" }],
      },
    });

    console.log("Context seeded.");
  } catch (e) {
    console.error(e instanceof Error ? e.message : e);
  }
}

void main();

Headers

sdp_suki_token

string

required

sdp_suki_token

sdp_provider_id

string

Unique identifier for the provider. Optional for standard partners. Required for Single Auth Token authentication, where multiple providers share the same partner_token.

Example:

"provider-123"

Path Parameters

ambient_session_id

string

required

ambient_session_id

Body

application/json

FormFillingSessionContext

form_filling

object

Optional - Form template metadata for the session.

Show child attributes

Response

Success Response

The response is of type object.

​Code examples

Headers

Path Parameters

Body

Response

Code examples