OCR

Endpoints for submitting documents to the NetraOCRx engine. Single and Base64 uploads return results synchronously; bulk uploads are asynchronous.

Base path: /ocr

Property	Value
File types	PDF, PNG, JPG/JPEG, TIFF, BMP, WebP
Max single file	50 MB
Max bulk total	600 MB

---

Upload a document

POST /ocr/upload

Uploads a single file as multipart/form-data and returns the OCR result synchronously.

Parameters

Name	In	Type	Default	Description
file	form	file	—	The document to process (≤ 50 MB). Required.
template_id	query	string	—	Template for structured extraction (e.g. gl1 or a user template ID). Required.
enable_fraud_check	query	boolean	false	Run a background integrity check.

cURL

curl -X POST "https://netraocr.shivicx.com/api/v1/ocr/upload?template_id=gl1" \
  -u "ak_live_xxxxxxxx:sk_live_xxxxxxxx" \
  -F "file=@invoice.pdf"

Python

import requests

resp = requests.post(
    "https://netraocr.shivicx.com/api/v1/ocr/upload",
    auth=("ak_live_xxxxxxxx", "sk_live_xxxxxxxx"),
    params={"template_id": "gl1"},
    files={"file": open("invoice.pdf", "rb")},
)
resp.raise_for_status()
print(resp.json()["structured_data"])

Node.js

import fs from "node:fs";

const form = new FormData();
form.append("file", new Blob([fs.readFileSync("invoice.pdf")]), "invoice.pdf");
const auth = Buffer.from("ak_live_xxxxxxxx:sk_live_xxxxxxxx").toString("base64");

const res = await fetch(
  "https://netraocr.shivicx.com/api/v1/ocr/upload?template_id=gl1",
  { method: "POST", headers: { Authorization: `Basic ${auth}` }, body: form }
);
console.log((await res.json()).structured_data);

Response 200 OK

{
  "job_id": "8f3c1d2e-…",
  "filename": "invoice.pdf",
  "batch_id": null,
  "structured_data": {
    "invoice_number": "INV-1024",
    "vendor_name": "Acme Supplies",
    "total": "1180.00",
    "line_items": [
      { "description": "Widget A", "quantity": "10", "amount": "1000.00" }
    ]
  },
  "page_count": 1,
  "document_type": "invoice",
  "processing_time_ms": 2310,
  "fraud_check_enabled": false,
  "fraud_check_status": null,
  "coins_consumed": 3
}

See the full field reference.

---

Upload a Base64 document

POST /ocr/upload-base64

Same as /ocr/upload, but the file is sent as a Base64 string in a JSON body — convenient when multipart is awkward.

Request body

Field	Type	Required	Description
file_base64	string	Yes	Base64 file content. A data: URI prefix is accepted and stripped.
filename	string	Yes	Original filename incl. extension (e.g. invoice.pdf).
template_id	string	Yes	Template for structured extraction (e.g. gl1 or a user template ID).
enable_fraud_check	boolean	No	Defaults to false.
disabled_fraud_checks	string[]	No	Check IDs to skip during integrity analysis.

curl -X POST "https://netraocr.shivicx.com/api/v1/ocr/upload-base64" \
  -u "ak_live_xxxxxxxx:sk_live_xxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "file_base64": "JVBERi0xLjQ…",
    "filename": "invoice.pdf",
    "template_id": "gl1"
  }'

The response is identical to /ocr/upload.

---

Bulk processing

For folders of documents, use the two-step asynchronous flow.

Analyze files before a bulk upload

POST /ocr/bulk-analyze

Validates each file (type, size, page count) and returns an accurate cost estimate. It does not create jobs — call it first to show users exactly what will run.

Name	In	Type	Default	Description
files	form	file[]	—	Files to analyze. Required.
template_id	query	string	—	Template to validate against, including plan/page-limit overrides. Required.
page_count_only	query	boolean	false	Count pages without enforcing batch plan limits. Used by the console for single-upload cost checks.

curl -X POST "https://netraocr.shivicx.com/api/v1/ocr/bulk-analyze?template_id=gl1" \
  -u "ak_live_xxxxxxxx:sk_live_xxxxxxxx" \
  -F "files=@inv1.pdf" \
  -F "files=@inv2.pdf"

Response 200 OK

{
  "files": [
    { "filename": "inv1.pdf", "size": 184320, "ext": ".pdf", "pages": 2, "valid": true, "error": null },
    { "filename": "inv2.pdf", "size": 91022,  "ext": ".pdf", "pages": 1, "valid": true, "error": null }
  ],
  "total_files": 2,
  "valid_files": 2,
  "invalid_files": 0,
  "total_pages": 3,
  "total_size": 275342,
  "estimated_cost": 3,
  "base_cost_per_page": 1
}

Submit a bulk upload

POST /ocr/bulk-upload

Submits multiple files for asynchronous processing. Returns 202 Accepted with the created job/batch identifiers — processing happens in the background.

Name	In	Type	Default	Description
files	form	file[]	—	Documents to process. Required.
folder_name	query	string	—	Logical folder or batch name. Required.
template_id	query	string	—	Template for structured extraction. Required.
enable_fraud_check	query	boolean	false	Run document integrity checks for each file.

curl -X POST "https://netraocr.shivicx.com/api/v1/ocr/bulk-upload?folder_name=June%20invoices&template_id=gl1" \
  -u "ak_live_xxxxxxxx:sk_live_xxxxxxxx" \
  -F "files=@inv1.pdf" \
  -F "files=@inv2.pdf"

After submitting, poll the batch with Batches or poll each job and fetch results as jobs complete — see Jobs & Results.

---

Errors

Status	When
400	Invalid Base64, bad parameters
401 / 403	Auth failure / IP not allow-listed
402	Payment required
413	File exceeds the size limit
422	Validation error in the request body
429	Rate limit exceeded

See Errors and Rate Limits.