API documentation

The Handwriting OCR API provides a simple, reliable way to extract text and data from documents and images. Using state-of-the-art OCR technology, it can process handwritten text, printed documents, and structured data like tables. The API is RESTful, uses JSON for response data, and requires authentication via API tokens.

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, 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

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

Getting Started

You can find documentation for the previous version of our API here.

Support

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://www.handwritingocr.com/settings/api
  • Tokens never expire but can be revoked 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

Example request
curl -X GET "https://www.handwritingocr.com/api/v2/documents" \
     -H "Authorization: Bearer your-api-token" \
     -H "Accept: application/json"

List documents

Retrieves a paginated list of documents belonging to the authenticated user. Documents are sorted by creation date in descending order.

Endpoint

GET /api/v2/documents

Headers

Authorization: Bearer your-api-token

Required. Your API token, generated in your user dashboard.

Accept: application/json

Required.

Parameters

per_page integer

Number of items per page. Default is 50. Maximum 200.

page integer

The page number for pagination. Defaults to 1.

Response codes

Code Explanation
200 Success - Returns list of documents
401 Unauthorized - Invalid or missing API token
422 Validation Error - Invalid parameters
Example request
curl -X GET "https://www.handwritingocr.com/api/v2/documents?page=1&per_page=100" \
     -H "Authorization: Bearer your-api-token" \
     -H "Accept: application/json"
Example response
{
    "current_page": 1,
    "data": [
        {
            "document_id": "xyz789",
            "status": "processed",
            "created_at": "2024-03-15T14:30:00Z",
            "updated_at": "2024-03-15T14:35:00Z",
            "automatically_deleted_at": "2024-03-22T14:30:00Z",
            "page_count": 3,
            "original_file_name": "business_report.pdf",
            "action": "transcribe"
        },
        {
            "document_id": "abc123",
            "status": "queued",
            "created_at": "2024-03-15T14:25:00Z",
            "updated_at": "2024-03-15T14:25:00Z",
            "automatically_deleted_at": "2024-03-22T14:25:00Z",
            "page_count": 1,
            "original_file_name": "receipt.jpg",
            "action": "tables"
        }
    ],
    "first_page_url": "https://www.handwritingocr.com/api/v2/documents?page=1",
    "from": 1,
    "last_page": 5,
    "last_page_url": "https://www.handwritingocr.com/api/v2/documents?page=5",
    "next_page_url": "https://www.handwritingocr.com/api/v2/documents?page=2",
    "path": "https://www.handwritingocr.com/api/v2/documents",
    "per_page": 50,
    "prev_page_url": null,
    "to": 50,
    "total": 243
}

Upload Document

Upload a new document for processing. Supports PDF files and various image formats. The API will automatically check the page count of the submitted document against your credit balance before queueing for processing.

Endpoint

POST /api/v2/documents

Headers

Authorization: Bearer your-api-token

Required.

Accept: application/json

Required.

Content-Type: multipart/form-data

Required.

Parameters

file file

Required. The document to process. Valid file types are PDF, JPG, PNG, TIFF, HEIC, GIF. Maximum file size is 20MB.

action string

Required. The action to perform on the document. Valid values are transcribe to extract text, or tables to extract tables and key-value pairs.

delete_after integer

Seconds until auto-deletion. Overrides the auto-deletion period set in your user settings. Minimum is 300 seconds. Maximum is 1209600 seconds (14 days).

Response codes

Code Explanation
201 Success - Document created and queued for processing
400 Bad Request - Missing required fields
401 Unauthorized - Invalid or missing API token
403 Forbidden - Insufficient page credits
415 Unsupported Media Type
422 Validation Error - Invalid parameters
429 Too many requests
500 Server Error - File storage or processing failed
Example request
curl -X POST "https://www.handwritingocr.com/api/v2/documents" \
     -H "Authorization: Bearer your-api-token" \
     -H "Accept: application/json" \
     -F "file=@/path/to/document.pdf" \
     -F "action=transcribe" \
     -F "delete_after=604800"
Example response
{
    "document_id": "abc123",
    "status": "queued"
}

Download result

Retrieve the status of a document or download the processed results. The format extension is optional - if not provided, returns the document status in a JSON response. If the format extension is provided, downloads the processed document in the specified format.

Webhooks

We strongly encourage using a webhook instead of polling this endpoint repeatedly. 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 at https://www.handwritingocr.com/settings/documents

Endpoint

GET /api/v2/documents/{document_id}[.{format}]

Headers

Authorization: Bearer your-api-token

Required.

Accept: application/json

Required.

Path values

document_id

Required. The document's unique identifier.

format

Output format. Varies by action: valid values are txt, docx, xlsx, and json.

Response codes

Code Explanation
200 Success - Returns document status or file
202 Accepted - Document is still being processed
400 Bad Request - Invalid format for action type
401 Unauthorized - Invalid or missing API token
403 Forbidden - No permission to access document
404 Not Found - Document not found
500 Server Error - Error preparing file for download
Example request
curl -X GET "https://www.handwritingocr.com/api/v2/documents/abc123.txt" \
     -H "Authorization: Bearer your-api-token" \
     -H "Accept: application/json" \
     --output document.txt
Example response
{
    "id": "abc123",
    "status": "processed",
    "action": "transcribe",
    "created_at": "2024-03-15T14:30:00Z",
    "updated_at": "2024-03-15T14:35:00Z"
}

Delete document

Permanently delete a document and its associated files. This action cannot be undone.

Endpoint

DELETE /api/v2/documents/{document_id}

Headers

Authorization: Bearer your-api-token

Required.

Accept: application/json

Required.

Path values

document_id

Required. The document's unique identifier

Response codes

Code Explanation
204 Success - Document deleted
401 Unauthorized - Invalid or missing API token
403 Forbidden - No permission to delete document
404 Not Found - Document not found
500 Server Error - Error deleting document
Example request
curl -X DELETE "https://www.handwritingocr.com/api/v2/documents/abc123" \
     -H "Authorization: Bearer your-api-token" \
     -H "Accept: application/json"