API Reference
Sessions API
Create hosted intake sessions and redirect applicants to signed Klarefi intake URLs
Use sessions for Hosted Intake integrations where Klarefi owns the hosted applicant intake flow.
POST /api/v1/sessions
Required scope: intake:sessions:create
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",
"external_customer_id": "customer_456",
"trace_id": "trace_claim_12345",
"ttl_hours": 168,
"return_url": "https://claims.example.com/claim_12345",
"locale": "nl"
}'Request Body
| Field | Required | Description |
|---|---|---|
case_type_id | Yes | Case type configured in Klarefi |
idempotency_key | Yes | Retry-safe key, unless sent as a header |
ttl_hours | No | Link lifetime in hours, default 168 |
return_url | No | Destination after the applicant completes intake |
locale | No | BCP 47 locale hint for hosted intake |
external_case_id | No | Your source-system case identifier |
external_applicant_id | No | Your applicant identifier |
external_customer_id | No | Your customer or account identifier |
trace_id | No | Correlation ID included in events and reads |
Response
201 means a new session was created. 200 means an idempotent replay.
{
"session_id": "550e8400-e29b-41d4-a716-446655440000",
"signed_url": "https://app.klarefi.com/s/550e8400-e29b-41d4-a716-446655440000?token=...",
"expires_at": "2026-01-22T10:30:00.000Z",
"snippet": "<script>window.location.href=\"https://app.klarefi.com/s/...\";</script>",
"idempotent_replay": false
}Redirect the applicant to signed_url. Do not construct session URLs in the
browser.