API Reference
API Reference
Compact endpoint reference for Klarefi API v1
Base URL examples use https://api.klarefi.com.
Endpoints
| Method | Path | Scope | Purpose |
|---|---|---|---|
| GET | /api/v1/health | None | Service health check |
| GET | /api/v1/me | cases:read | Identify the authenticated org |
| POST | /api/v1/sessions | intake:sessions:create | Create a hosted intake session |
| GET | /api/v1/cases/\{caseId\} | cases:read | Read current case state |
| GET | /api/v1/cases/\{caseId\}/events | cases:read | Poll intake events |
| GET | /api/v1/cases/\{caseId\}/package | cases:read | Read the decision-ready package |
| DELETE | /api/v1/documents/\{docId\} | privacy:erase | Erase a document and derived data |
| POST | /api/v1/webhooks/test | webhooks:test | Send a signed test delivery |
| POST | /api/v1/webhooks/deliveries/\{deliveryId\}/ack | webhooks:acknowledge | Acknowledge webhook handoff |
GET /api/v1/health
{
"status": "ok"
}GET /api/v1/me
{
"org_id": "org_abc123",
"environment": "test"
}POST /api/v1/sessions
{
"case_type_id": "motor_claim",
"idempotency_key": "session_claim_12345",
"external_case_id": "claim_12345",
"ttl_hours": 168,
"locale": "nl"
}{
"session_id": "550e8400-e29b-41d4-a716-446655440000",
"signed_url": "https://app.klarefi.com/s/550e8400...?token=...",
"expires_at": "2026-01-22T10:30:00.000Z",
"snippet": "<script>window.location.href=\"https://app.klarefi.com/s/...\";</script>",
"idempotent_replay": false
}GET /api/v1/cases/{caseId}
The case response follows the configured workflow projection. Unknown fields are allowed.
{
"case_id": "case_abc123",
"org_id": "org_xyz",
"status": "needs_review",
"features": {
"incident_date": {
"decision": { "decision": "keep", "selected_candidate_id": "cand_001" },
"candidates": [
{
"candidate_id": "cand_001",
"value_raw": "3 februari 2023",
"value_normalized": "2023-02-03",
"evidence_ids": ["ev_001"]
}
]
}
}
}GET /api/v1/cases/{caseId}/events
Query parameter: after_cursor, default 0.
{
"case_id": "case_abc123",
"events": [
{
"event_id": "evt_001",
"event_type": "document.processed",
"cursor": 1,
"created_at": "2026-01-15T10:30:00Z"
}
],
"next_cursor": 1
}GET /api/v1/cases/{caseId}/package
The package response is workflow-shaped and includes case_file_url.
{
"case_id": "case_abc123",
"case_file_url": "https://app.klarefi.com/case-file/case_abc123?token=..."
}DELETE /api/v1/documents/{docId}
Returns 200 when complete or 202 when another erasure batch remains.
{
"erasure_receipt": {
"doc_id": "doc_def456",
"audit_id": "audit_001",
"completed": true,
"deleted_evidence": 5,
"deleted_candidates": 3,
"deleted_document": true,
"timestamp": "2026-01-15T10:30:00.000Z"
}
}POST /api/v1/webhooks/test
{
"endpoint_url": "https://your-app.example.com/webhooks/klarefi",
"signing_secret": "whsec_your_signing_secret"
}{
"success": true,
"status_code": 200
}POST /api/v1/webhooks/deliveries/{deliveryId}/ack
{
"acknowledgement_id": "ack_claim_12345"
}{
"acknowledged": true,
"already_acknowledged": false,
"delivery_id": "whd_123"
}