Documents

Download result

Retrieve the status of a document, or download the processed

GET /api/v3/documents/{id}[.{format}] Try It

Download result

cURL
curl --request GET \
  --url 'https://api.handwritingocr.com/v3/documents/abcde12345?format=SOME_STRING_VALUE' \
  --header 'Authorization: Bearer your-api-token'
200 application/json
3 examples
{
  "id": "3486EvMD9p",
  "file_name": "page-1.jpg",
  "action": "transcribe",
  "page_count": 2,
  "status": "processed",
  "results": [
    {
      "page_number": 1,
      "transcript": "Lorem ipsum dolor sit amet, consectetur adipiscing elit."
    },
    {
      "page_number": 2,
      "transcript": "Ut enim ad minim veniam, quis nostrud exercitation ullamco."
    }
  ],
  "thumbnails": [
    {
      "page_number": 1,
      "url": "https://api.handwritingocr.com/v3/document/3486EvMD9p/image-1.jpg"
    }
  ],
  "automatically_deleted_at": "2025-03-05 19:47:44",
  "created_at": "2025-02-19T19:47:44.000000Z",
  "updated_at": "2025-02-21T03:05:42.000000Z"
}

Retrieve the status of a document, or download the processed results. The format extension is optional — if not provided, returns a JSON status response. If the format extension is provided (e.g. documents/abc123.txt), downloads the processed document in that format.

Image thumbnail URLs are provided for each page. These images must be authenticated with your API token to download.

Webhooks

We strongly encourage using a webhook instead of polling this endpoint repeatedly. Webhooks deliver the processed result in JSON format to a URL you choose as soon as the document is ready, saving bandwidth and reducing latency. Configure a webhook in the user dashboard.

Headers

  • Authorization string required header

    Bearer your-api-token

  • Accept string required header

    application/json

Path parameters

  • id string required path

    The document's unique identifier (e.g. abcde12345).

Query parameters

  • format string query

    Output format passed as a URL extension on the path (e.g. documents/abc123.txt). Varies by action: txt, docx, xlsx, csv, json.

Response codes

HTTP status
  • 200

    Returns the processed result.

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

  • 429

    Too many requests — rate limited.

  • 500

    Server Error — error preparing file for download.