Batch

The Batch endpoints let you upload multiple files in a single request and track their combined processing status. Each batch groups up to 50 files and provides a unified progress view — how many files have completed, failed, or are still processing.

Project ID requirement: For organization tokens, provide projectId as a form field (upload) or query parameter (list). For project tokens, projectId is inferred from the token automatically.

Batch Upload

POST /v1/openapi/batch/upload

Uploads multiple files at once and creates a batch record to track their processing. All files in the batch are queued for OCR using the same template (if provided).

Headers:

Header	Value	Required
`X-API-Key`	`ocr_your_api_key`	Yes
`Content-Type`	`multipart/form-data`	Yes

Request Body (multipart/form-data):

Field	Type	Required	Description
`files`	File[]	Yes	Files to upload. Maximum 50 files per request
`projectId`	string	Yes	Target project ID
`templateId`	string	No	Template to apply to all files in the batch
`name`	string	No	Batch name. Auto-generated (e.g., `Batch 2026-03-31`) if omitted
`metadata`	string	No	Additional metadata as a JSON string

Example Request:

curl -X POST "https://api.ocriva.com/v1/openapi/batch/upload" \
  -H "X-API-Key: ocr_your_api_key" \
  -F "files=@/path/to/invoice-001.pdf" \
  -F "files=@/path/to/invoice-002.pdf" \
  -F "files=@/path/to/invoice-003.pdf" \
  -F "projectId=68db4aa2967d9c03fa9b5e74" \
  -F "templateId=68db4bb3a67e9c04fb0c6f85" \
  -F "name=March 2026 Invoices"

Example Response (201 Created):

{
  "id": "68dd2ee6d89g1f27ge4c9h96",
  "name": "March 2026 Invoices",
  "projectId": "68db4aa2967d9c03fa9b5e74",
  "organizationId": "68da2880b45d7a01d90a3c51",
  "userId": "68da3991c56e8b02ea1b4d60",
  "templateId": "68db4bb3a67e9c04fb0c6f85",
  "templateName": "Invoice Template",
  "totalFiles": 3,
  "completedFiles": 0,
  "failedFiles": 0,
  "status": "processing",
  "uploadIds": [
    "68dd2ee6d89g1f27ge4c9h01",
    "68dd2ee6d89g1f27ge4c9h02",
    "68dd2ee6d89g1f27ge4c9h03"
  ],
  "processingHistoryIds": [
    "68dd2ff7e90h2g38hf5d0i07",
    "68dd2ff7e90h2g38hf5d0i08",
    "68dd2ff7e90h2g38hf5d0i09"
  ],
  "progress": 0,
  "createdAt": "2026-03-31T10:00:00.000Z",
  "updatedAt": "2026-03-31T10:00:00.000Z"
}

Common Errors:

Status	Cause
`400`	No files included, or `projectId` is missing
`401`	Token is invalid or `projectId` does not match the token scope

List Batches

GET /v1/openapi/batch

Returns a paginated list of batches for the specified project.

Headers:

Header	Value	Required
`X-API-Key`	`ocr_your_api_key`	Yes

Query Parameters:

Parameter	Type	Required	Description
`projectId`	string	Org token: Yes	Target project ID
`page`	number	No	Page number (default: `1`)
`limit`	number	No	Items per page (default: `20`)
`status`	string	No	Filter by status: `uploading`, `processing`, `completed`, `partially_failed`, `failed`

Example Request:

curl "https://api.ocriva.com/v1/openapi/batch?projectId=68db4aa2967d9c03fa9b5e74&status=completed&page=1&limit=20" \
  -H "X-API-Key: ocr_your_api_key"

Example Response (200 OK):

