Introduction

Key Features

• Handwriting recognition and text extraction
• Table structure detection and data extraction
• Support for PDF and common image formats (JPG, PNG, TIFF, etc.)
• Multiple export formats (TXT, DOCX, JSON, CSV, XLSX)

Basic Process

1. Upload Document Start by uploading your document with a specified action:
   • transcribe: Extract all text from the document
   • tables: Extract data from tables
   • extractor: Extract structured data using a Custom Extractor.
2. Check Status After upload, your document enters the processing queue. Check its status using the document ID returned in step 1.
3. Download Results Once processing is complete, download the results in your preferred format:
   • Transcription: TXT, DOCX, or JSON
   • Tables: XLSX or JSON
   • Extractor: XLSX, CSV, or JSON.

Getting Started

• Create an account at handwritingocr.com
• Generate an API token in the dashboard
• For Custom Extractors, create and test an Extractor first.
• Test the API with a sample document
• Monitor results in the dashboard

Authentication

The API uses token-based authentication. Each request must include a valid API token in the Authorization header. API tokens provide full access to the document management API for a specific user account.

• Tokens are generated through the web interface at https://app.handwritingocr.com/settings?tab=api
• Tokens never expire but can be revoked or replaced at any time.
• Multiple active tokens are not supported
• Token permissions cannot be customized — each token has full access to all API endpoints

Authentication Header

Include your API token in all requests using the Bearer authentication scheme:

Authorization: Bearer your-api-token

Webhooks

Webhooks provide a more efficient and real-time alternative by automatically delivering the processed result in JSON format to a specified URL as soon as the document is ready, saving you bandwidth and reducing latency. You can set your webhook URL through the user dashboard, or for each request in the Upload Document endpoint documented below.

All webhooks are protected by HMAC-SHA256 signature verification. Each webhook request includes an X-Signature header containing a cryptographic signature that proves the request came from our servers and hasn’t been modified.

Go to the user dashboard to generate your webhook secret, or set a global webhook URL.

Rate Limits

To ensure fair usage, protect our services from abuse, and maintain high availability for all users, our API enforces rate limits. Familiarizing yourself with these limits will help you build robust and efficient integrations.

Standard Rate Limit

• Limit: We enforce a global rate limit of 2 requests per second (RPS).
• Scope: This limit is applied at the account level and is shared across all API endpoints. It is not a per-endpoint limit.

Detecting Rate Limits

When your application exceeds the rate limit, the API will respond with an:

• HTTP Status Code: 429 Too Many Requests

Rate Limit Headers

To help you manage your request volume and anticipate when limits might be reached, the API includes the following headers in its responses:

• X-RateLimit-Limit: The maximum number of requests allowed within the current time window.
• X-RateLimit-Remaining: The number of requests remaining in the current time window.
• Retry-After: Sent with a 429 Too Many Requests response, this header indicates the number of seconds your application should wait before attempting another request. It is crucial to respect this header to allow your connection to recover.

Best Practices for Managing Rate Limits

To operate efficiently within these limits, especially when processing multiple documents, we recommend the following best practices:

• Use the document list endpoint: For tasks like checking the status of multiple documents, utilize batch or list endpoints (such as a document list endpoint if available). This allows you to retrieve the status of many items in a single API call instead of polling each one individually.
• Process sequentially based on status: Only attempt to retrieve full results for a document (e.g., download) once its status has changed to “processed” (or your equivalent terminal status).
• Implement exponential backoff: When you receive a 429 status code, use the Retry-After header value to pause before retrying. If Retry-After is not present, or as a general error handling strategy, implement an exponential backoff mechanism for retries. This helps reduce pressure on the API during busy periods.
• Cache responses: Cache responses from the API where appropriate to avoid requesting the same data repeatedly.
• Utilize Webhooks: By setting up a webhook, our service will proactively send your results to your specified URL as soon as they are ready. This eliminates the need for you to poll for status updates or use the API to download your results, significantly reducing your API call volume.

Increasing Rate Limits

For users with consistently higher throughput requirements, we offer increased rate limits for Enterprise subscribers. These limits are determined on a case-by-case basis by negotiation.

If you anticipate needing a higher rate limit than the standard offering, please contact our support team to discuss your specific needs.

Support

For technical support or questions, contact our support team.