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

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

Request 

 1curl -X GET "https://www.handwritingocr.com/api/v2/documents" \
 2     -H "Authorization: Bearer your-api-token" \
 3     -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

Key Value Required Notes
Authorization Bearer your-api-token Yes
Accept application/json Yes

Request Parameters

Name Type Required Notes
per_page integer No Number of items per page. Default is 50. Maximum 200.
page integer No 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

Request 

 1curl -X GET "https://www.handwritingocr.com/api/v2/documents?page=1&per_page=100" \
 2     -H "Authorization: Bearer your-api-token" \
 3     -H "Accept: application/json"

Response 

 1{
 2    "current_page": 1,
 3    "data": [
 4        {
 5            "document_id": "xyz789",
 6            "status": "processed",
 7            "created_at": "2024-03-15T14:30:00Z",
 8            "updated_at": "2024-03-15T14:35:00Z",
 9            "automatically_deleted_at": "2024-03-22T14:30:00Z",
10            "page_count": 3,
11            "original_file_name": "business_report.pdf",
12            "action": "transcribe"
13        },
14        {
15            "document_id": "abc123",
16            "status": "queued",
17            "created_at": "2024-03-15T14:25:00Z",
18            "updated_at": "2024-03-15T14:25:00Z",
19            "automatically_deleted_at": "2024-03-22T14:25:00Z",
20            "page_count": 1,
21            "original_file_name": "receipt.jpg",
22            "action": "tables"
23        }
24    ],
25    "first_page_url": "https://www.handwritingocr.com/api/v2/documents?page=1",
26    "from": 1,
27    "last_page": 5,
28    "last_page_url": "https://www.handwritingocr.com/api/v2/documents?page=5",
29    "next_page_url": "https://www.handwritingocr.com/api/v2/documents?page=2",
30    "path": "https://www.handwritingocr.com/api/v2/documents",
31    "per_page": 50,
32    "prev_page_url": null,
33    "to": 50,
34    "total": 243
35}

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

Key Value Required Notes
Authorization Bearer your-api-token Yes
Accept application/json Yes
Content-Type multipart/form-data Yes

Request Parameters

Name Type Required Notes
file file Yes The document to process. Valid file types are PDF, JPG, PNG, TIFF, HEIC, GIF. Maximum file size is 20MB.
action string Yes The action to perform on the document. Valid values are transcribe to extract text, tables to extract tables, and extractor to apply a custom extractor.
delete_after integer No Seconds until auto-deletion. Overrides the auto-deletion period set in your user settings. Minimum is 300 seconds. Maximum is 1209600 seconds (14 days).
extractor_id string No A 10-character alphanumeric string e.g. Ks08XVPyMd. Create and test an extractor in the dashboard to get the extractor ID. Required when action is extractor.
prompt_id string No A 10-character alphanumeric string e.g. Ab08RsPyMd. For custom prompts. Requires Enterprise subscription.

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 - Rate limited.
500 Server Error - File storage or processing failed

Request 

 1curl -X POST "https://www.handwritingocr.com/api/v2/documents" \
 2     -H "Authorization: Bearer your-api-token" \
 3     -H "Accept: application/json" \
 4     -F "file=@/path/to/document.pdf" \
 5     -F "action=transcribe" \
 6     -F "delete_after=604800"

Response 

 1{
 2    "document_id": "abc123",
 3    "status": "queued"
 4}

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

Key Value Required Notes
Authorization Bearer your-api-token Yes
Accept application/json Yes

Path Parameters

Name Type Required Notes
document_id string Yes The document's unique identifier, example abcde12345..
format string No Output format. Varies by action: valid values are txt, docx, xlsx, csv, and json.

Response Codes

Code Explanation
200 Success - Returns document status (without format) or file (with format).
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.

Request 

 1curl -X GET "https://www.handwritingocr.com/api/v2/documents/abc123.txt" \
 2     -H "Authorization: Bearer your-api-token" \
 3     -H "Accept: application/json" \
 4     --output document.txt

Response 

 1{
 2    "id": "abc123",
 3    "status": "processed",
 4    "action": "transcribe",
 5    "created_at": "2024-03-15T14:30:00Z",
 6    "updated_at": "2024-03-15T14:35:00Z"
 7}

Delete document

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

Endpoint

DELETE /api/v2/documents/{document_id}

Headers

Key Value Required Notes
Authorization Bearer your-api-token Yes
Accept application/json Yes

Path Parameters

Name Type Required Notes
document_id string Yes 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.

Request 

 1curl -X DELETE "https://www.handwritingocr.com/api/v2/documents/abc123" \
 2     -H "Authorization: Bearer your-api-token" \
 3     -H "Accept: application/json"