{
  "data": [
    {
      "id": "68dd2ee6d89g1f27ge4c9h96",
      "name": "March 2026 Invoices",
      "projectId": "68db4aa2967d9c03fa9b5e74",
      "organizationId": "68da2880b45d7a01d90a3c51",
      "userId": "68da3991c56e8b02ea1b4d60",
      "templateId": "68db4bb3a67e9c04fb0c6f85",
      "templateName": "Invoice Template",
      "totalFiles": 3,
      "completedFiles": 3,
      "failedFiles": 0,
      "status": "completed",
      "progress": 100,
      "createdAt": "2026-03-31T10:00:00.000Z",
      "updatedAt": "2026-03-31T10:02:30.000Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 8,
    "pages": 1
  }
}

Get Batch Details

GET /v1/openapi/batch/:batchId

Returns the full details for a single batch, including file counts and current progress percentage. Poll this endpoint to monitor batch completion.

The progress field is calculated as (completedFiles + failedFiles) / totalFiles * 100.

Path Parameters:

Parameter	Description
`batchId`	Batch ID

Headers:

Header	Value	Required
`X-API-Key`	`ocr_your_api_key`	Yes

Example Request:

curl "https://api.ocriva.com/v1/openapi/batch/68dd2ee6d89g1f27ge4c9h96" \
  -H "X-API-Key: ocr_your_api_key"

Example Response (200 OK):

{
  "id": "68dd2ee6d89g1f27ge4c9h96",
  "name": "March 2026 Invoices",
  "projectId": "68db4aa2967d9c03fa9b5e74",
  "organizationId": "68da2880b45d7a01d90a3c51",
  "userId": "68da3991c56e8b02ea1b4d60",
  "templateId": "68db4bb3a67e9c04fb0c6f85",
  "templateName": "Invoice Template",
  "totalFiles": 3,
  "completedFiles": 2,
  "failedFiles": 0,
  "status": "processing",
  "uploadIds": [
    "68dd2ee6d89g1f27ge4c9h01",
    "68dd2ee6d89g1f27ge4c9h02",
    "68dd2ee6d89g1f27ge4c9h03"
  ],
  "processingHistoryIds": [
    "68dd2ff7e90h2g38hf5d0i07",
    "68dd2ff7e90h2g38hf5d0i08",
    "68dd2ff7e90h2g38hf5d0i09"
  ],
  "progress": 66.67,
  "createdAt": "2026-03-31T10:00:00.000Z",
  "updatedAt": "2026-03-31T10:01:45.000Z"
}

Batch Status Values:

Status	Description
`uploading`	Files are still being uploaded
`processing`	Files are queued or being processed
`completed`	All files processed successfully
`partially_failed`	Some files completed, some failed
`failed`	All files failed to process

Common Errors:

Status	Cause
`401`	Batch does not belong to the token's organization
`404`	Batch not found

Export Batch Results

GET /v1/openapi/batch/:batchId/export

Downloads the combined processing results of all completed files in the batch as a single file. Only files with completed status are included in the export.

Path Parameters:

Parameter	Description
`batchId`	Batch ID

Headers:

Header	Value	Required
`X-API-Key`	`ocr_your_api_key`	Yes

Query Parameters:

Parameter	Type	Required	Description
`format`	string	Yes	Export format: `json`, `csv`, `text`, `xml`, `pdf`, `docx`

Example Request:

# Export all results as a single CSV file
curl "https://api.ocriva.com/v1/openapi/batch/68dd2ee6d89g1f27ge4c9h96/export?format=csv" \
  -H "X-API-Key: ocr_your_api_key" \
  -o "march-2026-invoices.csv"

The response is a file download. The filename is set automatically to batch-{batchId}-export.{extension} via the Content-Disposition header.

Supported Export Formats:

Format	Content-Type	File Extension
`json`	`application/json`	`.json`
`csv`	`text/csv`	`.csv`
`text`	`text/plain`	`.txt`
`xml`	`application/xml`	`.xml`
`pdf`	`application/pdf`	`.pdf`
`docx`	`application/vnd.openxmlformats-officedocument.wordprocessingml.document`	`.docx`

Common Errors:

Status	Cause
`400`	`format` parameter missing, or no completed results to export
`401`	Batch does not belong to the token's organization
`404`	Batch not found

Documents

Batch

Batch

Batch Upload

List Batches

Get Batch Details

Export Batch Results

Table of Contents