Handwriting OCR API documentation

Postman collection → OpenAPI spec →

Introduction

This documentation aims to provide all the information you need to work with our API.

Authenticating requests

To authenticate requests, include an Authorization header with the value "Bearer {YOUR_AUTH_KEY}".

All authenticated endpoints are marked with a requires authentication badge in the documentation below.

You can enable API access and generate your token by visiting the settings page in the account dashboard.

Document Management

APIs for managing documents

List documents

GET
https://www.handwritingocr.com
/api/v1/documents
requires authentication

Get a paginated list of the authenticated user's documents.

Headers

Authorization
Example:
Bearer {YOUR_AUTH_KEY}
Content-Type
Example:
application/json
Accept
Example:
application/json

Query Parameters

page
integer

The page number. Default: 1

Example:
18
per_page
integer

The number of items per page. Default: 50

Example:
10

Body Parameters

Example request: 
curl --request GET \
    --get "https://www.handwritingocr.com/api/v1/documents?page=18&per_page=10" \
    --header "Authorization: Bearer {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --data "{
    \"per_page\": 2,
    \"page\": 62
}"
Example response:
{
    "current_page": 1,
    "data": [
        {
            "document_id": "abc123",
            "status": "processed",
            "created_at": "2023-05-01T12:00:00Z",
            "updated_at": "2023-05-01T12:30:00Z",
            "automatically_deleted_at": "2023-05-08T12:00:00Z",
            "page_count": 5,
            "original_file_name": "example.pdf",
            "action": "transcribe"
        }
    ],
    "first_page_url": "http://www.handwritingocr.com/api/v1/documents?page=1",
    "from": 1,
    "last_page": 1,
    "last_page_url": "http://www.handwritingocr.com/api/v1/documents?page=1",
    "links": [
        {
            "url": null,
            "label": "« Previous",
            "active": false
        },
        {
            "url": "http://www.handwritingocr.com/api/v1/documents?page=1",
            "label": "1",
            "active": true
        },
        {
            "url": null,
            "label": "Next »",
            "active": false
        }
    ],
    "next_page_url": null,
    "path": "http://www.handwritingocr.com/api/v1/documents",
    "per_page": 50,
    "prev_page_url": null,
    "to": 1,
    "total": 1
}

Get document details

GET
https://www.handwritingocr.com
/api/v1/documents/{hashid}
requires authentication

Retrieve details of a specific document.

Headers

Authorization
Example:
Bearer {YOUR_AUTH_KEY}
Content-Type
Example:
application/json
Accept
Example:
application/json

URL Parameters

hashid
string
required
Example:
voluptas
id
string
required

The document's id.

Example:
sapiente
Example request: 
curl --request GET \
    --get "https://www.handwritingocr.com/api/v1/documents/voluptas" \
    --header "Authorization: Bearer {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"
Example response:
{
    "id": "abc123",
    "status": "processed",
    "action": "transcribe",
    "created_at": "2023-05-01T12:00:00Z",
    "updated_at": "2023-05-01T12:30:00Z",
    "results": {
        "txt": "https://www.handwritingocr.com/api/v1/documents/abc123/download/token123/transcribe.txt",
        "docx": "https://www.handwritingocr.com/api/v1/documents/abc123/download/token123/transcribe.docx",
        "json": "https://www.handwritingocr.com/api/v1/documents/abc123/download/token123/transcribe.json"
    }
}
{
    "message": "Document abc123 was not found"
}

Process a new document

POST
https://www.handwritingocr.com
/api/v1/documents
requires authentication

Upload a new document for processing.

Headers

Authorization
Example:
Bearer {YOUR_AUTH_KEY}
Content-Type
Example:
multipart/form-data
Accept
Example:
application/json

Body Parameters

Example request: 
curl --request POST \
    "https://www.handwritingocr.com/api/v1/documents" \
    --header "Authorization: Bearer {YOUR_AUTH_KEY}" \
    --header "Content-Type: multipart/form-data" \
    --header "Accept: application/json" \
    --form "action=magnam"\
    --form "extractor_id=16"\
    --form "delete_after=19"\
    --form "file=@/private/var/folders/xt/b28shz4965d33r0h9hpysjzh0000gn/T/php8drX8a"
Example response:
{
    "document_id": "abc123",
    "status": "queued"
}
{
    "errors": {
        "file": [
            "The file field is required."
        ],
        "action": [
            "The action field is required."
        ]
    }
}

Delete a document

DELETE
https://www.handwritingocr.com
/api/v1/documents/{hashid}
requires authentication

Delete a specific document and its associated file.

Headers

Authorization
Example:
Bearer {YOUR_AUTH_KEY}
Content-Type
Example:
application/json
Accept
Example:
application/json

URL Parameters

hashid
string
required
Example:
dignissimos
id
string
required

The document's id.

Example:
illum
Example request: 
curl --request DELETE \
    "https://www.handwritingocr.com/api/v1/documents/dignissimos" \
    --header "Authorization: Bearer {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"
Example response:
[Empty response]
{
    "message": "No query results for model [App\\Models\\Document] abc123"
}

Download processed document

GET
https://www.handwritingocr.com
/api/v1/documents/{hashid}/download/{token}/{action}.{format}
requires authentication

Download a processed document in the specified format.

Headers

Authorization
Example:
Bearer {YOUR_AUTH_KEY}
Content-Type
Example:
application/json
Accept
Example:
application/json

URL Parameters

hashid
string
required
Example:
sit
token
string
required

The download token.

Example:
dolores
action
string
required

The processing action. Must be one of: transcribe, tables, extractor.

Example:
corporis
format
string
required

The download format. Available formats depend on the action.

Example:
quis
id
string
required

The document's id.

Example:
voluptas
Example request: 
curl --request GET \
    --get "https://www.handwritingocr.com/api/v1/documents/sit/download/dolores/corporis.quis" \
    --header "Authorization: Bearer {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"
Example response:
{
 "binary_file_content"
}
{
    "error": "Invalid or expired download token"
}