API Reference
Processing API
Advanced pilot endpoint for direct document submission
Use the Processing API only when Klarefi has enabled direct document submission for your workspace. The default Klarefi integration is Hosted Intake.
This endpoint is useful for pilots where your product already owns the applicant-facing experience and Klarefi runs behind it to process documents, extract facts, and keep the case current.
POST /api/v1/process
Required scope: cases:process
curl -X POST "$KLAREFI_API_BASE_URL/api/v1/process" \
-H "Authorization: Bearer $KLAREFI_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: process_claim_12345_doc_1" \
-d '{
"document_url": "https://storage.example.com/claim-form.pdf",
"case_type_id": "motor_claim",
"external_case_id": "claim_12345",
"external_applicant_id": "applicant_789",
"external_customer_id": "customer_456",
"trace_id": "trace_claim_12345"
}'Request Body
| Field | Required | Description |
|---|---|---|
document_url | Yes | Public HTTPS URL for the document |
case_type_id | Yes | Case type configured in Klarefi |
idempotency_key | Yes | Retry-safe key, unless sent as a header |
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 |
Klarefi rejects non-HTTPS, loopback, private-network, and local document URLs.
Per-request webhook_url is not supported; configure registered webhook
endpoints in the dashboard.
Response
201 means a new case/document/job was queued. 200 means an idempotent
replay.
{
"case_id": "case_abc123",
"doc_id": "doc_def456",
"job_id": "job_ghi789",
"status": "queued",
"idempotent_replay": false
}