API FAQs

Yes. Results can be downloaded programmatically through the API. Many users pipe results straight into S3, Google Cloud Storage, or on-premise systems via their own scripts or integration layers.

Yes. The API is designed for batching and automation. You can upload documents, poll for completion, and retrieve results programmatically. Many users process thousands of documents by queueing uploads and downloading results as each job finishes.

Direct integrations are not currently available, but you can use custom HTTP steps or scripts to interact with the API. Many users integrate the API into their workflow tools this way. If you want a fully supported integration, let us know—it's a common feature request.

Yes. All API processing is asynchronous. You upload a document, receive a job ID, and check the job status or wait for a webhook callback. This allows you to process large files or many files in parallel without blocking your application.

Yes. Every new account includes free trial credits that you can use to test the API with real documents. This lets you evaluate accuracy, integration workflows, and response formats before choosing a plan.

Yes. You can upload individual images one by one, or you can combine multiple images into a single multi-page PDF before uploading. Processing speed and accuracy are the same in both cases, so choose whichever format best fits your workflow.

Short answer: no — the API does not return confidence scores or bounding box coordinates.

This is a constraint of the AI-based approach we use, not a product decision.

Why

Traditional OCR engines work by segmenting the page into regions and recognising each region in isolation. That makes per-character bounding boxes and per-word confidence scores a natural by-product of how they operate. The AI models we use read the document holistically — they produce significantly higher accuracy on real handwriting, but they don't emit per-line or per-character coordinate data or numerical confidence values as part of that process.

What we do return

The JSON output includes the recognised text organised by page and line, plus document-level metadata (document ID, status, page count, timestamps). For exact JSON schema and example responses, see the API documentation.

If you need human-in-the-loop review

Common workarounds depending on your use case:

• Custom extractors — for forms, define the fields you want extracted and the API returns just those values, which you can then validate against your own business rules.
• Sample-based review — process documents in batches and route a percentage to human review rather than gating per-line.
• End-user verification — surface the transcribed text alongside the original image in your UI and let users confirm or correct it.

If you'd like to share more about your specific use case, we're happy to suggest the closest fit — and we track these requests for future product decisions.

Yes. The API supports text transcription, table extraction, and Custom Extractors, all of which return structured data in JSON. You can also retrieve tables and extractor outputs in CSV or XLSX formats through the dashboard.

At the moment we provide a well-documented REST API that works with any language or platform. Code examples are available for Python, JavaScript, cURL, and more. If you need help integrating the API into your preferred environment, our team is happy to assist.

Yes — webhooks let your system receive a callback the moment a job finishes, so you don't have to poll the status endpoint.

Configuring webhooks

You can set a webhook URL in two ways:

• Globally — visit Settings → Documents to set a default webhook URL for every job.
• Per request — pass a webhook_url parameter when submitting a job to override the default for that one request.

Verifying webhook calls

Every webhook call is signed with HMAC-SHA256 so your endpoint can verify it really came from Handwriting OCR. The signature is sent in a request header — your server should compute the expected HMAC using your shared secret and compare it to the header value before trusting the payload.

Webhooks are recommended over polling for any production integration — they're faster (no polling delay), cheaper on rate limits, and resilient to long-running jobs. Full payload format and verification examples are in the API documentation.

Authenticate every API request by including your token in the Authorization header as a Bearer token:

Authorization: Bearer YOUR_API_TOKEN

Generate a token

Visit Settings → API to generate, view, and revoke tokens. The API is available on all plans, including the free trial, so you can start integrating before you subscribe.

Common authentication errors

If you get a 401 Unauthorized response:

• Confirm the header reads Authorization: Bearer <token> (no extra quotes, the literal word Bearer, single space).
• Check the token hasn't been regenerated — old tokens stop working as soon as a new one is created.
• Make sure you're calling the API on the right host (https://api.handwritingocr.com/...).

For full request and response examples, see the API documentation.

After uploading a document, the API returns a job ID that you can use to query its status. You can check whether it is queued, processing, or complete, and then retrieve the results or download files once ready.

Yes. API uploads are capped at 20 MB per file. (Dashboard uploads have a higher 100 MB limit, useful when you're processing larger PDFs interactively.)

You can submit as many files as you like — there's no overall daily cap on submissions, only the per-file size limit. Documents with any number of pages are supported as long as they remain within 20 MB. For very large PDFs that exceed the limit, split into smaller files of ~100 pages and submit them as separate jobs.

API rate limits depend on your plan:

• Starter and Pro — 2 requests per second per account.
• Business — 5 requests per second per account.

These limits apply to job submissions and status checks. If you're working at very high sustained throughput, contact us — Business customers can negotiate higher dedicated limits as part of their plan.

If you hit the rate limit, the API responds with HTTP 429 Too Many Requests. Back off briefly and retry, or use webhooks instead of polling for job status to reduce request volume.

This usually means the API token is missing, malformed, or expired. Ensure you are including Authorization: Bearer YOUR_TOKEN exactly as specified. If you recently regenerated your token, make sure your application is using the new one. If the issue persists, regenerate the token again and update your workflow with the new value.