API Reference
API Quickstart
Create a hosted intake session, redirect an applicant, and read the resulting case
Canonical API base URL
Production integrations use
https://www.klarefi.com. A workspace-specific Convex HTTP URL shown in Settings → Developer remains valid for direct regional access.
Set your API key:
export KLAREFI_API_KEY="sk_test_..."
export KLAREFI_BASE_URL="https://www.klarefi.com"
export KLAREFI_API_BASE_URL="https://www.klarefi.com"@klarefi/node reads KLAREFI_BASE_URL. The CLI and curl examples use
KLAREFI_API_BASE_URL; set both to the dashboard value.
Install
npm install @klarefi/node
npx klarefi doctorHosted intake
Create a session when Klarefi should own the applicant-facing intake. Run this
from trusted server-side code, then redirect the applicant to signed_url.
import { Klarefi } from "@klarefi/node";
const klarefi = new Klarefi({
apiKey: process.env.KLAREFI_API_KEY!,
});
const session = await klarefi.sessions.create({
case_type_id: "motor_claim",
external_case_id: "claim_12345",
external_applicant_id: "applicant_789",
idempotency_key: "session_claim_12345",
ttl_hours: 168,
locale: "nl",
});
return Response.redirect(session.signed_url, 303);For a CLI smoke test:
npx klarefi sessions create \
--case-type motor_claim \
--external-case-id claim_12345 \
--external-applicant-id applicant_789 \
--url-onlyThe same request over HTTP:
curl -X POST "$KLAREFI_API_BASE_URL/api/v1/sessions" \
-H "Authorization: Bearer $KLAREFI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"case_type_id": "motor_claim",
"idempotency_key": "session_claim_12345",
"external_case_id": "claim_12345",
"external_applicant_id": "applicant_789",
"ttl_hours": 168,
"locale": "nl"
}'Example response:
{
"session_id": "550e8400-e29b-41d4-a716-446655440000",
"signed_url": "https://app.klarefi.com/s/550e8400-e29b-41d4-a716-446655440000?token=...",
"access_token": "1751879000.9f2c4e...",
"access_token_expires_at": "2026-01-22T10:30:00.000Z",
"expires_at": "2026-01-22T10:30:00.000Z",
"agent": {
"api_base": "https://your-deployment.convex.site/api/v1",
"manifest_url": "https://your-deployment.convex.site/api/v1/sessions/550e8400-e29b-41d4-a716-446655440000/manifest",
"access_token": "1751879000.9f2c4e..."
},
"snippet": "<script>window.location.href=\"https://app.klarefi.com/s/...\";</script>",
"idempotent_replay": false
}For v1 hosted sessions, the session ID is also the case ID used by case reads.
const caseFile = await klarefi.cases.retrieve(session.session_id);
const events = await klarefi.cases.events(session.session_id, {
afterCursor: 0,
limit: 100,
});
const pkg = await klarefi.cases.getPackage(session.session_id);CLI equivalents:
npx klarefi cases get 550e8400-e29b-41d4-a716-446655440000
npx klarefi cases events 550e8400-e29b-41d4-a716-446655440000 --after-cursor 0
npx klarefi cases package 550e8400-e29b-41d4-a716-446655440000