Sends an authorized API key and desired result file settings.
Returns an upload URL and file information.



Request Header

Header Field Value

Required. Valid API key. See Overview for details.

Request Body (Optional)

Name Type Description Notes
max_pages_per_document integer Maximum number of pages to convert for the document. Used to limit the number of pages per document that are converted. Useful when large documents are not expected, to reduce workloads and costs.
max_files_per_archive integer Maximum number of archived files to extract. If the uploaded file is an archive (.zip or tar.gz), use this to limit how many files are extracted from the archive for conversion and repacking into a new archive.

Example requests


import requests, json
apikey = "YOUR_APIKEY"
r ="", headers={"APIKEY": apikey})
auth_response = json.loads(r.text)

URL url = new URL("");
HttpURLConnection conn = (HttpURLConnection) url.openConnection();
conn.setRequestProperty("APIKEY", this.apikey);
BufferedReader = new BufferedReader(new InputStreamReader(conn.getInputStream()));
String inputLine;
StringBuffer content = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
JsonElement jsonTree =  new JsonParser().parse(content.toString());
JsonObject auth_response = jsonTree.getAsJsonObject();

url = new URL(auth_response.get("links").get("upload").getAsString());
conn = (HttpURLConnection) url.openConnection();
conn.setRequestProperty("filename", filename);

for (int i = 1; i <= 100; i++) {

    URL url = null;
    BufferedReader in = null;
    StringBuffer content = null;
    HttpURLConnection conn = null;
    url = new URL(itemUrl);
    conn = (HttpURLConnection) url.openConnection();
    conn.setRequestProperty("APIKEY", this.apikey);
    in = new BufferedReader(new InputStreamReader(conn.getInputStream()));
    String inputLine;
    content = new StringBuffer();
    while ((inputLine = in.readLine()) != null) {

    JsonElement jsonTree = new JsonParser().parse(content.toString());
    JsonObject status_response = jsonTree.getAsJsonObject();

    String status = (status_response.get("status").getAsString());
    if (!status.equals("waiting") && !status.equals("processing")) {




URL url = null;
HttpURLConnection conn = null;
int statusCode = 0;
String header = null;
ByteArrayOutputStream output = new ByteArrayOutputStream();
InputStream in = null;
try {
    url = new URL(downloadUrl);
    conn = (HttpURLConnection) url.openConnection();
    statusCode = conn.getResponseCode();
    header = conn.getHeaderField("content-disposition");
    in = conn.getInputStream();
    byte[] buffer = new byte[4096];
    int n;
    while ((n = > 0) {
    output.write(buffer, 0, n);
byte[] content = output.toByteArray();
String[] tokens = header.split("; filename=");
String filename = tokens[1].replace("\"" , "");

logger.log(Level.INFO, "Secured file " +filename  +" (" +content.length +" bytes) downloaded");

Result result = new Result(true, filename, content);
return result;


Menu 2

Sed ut perspiciatis unde omnis iste natus error sit voluptatem accusantium doloremque laudantium, totam rem aperiam.


The response is JSON and contains, at minimum, an error code. See Response Codes for details.

Response Body

Name Type Description
uid string Unique request ID
status string The default status is new after a successful authorisation request.
created string Date and timestamp the file was uploaded to the server.
source_name string Original file name of the uploaded file.
source_size integer Original size in bytes of the uploaded file.
error string Error message, see Response Codes for details.

Note: This field is only displayed if an error occure during authentication.
links array URLs for various actions. Possible keys are:
  • self: Link to call information about the uploaded file.
  • upload: Link to which the file must be uploaded. See Upload for details.

Example response

HTTP 202, OK
    "uid":         "abbc7c94-h11y-4r27-92fg-czd3362f464a",
    "created":     "2020-02-01T14:19:10.713Z",
    "status":      "new",
    "source_name": "",
    "source_size": 0,
    "links": {
        "self":   "",
        "upload": ""

HTTP 400, Bad Request
    "error": "invalid_request"

Response Codes

Code Value Description Response Body Value
202 Accepted Request accepted.
400 Bad Request One of the specified request body parameters was incorrect, or the API key was not sent in the request header. invalid_request
402 Payment Required Account file limit reached. Upgrade your plan to continue. payment_required
403 Forbidden Invalid API key in the request header. auth_failed
406 Not Acceptable Invalid parameter syntax. For example, -1 specified in the max_files_per_archive parameter in the request. value_error
429 Too Many Requests Too many simultaneous requests. too_many_requests

Any thoughts? Did we miss something? Drop us a note!