Create an Intake Session
Create a hosted intake session and hand the applicant a signed Klarefi intake URL
Overview
An intake session is the applicant-facing entry point for one case. Create a session when your system knows which workflow should run and who needs to submit answers or documents.
Inputs
A session creation request should include:
- Case type identifier from your Klarefi dashboard
- Applicant or case reference from your system
- Optional callback or return destination
- Optional locale and trace ID for support/debugging
Example Request
Install the SDK:
npm install @klarefi/nodeCreate the session from trusted server-side code:
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",
idempotency_key: "session_claim_48392",
external_case_id: "claim_48392",
external_applicant_id: "applicant_789",
return_url: "https://claims.example.com/claim_48392",
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_48392 \
--external-applicant-id applicant_789 \
--return-url https://claims.example.com/claim_48392 \
--url-onlyThe same request over HTTP:
POST /api/v1/sessions
Authorization: Bearer sk_live_your_api_key
Content-Type: application/json{
"case_type_id": "motor_claim",
"idempotency_key": "session_claim_48392",
"external_case_id": "claim_48392",
"external_applicant_id": "applicant_789",
"return_url": "https://claims.example.com/claim_48392",
"locale": "nl"
}The response contains signed_url, which can be opened by the applicant. Store
the Klarefi session_id alongside your own case identifier. In v1 hosted
sessions, the session_id is also the case ID used by case reads.
Operational Guidance
Create sessions from trusted server-side code. Do not build session URLs in the browser. Treat session links as scoped applicant access, and expire or revoke them when the case no longer needs applicant input.