Skip to main content
POST
AI-categorize uncategorized expenses

When to use

After bulk-importing expenses (OCR, supplier sync, e-Factura SPV) the category_id is often null. This endpoint sweeps every such row and assigns a category from the firm’s existing list — system defaults plus custom categories, merged. Existing categorizations are never overwritten. Call repeatedly until remaining = 0. Each call processes up to cap expenses (a server-side constant returned in the response), so a large backlog can be drained in controlled passes rather than a single long-running request.

Permissions

Requires write permission on expenses.

Request

integer
Optional cap on the number of expenses to process this call. The server enforces its own ceiling (BATCH_MAX_PER_CALL), so very large values are clamped silently. Omit for “process up to the server cap.”

Response

Driver pattern

Errors

  • 401 — missing / invalid bearer token
  • 403 — API key lacks write permission on expenses
  • 502 ai_unavailable — classifier call failed; safe to retry
  • 503 ai_not_configured — AI categorization is not enabled on this deployment

Authorizations

Authorization
string
header
required

Use your API key (sk_live_xxx or sk_test_xxx)

Body

application/json
max
integer

Optional override for the per-call cap. The server still enforces its own BATCH_MAX_PER_CALL ceiling, so very large values are silently clamped.

Response

Batch run summary

processed
integer

Expenses inspected this call.

categorized
integer

Expenses that received a category.

skipped
integer

Classifier declined to assign a category (low confidence or no match).

errors
integer

Per-row failures (logged server-side).

remaining
integer

Uncategorized expenses still in the queue. Call again until 0.

batch_size
integer

Expenses per classifier call (server constant).

cap
integer

Hard ceiling per invocation (server constant).