Financial document API
Upload bank statements, invoices and receipts from your software. Read the extracted data, review uncertain fields and download CSV, Excel or JSON.
The downloadable OpenAPI schema contains request fields, responses and permission requirements. The example uses a key from your environment and uploads only the file you choose.
Connect your workspace
In your workspace, open Settings → API keys. Create a key with only the permissions your integration needs. The workspace ID is the value after /app/ in that workspace’s URL. Send the key in the Authorization: Bearer header to https://rahunko.com/api/v1/workspaces/{workspaceId}.
Open RahunkoKeep the key on your server
The full key is shown only when you create it. Store it in a secret manager, never in browser code, URLs, screenshots or logs. Each key belongs to one workspace. Create a replacement before revoking an old key in Settings.
Download upload example
Run the downloaded example with Bun. Set RAHUNKO_API_KEY and RAHUNKO_WORKSPACE_ID in your environment. Use a key with documents:write and jobs:read. Exporting also requires exports:read. The example does not confirm a review for you.
bun upload-document.ts ./statement.pdfUpload the file
Create an upload with the file’s size, SHA-256 hash and batchId. Split the bytes using the returned partSize, then send each part to partsUrl/{partNumber}. Send its hash and an Idempotency-Key with every part. Call completeUrl after all parts arrive.
Start processing
Call uploadUrl/finalize once the upload is complete. Use the returned job ID to poll its status. Processing and review have separate states. A completed job can still contain fields that need checking.
Review and export
Read the job result or document. Use the review endpoints to check or correct values, then export the current revision. If the revision changes, fetch the latest result before trying again. Never mark a document reviewed automatically just to allow an export.
Limits and retries
A file can be up to 50 MiB. An upload expires after one hour. Use the returned part size and URLs, not a hardcoded split. Workspace processing quotas also apply. Reuse an Idempotency-Key only for the same upload request or part. On 429, respect Retry-After when present and retry with increasing delays.
Up to 300 requests per key and 600 per IP address in a 60-second window. Both limits apply. Exceeding either returns 429 with Retry-After.
Handle errors explicitly
400 or 422 means the input needs correction. 401 or 403 means access was denied. 404 means the resource is unavailable in this workspace. 409 means the state, revision or idempotency key conflicts. Do not retry these unchanged. A 5xx response may be temporary. Retry only when the operation can be safely repeated.
Exception: a job result with HTTP 409 and status=waiting is still processing. Continue polling the job status with a delay.
Webhooks
Callbacks currently require an endpoint provisioned by the Rahunko operator. The API registers its endpointId, not an arbitrary URL. Verify the signature over the exact body bytes and timestamp, reject stale deliveries and deduplicate event IDs. Until an endpoint is provisioned, poll the job status.
The x-rahunko-signature header is sha256= followed by a Base64 HMAC-SHA256 of timestamp.eventId.rawBody, using the provisioned secret. Read the event ID from x-rahunko-event-id and the Unix timestamp in seconds from x-rahunko-timestamp. Compare signatures in constant time before processing the body.
Endpoints
Generated from the versioned API contract. All endpoints require a workspace API key. Paths, fields and permission identifiers are the same in every language.
- List documents
GET /api/v1/workspaces/{workspaceId}/documents - Required permission:
documents:read - Read a document
GET /api/v1/workspaces/{workspaceId}/documents/{documentId} - Required permission:
documents:read - Delete a document
DELETE /api/v1/workspaces/{workspaceId}/documents/{documentId} - Required permission:
documents:write - Cancel processing
POST /api/v1/workspaces/{workspaceId}/documents/{documentId}/cancel - Required permission:
documents:write - Read source evidence
GET /api/v1/workspaces/{workspaceId}/documents/{documentId}/evidence - Required permission:
documents:read - Read a source page
GET /api/v1/workspaces/{workspaceId}/documents/{documentId}/evidence/pages/{pageNumber} - Required permission:
documents:read - Export a revision
GET /api/v1/workspaces/{workspaceId}/documents/{documentId}/export - Required permission:
exports:read - Read review fields
GET /api/v1/workspaces/{workspaceId}/documents/{documentId}/review - Required permission:
documents:read - Correct review fields
PATCH /api/v1/workspaces/{workspaceId}/documents/{documentId}/review - Required permission:
documents:write - Confirm a completed review
POST /api/v1/workspaces/{workspaceId}/documents/{documentId}/review/complete - Required permission:
documents:write - Read processing status
GET /api/v1/workspaces/{workspaceId}/jobs/{jobId} - Required permission:
jobs:read - Read the result and export links
GET /api/v1/workspaces/{workspaceId}/jobs/{jobId}/result - Required permission:
jobs:read - Read the processing quota
GET /api/v1/workspaces/{workspaceId}/quota - Required permission:
documents:read - Create an upload
POST /api/v1/workspaces/{workspaceId}/uploads - Required permission:
documents:write - Read upload progress
GET /api/v1/workspaces/{workspaceId}/uploads/{uploadId} - Required permission:
documents:write - Abort an upload
POST /api/v1/workspaces/{workspaceId}/uploads/{uploadId}/abort - Required permission:
documents:write - Complete the uploaded parts
POST /api/v1/workspaces/{workspaceId}/uploads/{uploadId}/complete - Required permission:
documents:write - Submit the file for processing
POST /api/v1/workspaces/{workspaceId}/uploads/{uploadId}/finalize - Required permission:
documents:write - Upload one part
PUT /api/v1/workspaces/{workspaceId}/uploads/{uploadId}/parts/{partNumber} - Required permission:
documents:write - List registered webhooks
GET /api/v1/workspaces/{workspaceId}/webhooks - Required permission:
webhooks:read - Register a provisioned webhook
POST /api/v1/workspaces/{workspaceId}/webhooks - Required permission:
webhooks:write - Disable a webhook
DELETE /api/v1/workspaces/{workspaceId}/webhooks/{endpointId} - Required permission:
webhooks:write