API Reference | SmartOCR

Authentication

Authenticate your API requests by including your secret API key in the x-api-key header. You can generate and manage your API keys in the developer dashboard.

x-api-key: ocr-tok_...123abc

Extract Custom Schema

Post/v1/extract

Upload a document (PDF or Image) and a JSON schema. The API will route the document to the optimal engine and return a strictly typed JSON object matching your schema.

Request Parameters (multipart/form-data)

fileRequired

binary (PDF, PNG, JPEG)

The document file to be parsed. Max size 5MB.

schemaRequired

string (JSON)

A stringified JSON object defining the exact keys and types you want extracted.

Async Extraction & Webhooks

Post/v1/extract-async

Submit large documents for asynchronous processing to prevent HTTP timeouts. Returns a jobId immediately. Once processing completes, the result is sent via POST to your configured Webhook URL.

Request Parameters

This endpoint accepts the same file and schema parameters as the standard extract endpoint, plus one additional optional parameter:

webhookUrlOptional

string (URL)

The URL where the final extracted JSON should be sent. If no default exists and this is omitted, the request returns a 400 Bad Request.

Dashboard Configuration

You do not need to send the webhook URL in every API request. You can easily set, edit, or remove your default Webhook URL at any time directly from the API Keys section in your SmartOCR dashboard. If a default is set on your dashboard API key, the API will automatically use it whenever you omit the webhookUrl parameter in your request body.

Initial Response (200 OK)

{
  "jobId": "uuid-string",
  "status": "PROCESSING",
  "message": "Document is processing in the background. Webhook will be sent upon completion."
}

The Webhook Payload

Our servers will fire a POST request to your resolved webhook URL when processing concludes.

Successful Processing

{
  "jobId": "uuid-string",
  "status": "COMPLETED",
  "data": {
    "extractedData": { ... }, 
    "confidenceScore": 95,
    "processedAt": "2026-06-29T12:00:00.000Z",
    "creditsRemaining": 98
  }
}

Failed Processing

{
  "jobId": "uuid-string",
  "status": "FAILED",
  "error": "Reason for failure (e.g., Timeout, Unreadable document)"
}

Fallback Polling Endpoint

Get/v1/job/:id

If your webhook server drops the payload or you prefer to poll manually, you can fetch the job status. Requires the x-api-key header.

{
  "jobId": "uuid-string",
  "status": "PROCESSING | COMPLETED | FAILED",
  "result": { ... },
  "createdAt": "2026-06-29T12:00:00.000Z",
  "completedAt": "2026-06-29T12:05:00.000Z"
}

File Integrity & Safety

To guarantee secure and reliable processing, the SmartOCR API performs strict real-time validation on all uploaded files before sending them to the inference engines.

Magic Byte Signature Verification

To prevent extension-spoofing attacks (e.g. renaming an executable to a .pdf), we verify file headers at the binary level. If the magic bytes do not match the declared MIME type, the request will fail with:

"Invalid [format] file signature. The file may be corrupted or renamed."

PDF Structural Integrity Check

All PDF uploads undergo deep structural analysis. If a PDF is corrupted, lacks a catalog, or has parsing anomalies, the API returns:

"Corrupted or invalid PDF file structure."

Encryption Detection

Password-protected, encrypted, or DRM-locked PDF documents cannot be processed. These will be rejected immediately with:

"Password protected PDFs are not supported."

Status Codes

SmartOCR uses standard HTTP response codes to indicate the success or failure of an API request.

200
OK
Successful extraction.
400
Bad Request
Invalid schema format, missing file, corrupted structures, spoofed file signatures, or password-protected PDFs.
401
Unauthorized
API key is missing, invalid, or inactive.
402
Payment Required
Out of credits. Top up required.
429
Too Many Requests
Rate limit exceeded (10 req/min for free, 100 for premium).
500
Server Error
All fallback providers failed to process the document.

curl -X POST https://api.smartocr.dev/v1/extract \
  -H "x-api-key: ocr-tok_...123abc" \
  -F "file=@/path/to/invoice.pdf" \
  -F 'schema={"invoiceNumber": "string", "totalDue": "number"}'

Response200 OK

{
  "extractedData": {
    "invoiceNumber": "INV-2847",
    "totalDue": 9782.00
  },
  "confidenceScore": 95,
  "processedAt": "2026-05-31T18:00:00.000Z",
  "creditsRemaining": 499
}