Ocriva Logo

Documents

Batch Processing

Upload and process multiple documents at once with batch operations.

batchuploadprocessingbulk

Published: 4/1/2026

Batch Processing

What is Batch Processing

Batch processing lets you upload and process up to 50 files in a single operation. All files in a batch share the same template and project, so AI extracts data consistently across every document. You can track the entire group as one unit, then export combined results in your preferred format.

Key benefits:

  • Upload up to 50 files in one request instead of one at a time
  • All files share the same template for consistent extraction
  • Track progress as a group with a single progress indicator
  • Export combined results (JSON, CSV, PDF, DOCX, XML, HTML, Text)
  • Filter Processing History by batch for easy retrieval

NOTE

Credits are deducted per file, not per batch. A 50-file batch uses 50 credits. Check your organization's credit balance before submitting large batches.

Uploading a Batch

Via the Web Interface

  1. Navigate to the Upload page
  2. Select your Template and Project
  3. Drag and drop multiple files into the upload zone (up to 50 files)
  4. Optionally enter a Batch Name (e.g., "March 2026 Invoices")
  5. Click Upload Batch
  6. Monitor progress in Processing History

TIP

Name batches descriptively — for example "Invoice Batch March 2026" — so they are easy to find and filter in Processing History later.

Via API

Send a multipart/form-data POST request with all files and metadata in one call:

curl -X POST https://api.ocriva.com/batch/YOUR_ORG_ID/upload \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -F "files=@invoice1.pdf" \
  -F "files=@invoice2.pdf" \
  -F "files=@invoice3.pdf" \
  -F "projectId=YOUR_PROJECT_ID" \
  -F "templateId=YOUR_TEMPLATE_ID" \
  -F "name=March 2026 Invoices"

Response:

{
  "id": "batch_abc123",
  "name": "March 2026 Invoices",
  "totalFiles": 3,
  "completedFiles": 0,
  "failedFiles": 0,
  "status": "processing",
  "progress": 0,
  "createdAt": "2026-03-31T09:00:00.000Z"
}

WARNING

Maximum 50 files per batch. Requests with more than 50 files will be rejected with a 400 Bad Request error. Split large document sets into multiple batches.

Batch Status Lifecycle

A batch moves through the following statuses from creation to completion:

StatusDescription
uploadingFiles are being received and stored. The batch is not yet queued for AI processing.
processingFiles have been uploaded successfully. AI is actively extracting data from each document.
completedAll files processed successfully. Results are available for export.
partially_failedAt least one file succeeded and at least one failed. Successful results are available; failed files can be retried individually.
failedAll files in the batch failed to process. No results are available.

IMPORTANT

A failed file does not block the rest of the batch. Processing continues for all remaining files, and the batch reaches partially_failed rather than failed as long as at least one file succeeds.

Tracking Progress

Real-Time via WebSocket

Connect to the WebSocket service and listen for batch_progress_updated events. The payload includes live progress data:

{
  "batchId": "batch_abc123",
  "totalFiles": 10,
  "completedFiles": 7,
  "failedFiles": 1,
  "progress": 80,
  "status": "processing"
}

Progress percentage is calculated as:

progress = (completedFiles + failedFiles) / totalFiles * 100

Polling via API

If you are not using WebSockets, poll the batch detail endpoint:

curl https://api.ocriva.com/batch/YOUR_ORG_ID/BATCH_ID \
  -H "Authorization: Bearer YOUR_TOKEN"

Webhook Notifications

Configure webhooks to receive push notifications on batch events:

EventTriggered When
batch.uploadedAll files have been received and queued
batch.completedBatch reaches completed, partially_failed, or failed

See the Webhooks Guide for setup instructions.

Exporting Batch Results

Export the combined results of all completed files in a batch in one download.

Supported formats: JSON, CSV, PDF, DOCX, XML, HTML, Text

Via the Web Interface

  1. Open Processing History
  2. Filter by the batch you want
  3. Click the Export dropdown on the batch row
  4. Select your preferred format

Via API

curl -O "https://api.ocriva.com/batch/YOUR_ORG_ID/BATCH_ID/export?format=csv" \
  -H "Authorization: Bearer YOUR_TOKEN"

Replace csv with json, pdf, docx, xml, html, or text as needed.

Batch API Reference

MethodEndpointDescription
POST/batch/:orgId/uploadUpload a new batch (multipart form)
GET/batch/:orgIdList all batches with pagination and status filter
GET/batch/:orgId/:batchIdGet batch detail including progress
GET/batch/:orgId/:batchId/exportExport combined results (?format=json|csv|pdf|docx|xml|html|text)
DELETE/batch/:orgId/:batchIdSoft-delete a batch

Authentication: All endpoints require a Bearer token (Authorization: Bearer YOUR_TOKEN).

Path parameters:

  • :orgId — your organization ID
  • :batchId — the batch ID returned by the upload endpoint

Best Practices

  • Name batches descriptively. Use names like "Invoice Batch March 2026" or "Receipts Q1 2026" so they are easy to search in Processing History.
  • Use the same template for all files in a batch. Mixing document types in one batch produces inconsistent extraction results.
  • Check your credit balance before large batches. Credits are deducted per file. A 50-file batch consumes 50 credits immediately on upload.
  • Monitor failed files and retry individually. If a batch reaches partially_failed, view the failed files in Processing History and reprocess them one at a time.
  • Use webhooks for automation. Subscribe to batch.completed to trigger downstream workflows (database updates, notifications, further processing) without polling.
  • Batch naming falls back to auto-generated. If you omit the name field, the system generates "Batch YYYY-MM-DD HH:mm" using the upload timestamp. Always provide a name for production workflows.