Documents

Upload document

Upload a new document for processing. Supports PDF files and

POST /api/v3/documents Try It

Upload document

cURL

curl -X POST "https://api.handwritingocr.com/v3/documents" \
     -H "Authorization: Bearer your-api-token" \
     -H "Accept: application/json" \
     -F "file=@/path/to/document.pdf" \
     -F "action=transcribe" \
     -F "delete_after=604800"

import requests

url = "https://api.handwritingocr.com/v3/documents"

payload = "-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"action\"\r\n\r\ntranscribe\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"file\"\r\n\r\nstring\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"delete_after\"\r\n\r\n300\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"extractor_id\"\r\n\r\nstring\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"webhook_url\"\r\n\r\nhttp://example.com\r\n-----011000010111000001101001--\r\n"
headers = {
    "Authorization": "Bearer your-api-token",
    "content-type": "multipart/form-data"
}

response = requests.request("POST", url, data=payload, headers=headers)

print(response.text)

const form = new FormData();
form.append("action", "transcribe");
form.append("file", "string");
form.append("delete_after", "300");
form.append("extractor_id", "string");
form.append("webhook_url", "http://example.com");

const options = {
  method: 'POST',
  headers: {
    Authorization: 'Bearer your-api-token',
    'content-type': 'multipart/form-data'
  }
};

options.body = form;

fetch('https://api.handwritingocr.com/v3/documents', options)
  .then(response => response.json())
  .then(response => console.log(response))
  .catch(err => console.error(err));

require 'uri'
require 'net/http'
require 'openssl'

url = URI("https://api.handwritingocr.com/v3/documents")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
http.verify_mode = OpenSSL::SSL::VERIFY_NONE

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer your-api-token'
request["content-type"] = 'multipart/form-data'
request.body = "-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"action\"\r\n\r\ntranscribe\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"file\"\r\n\r\nstring\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"delete_after\"\r\n\r\n300\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"extractor_id\"\r\n\r\nstring\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"webhook_url\"\r\n\r\nhttp://example.com\r\n-----011000010111000001101001--\r\n"

response = http.request(request)
puts response.read_body

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.handwritingocr.com/v3/documents",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => "-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"action\"\r\n\r\ntranscribe\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"file\"\r\n\r\nstring\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"delete_after\"\r\n\r\n300\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"extractor_id\"\r\n\r\nstring\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"webhook_url\"\r\n\r\nhttp://example.com\r\n-----011000010111000001101001--\r\n",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer your-api-token",
    "content-type: multipart/form-data"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io/ioutil"
)

func main() {

	url := "https://api.handwritingocr.com/v3/documents"

	payload := strings.NewReader("-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"action\"\r\n\r\ntranscribe\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"file\"\r\n\r\nstring\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"delete_after\"\r\n\r\n300\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"extractor_id\"\r\n\r\nstring\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"webhook_url\"\r\n\r\nhttp://example.com\r\n-----011000010111000001101001--\r\n")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer your-api-token")
	req.Header.Add("content-type", "multipart/form-data")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := ioutil.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}

201 application/json

{
  "id": "abc123",
  "status": "queued"
}

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

Headers

Authorization string required header

Bearer your-api-token
Accept string required header

application/json
Content-Type string required header

multipart/form-data

Body parameters

action string required body

What to do with the document. transcribe extracts text, tables extracts table structure, extractor runs a Custom Extractor.
file file required body

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

Seconds until auto-deletion. Overrides the auto-deletion period set in your user settings. Minimum 300 seconds, maximum 1209600 seconds (14 days).
extractor_id string body

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.
webhook_url string body

A webhook URL to send the results for this request. Overrides your global webhook URL.

Response codes

HTTP status

201

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.

Upload document

cURL

curl -X POST "https://api.handwritingocr.com/v3/documents" \
     -H "Authorization: Bearer your-api-token" \
     -H "Accept: application/json" \
     -F "file=@/path/to/document.pdf" \
     -F "action=transcribe" \
     -F "delete_after=604800"

import requests

url = "https://api.handwritingocr.com/v3/documents"

payload = "-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"action\"\r\n\r\ntranscribe\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"file\"\r\n\r\nstring\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"delete_after\"\r\n\r\n300\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"extractor_id\"\r\n\r\nstring\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"webhook_url\"\r\n\r\nhttp://example.com\r\n-----011000010111000001101001--\r\n"
headers = {
    "Authorization": "Bearer your-api-token",
    "content-type": "multipart/form-data"
}

response = requests.request("POST", url, data=payload, headers=headers)

print(response.text)

const form = new FormData();
form.append("action", "transcribe");
form.append("file", "string");
form.append("delete_after", "300");
form.append("extractor_id", "string");
form.append("webhook_url", "http://example.com");

const options = {
  method: 'POST',
  headers: {
    Authorization: 'Bearer your-api-token',
    'content-type': 'multipart/form-data'
  }
};

options.body = form;

fetch('https://api.handwritingocr.com/v3/documents', options)
  .then(response => response.json())
  .then(response => console.log(response))
  .catch(err => console.error(err));

require 'uri'
require 'net/http'
require 'openssl'

url = URI("https://api.handwritingocr.com/v3/documents")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
http.verify_mode = OpenSSL::SSL::VERIFY_NONE

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer your-api-token'
request["content-type"] = 'multipart/form-data'
request.body = "-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"action\"\r\n\r\ntranscribe\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"file\"\r\n\r\nstring\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"delete_after\"\r\n\r\n300\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"extractor_id\"\r\n\r\nstring\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"webhook_url\"\r\n\r\nhttp://example.com\r\n-----011000010111000001101001--\r\n"

response = http.request(request)
puts response.read_body

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.handwritingocr.com/v3/documents",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => "-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"action\"\r\n\r\ntranscribe\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"file\"\r\n\r\nstring\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"delete_after\"\r\n\r\n300\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"extractor_id\"\r\n\r\nstring\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"webhook_url\"\r\n\r\nhttp://example.com\r\n-----011000010111000001101001--\r\n",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer your-api-token",
    "content-type: multipart/form-data"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io/ioutil"
)

func main() {

	url := "https://api.handwritingocr.com/v3/documents"

	payload := strings.NewReader("-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"action\"\r\n\r\ntranscribe\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"file\"\r\n\r\nstring\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"delete_after\"\r\n\r\n300\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"extractor_id\"\r\n\r\nstring\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"webhook_url\"\r\n\r\nhttp://example.com\r\n-----011000010111000001101001--\r\n")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer your-api-token")
	req.Header.Add("content-type", "multipart/form-data")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := ioutil.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}

201 application/json

{
  "id": "abc123",
  "status": "queued"
}