SDK reference

Web SDK

Load the script from sdk_url, then call KitaRisk.create(options).open(). For CSP, allow your Kita host in script-src, style-src, and frame-src.

Methods: open(), back(), exit(), and destroy() (call on unmount). An inline container needs at least 360 × 640 CSS pixels. To resume, create a new handle with the same session ID and a new client token. Verify outcomes from your server, not browser callbacks.

Server API

Send X-API-Key with your Risk Score key to the same base URL as the Scoring API: https://riskscore.kita.ai for kita_prod_ keys, https://sandbox-api.kita.ai for kita_sbx_ keys. Your organization path (/<org>/v1/risk/...) works too. Manage keys on the dashboard's API keys page, and allowed origins and your logo on its SDK page, which also lists recent runs. Never send an API key to a browser or mobile app.

Create a session

Send an Idempotency-Key header (up to 128 characters) per applicant. Repeating the same key and body returns the same session with a new client token; a different body returns 409 idempotency_conflict.

Returns 201 with session_id, client_token, expires_at, sdk_url, connect_url and environment.

Session status

collecting → queued → processing → completed, partial, or failed. Check each document's status and reason. Scores are included only with live scoring.

Python helper

Download kita_risk.py (standard library only).

import os
from kita_risk import KitaRisk
 
kita = KitaRisk(api_key=os.environ["KITA_API_KEY"], base_url=os.environ["KITA_BASE_URL"])
session = kita.create_session(reference_id="LOAN-2026-001", origin="https://app.example.com")
status = kita.status(session["session_id"])
# When the borrower returns:
token = kita.client_token(session["session_id"])

Webhooks

Kita turns on webhooks for your organization on request: send the HTTPS URL and we will share the signing secret. Events carry id, session_id, and a type: risk.session.completed, risk.session.partial, or risk.session.failed. They contain no scores; fetch results.

Verify Kita-Signature: t=TIMESTAMP,v1=DIGEST, where the digest is HMAC-SHA256 of TIMESTAMP.RAW_BODY with your webhook secret (or use KitaRisk.verify_webhook(secret, signature_header, raw_body)). Reject timestamps older than five minutes and deduplicate event IDs. Return 2xx after storing; failures retry up to six times.

iOS

Add the supplied KitaRisk Swift package and present KitaRiskViewController (iOS 15+). It runs in-app with the photo, Files and camera pickers.

import KitaRisk
 
let session = try KitaSession(
    id: response.sessionID,
    clientToken: response.clientToken,
    sdkOrigin: URL(string: "https://riskscore.kita.ai")!, // sandbox: https://sandbox-api.kita.ai
    appOrigin: URL(string: "https://app.example.com")!
)
let controller = KitaRiskViewController(session: session) { event in
    switch event {
    case .submitted, .exited:
        host.dismiss(animated: true)
    case .failed:
        // Offer retry with a fresh token from your backend.
        break
    }
}
host.present(controller, animated: true)

Add NSCameraUsageDescription to Info.plist. Both origins must be HTTPS, and appOrigin must match the session and an allowed origin. The callback confirms receipt only; fetch results on your server.

Android

Android has no drop-in screen yet: host the flow in your own WebView with the supplied capture Gradle module (Android 8+, Java 17, compile SDK 36).

1. Enable JavaScript and DOM storage, and allow navigation only to the SDK origin and your app origin.
2. Attach the bridge, then load a small host page under your app origin that loads {sdkOrigin}/sdk/v1/kita-risk.js and kita-risk.css and calls KitaRisk.create({ sessionId, clientToken, baseUrl: sdkOrigin, container: '#sdk' }).open().
3. Handle WebChromeClient.onShowFileChooser for photos and documents, and receive onSubmitted / onExit / onError through a message listener scoped to your app origin (WebViewCompat.addWebMessageListener).

String sdkOrigin = "https://riskscore.kita.ai"; // sandbox: https://sandbox-api.kita.ai
CaptureConfig config = new CaptureConfig(sdkOrigin, sessionId, clientToken, 702);
KitaCapture capture = new KitaCapture(activity, webView, config);
webView.loadDataWithBaseURL(appOrigin + "/", hostHtml, "text/html", "utf-8", null);
// Never put the server API key in the app.

Forward onActivityResult and onRequestPermissionsResult to the bridge, and call capture.close() when the host is destroyed. Call capture.setPhotoCaptureAvailable(true) only if your file chooser supports the camera. The SDK repository's Android sample is a complete host to start from.

Testing uploads

Use the SDK repository's iOS and Android samples and Maestro journeys; see docs/SDK_MOBILE_TESTING.md.

Errors

Errors contain error.code and error.request_id; include the request ID when contacting Kita.

Upload errors

Finished sessions may report per-file model_rejected, blank_document, extraction_error, or processing_timeout. These are analysis outcomes; the borrower still sees a receipt.

Limits