Tools and options
Every tool a run can start, the files it takes and each option it accepts, with the limits that refuse a run before anything is counted.
How options work
Send the options of a tool in the options object of POST /v1/tools/{toolId}/runs. The server checks them with the rules below before it counts anything, so a run with options that do not fit is refused with the error code options.invalid and costs no task. The same rules are returned as a JSON Schema in the options field of GET /v1/tools/{toolId}. An option that is not listed is refused.
Page numbers count from 1. A page list is written like 1-3, 5. Positions on a page, in the tools that draw on it, are in points (72 to the inch) measured from the bottom left corner of the visible page, before any rotation the page carries. Colours are written #RRGGBB. Text drawn on a page uses a standard font, so it accepts Western European characters only; other text is refused with options.invalid.
A tool that places pictures on a document (sign and editor) takes the document as the first file and the pictures after it, in order. A picture is named in the options by its number, from 1.
merge
Takes at least 2 files of type PDF.
This tool takes no options. Send an empty object.
split
Takes 1 file of type PDF. Returns: One ZIP holding one PDF for each range.
| Option | Type | Required | Limits |
|---|---|---|---|
ranges | string | No | 1 to 2000 characters |
every | integer | No | 1 to 2000 |
reorder
Takes 1 file of type PDF.
| Option | Type | Required | Limits |
|---|---|---|---|
order | array of integer | Yes | 1 to 2000 items |
extract-pages
Takes 1 file of type PDF.
| Option | Type | Required | Limits |
|---|---|---|---|
pages | string | Yes | 1 to 2000 characters |
insert-pages
Takes 2 files of type PDF.
| Option | Type | Required | Limits |
|---|---|---|---|
after | integer | Yes | 0 to 2000 |
insert-blank-pages
Takes 1 file of type PDF.
| Option | Type | Required | Limits |
|---|---|---|---|
after | integer | Yes | 0 to 2000 |
count | integer | Yes | 1 to 500 |
delete-pages
Takes 1 file of type PDF.
| Option | Type | Required | Limits |
|---|---|---|---|
pages | string | Yes | 1 to 2000 characters |
rotate
Takes 1 file of type PDF.
| Option | Type | Required | Limits |
|---|---|---|---|
angle | 90 or 180 or 270 | No | default 90 |
pages | string | No | 1 to 2000 characters |
crop
Takes 1 file of type PDF.
| Option | Type | Required | Limits |
|---|---|---|---|
top | number | No | 0 to 1000, default 10 |
right | number | No | 0 to 1000, default 10 |
bottom | number | No | 0 to 1000, default 10 |
left | number | No | 0 to 1000, default 10 |
pages | string | No | 1 to 2000 characters |
page-numbers
Takes 1 file of type PDF.
| Option | Type | Required | Limits |
|---|---|---|---|
position | "bottom-center" | "bottom-right" | "bottom-left" | "top-center" | "top-right" | "top-left" | No | default "bottom-center" |
start | integer | No | 0 to 100000, default 1 |
format | "n" | "n-of-total" | No | default "n" |
pdf-to-word
Takes at least 1 file of type PDF.
This tool takes no options. Send an empty object.
pdf-to-excel
Takes at least 1 file of type PDF.
This tool takes no options. Send an empty object.
pdf-to-ppt
Takes at least 1 file of type PDF.
This tool takes no options. Send an empty object.
pdf-to-zpl
Takes 1 file of type PDF. Returns: One ZPL file with a label for each page.
| Option | Type | Required | Limits |
|---|---|---|---|
density | 6 or 8 or 12 or 24 | No | default 8 |
size | "4x6in" | "4x4in" | "4x2in" | "2x1in" | "100x150mm" | No | default "4x6in" |
fit | "contain" | "cover" | No | default "contain" |
threshold | integer | No | 1 to 254, default 128 |
compression | "hex" | "acs" | "z64" | No | default "z64" |
pdf-to-jpg
Takes 1 file of type PDF. Returns: One JPEG for a one page document, otherwise one ZIP with a JPEG for each page.
| Option | Type | Required | Limits |
|---|---|---|---|
dpi | 72 or 150 or 300 | No | default 150 |
quality | integer | No | 10 to 100, default 85 |
pdf-to-png
Takes 1 file of type PDF. Returns: One PNG for a one page document, otherwise one ZIP with a PNG for each page.
| Option | Type | Required | Limits |
|---|---|---|---|
dpi | 72 or 150 or 300 | No | default 150 |
pdf-a
Takes at least 1 file of type PDF.
This tool takes no options. Send an empty object.
word-to-pdf
Takes at least 1 file of type application/vnd.openxmlformats-officedocument.wordprocessingml.document, application/msword, application/vnd.oasis.opendocument.text, application/rtf.
This tool takes no options. Send an empty object.
excel-to-pdf
Takes at least 1 file of type application/vnd.openxmlformats-officedocument.spreadsheetml.sheet, application/vnd.ms-excel, application/vnd.oasis.opendocument.spreadsheet, text/csv.
This tool takes no options. Send an empty object.
ppt-to-pdf
Takes at least 1 file of type application/vnd.openxmlformats-officedocument.presentationml.presentation, application/vnd.ms-powerpoint, application/vnd.oasis.opendocument.presentation.
This tool takes no options. Send an empty object.
zpl-to-pdf
Takes 1 file of type text.
| Option | Type | Required | Limits |
|---|---|---|---|
density | 6 or 8 or 12 or 24 | No | default 8 |
size | "4x6in" | "4x4in" | "4x2in" | "2x1in" | "100x150mm" | No | default "4x6in" |
jpg-to-pdf
Takes at least 1 file of type JPEG, PNG.
| Option | Type | Required | Limits |
|---|---|---|---|
size | "fit" | "a4" | "letter" | No | default "fit" |
margin | number | No | 0 to 50, default 0 |
html-to-pdf
Takes 0 to 1 files of type text/html.
| Option | Type | Required | Limits |
|---|---|---|---|
url | string | No | 1 to 2048 characters |
scan-to-pdf
Takes at least 1 file of type JPEG, PNG.
| Option | Type | Required | Limits |
|---|---|---|---|
size | "fit" | "a4" | "letter" | No | default "a4" |
margin | number | No | 0 to 50, default 10 |
clean | boolean | No | default true |
editor
Takes 1 to 11 files of type PDF, JPEG, PNG. Returns: A PDF with the text, pictures and rectangles drawn into the page content.
| Option | Type | Required | Limits |
|---|---|---|---|
edits | array of object or object or object | Yes | 1 to 500 items |
edits[].type | "text" | Yes | |
edits[].page | integer | Yes | 1 to 2000 |
edits[].x | number | No | -20000 to 20000 |
edits[].y | number | No | -20000 to 20000 |
edits[].anchor | "bottom-left" | "bottom-center" | "bottom-right" | "top-left" | "top-center" | "top-right" | "center" | No | |
edits[].text | string | Yes | 1 to 2000 characters |
edits[].size | number | No | 4 to 200, default 12 |
edits[].color | string | No | default "#000000" |
edits[].opacity | number | No | at most 1, above 0, default 1 |
edits[].type | "image" | Yes | |
edits[].page | integer | Yes | 1 to 2000 |
edits[].image | integer | Yes | 1 to 10 |
edits[].x | number | No | -20000 to 20000 |
edits[].y | number | No | -20000 to 20000 |
edits[].anchor | "bottom-left" | "bottom-center" | "bottom-right" | "top-left" | "top-center" | "top-right" | "center" | No | |
edits[].width | number | Yes | at most 20000, above 0 |
edits[].height | number | No | at most 20000, above 0 |
edits[].opacity | number | No | at most 1, above 0, default 1 |
edits[].type | "rectangle" | Yes | |
edits[].page | integer | Yes | 1 to 2000 |
edits[].x | number | Yes | -20000 to 20000 |
edits[].y | number | Yes | -20000 to 20000 |
edits[].width | number | Yes | at most 20000, above 0 |
edits[].height | number | Yes | at most 20000, above 0 |
edits[].color | string | No | default "#FFFFFF" |
edits[].opacity | number | No | at most 1, above 0, default 1 |
watermark
Takes 1 file of type PDF.
| Option | Type | Required | Limits |
|---|---|---|---|
text | string | Yes | 1 to 200 characters |
opacity | number | No | at most 1, above 0, default 0.25 |
pages | string | No | 1 to 2000 characters |
forms
Takes 1 file of type PDF.
| Option | Type | Required | Limits |
|---|---|---|---|
values | object | Yes | |
flatten | boolean | No | default false |
compare
Takes 2 files of type PDF. Returns: One JSON report: whether the documents are identical, and for each changed page the words removed and added.
This tool takes no options. Send an empty object.
annotate
Takes 1 file of type PDF. Returns: A PDF with real annotations, which any reader shows and lets the person edit or delete.
| Option | Type | Required | Limits |
|---|---|---|---|
annotations | array of object or object or object or object or object | Yes | 1 to 500 items |
annotations[].type | "highlight" | Yes | |
annotations[].page | integer | Yes | 1 to 2000 |
annotations[].x | number | Yes | -20000 to 20000 |
annotations[].y | number | Yes | -20000 to 20000 |
annotations[].width | number | Yes | at most 20000, above 0 |
annotations[].height | number | Yes | at most 20000, above 0 |
annotations[].color | string | No | default "#FFEB3B" |
annotations[].opacity | number | No | at most 1, above 0, default 0.4 |
annotations[].contents | string | No | 1 to 2000 characters |
annotations[].type | "rectangle" | Yes | |
annotations[].page | integer | Yes | 1 to 2000 |
annotations[].x | number | Yes | -20000 to 20000 |
annotations[].y | number | Yes | -20000 to 20000 |
annotations[].width | number | Yes | at most 20000, above 0 |
annotations[].height | number | Yes | at most 20000, above 0 |
annotations[].color | string | No | default "#E53935" |
annotations[].lineWidth | number | No | 0.25 to 20, default 2 |
annotations[].contents | string | No | 1 to 2000 characters |
annotations[].type | "line" | Yes | |
annotations[].page | integer | Yes | 1 to 2000 |
annotations[].x1 | number | Yes | -20000 to 20000 |
annotations[].y1 | number | Yes | -20000 to 20000 |
annotations[].x2 | number | Yes | -20000 to 20000 |
annotations[].y2 | number | Yes | -20000 to 20000 |
annotations[].color | string | No | default "#E53935" |
annotations[].lineWidth | number | No | 0.25 to 20, default 2 |
annotations[].contents | string | No | 1 to 2000 characters |
annotations[].type | "note" | Yes | |
annotations[].page | integer | Yes | 1 to 2000 |
annotations[].x | number | Yes | -20000 to 20000 |
annotations[].y | number | Yes | -20000 to 20000 |
annotations[].contents | string | Yes | 1 to 2000 characters |
annotations[].color | string | No | default "#FFEB3B" |
annotations[].type | "text" | Yes | |
annotations[].page | integer | Yes | 1 to 2000 |
annotations[].x | number | Yes | -20000 to 20000 |
annotations[].y | number | Yes | -20000 to 20000 |
annotations[].width | number | Yes | at most 20000, above 0 |
annotations[].height | number | Yes | at most 20000, above 0 |
annotations[].text | string | Yes | 1 to 2000 characters |
annotations[].size | number | No | 4 to 72, default 12 |
annotations[].color | string | No | default "#000000" |
bates
Takes at least 1 file of type PDF.
| Option | Type | Required | Limits |
|---|---|---|---|
prefix | string | No | at most 32 characters, default "" |
suffix | string | No | at most 32 characters, default "" |
start | integer | No | 0 to 1000000000000, default 1 |
digits | integer | No | 1 to 12, default 6 |
position | "bottom-right" | "bottom-left" | "bottom-center" | "top-right" | "top-left" | "top-center" | No | default "bottom-right" |
fontSize | number | No | 4 to 72, default 10 |
redact
Takes 1 file of type PDF. Returns: A PDF in which each page with a covered area has been rebuilt from a picture of itself, so the covered text, drawing and pictures no longer exist in the file. Pages without a covered area are copied unchanged. Annotations, links and form fields of a rebuilt page are not kept, and the information of the original document (title, author and similar) is dropped.
| Option | Type | Required | Limits |
|---|---|---|---|
areas | array of object | No | at most 500 items |
areas[].page | integer | Yes | 1 to 2000 |
areas[].x | number | Yes | -20000 to 20000 |
areas[].y | number | Yes | -20000 to 20000 |
areas[].width | number | Yes | at most 20000, above 0 |
areas[].height | number | Yes | at most 20000, above 0 |
terms | array of string | No | at most 50 items |
dpi | 150 or 200 or 300 | No | default 200 |
protect
Takes 1 file of type PDF.
| Option | Type | Required | Limits |
|---|---|---|---|
password | string | Yes | 4 to 128 characters |
ownerPassword | string | No | 4 to 128 characters |
allowPrinting | boolean | No | default true |
allowCopying | boolean | No | default true |
allowEditing | boolean | No | default true |
unlock
Takes 1 file of type PDF.
| Option | Type | Required | Limits |
|---|---|---|---|
password | string | Yes | 1 to 128 characters |
repair
Takes 1 file of type PDF.
This tool takes no options. Send an empty object.
sign
Takes 2 to 11 files of type PDF, JPEG, PNG. Returns: A PDF with the signature pictures drawn into the page content. This places a picture. It is not a certificate signature.
| Option | Type | Required | Limits |
|---|---|---|---|
placements | array of object | Yes | 1 to 50 items |
placements[].page | integer | Yes | 1 to 2000 |
placements[].image | integer | Yes | 1 to 10 |
placements[].x | number | No | -20000 to 20000 |
placements[].y | number | No | -20000 to 20000 |
placements[].anchor | "bottom-left" | "bottom-center" | "bottom-right" | "top-left" | "top-center" | "top-right" | "center" | No | |
placements[].width | number | Yes | at most 20000, above 0 |
placements[].height | number | No | at most 20000, above 0 |
placements[].opacity | number | No | at most 1, above 0, default 1 |
compress
Takes at least 1 file of type PDF.
| Option | Type | Required | Limits |
|---|---|---|---|
quality | "lossless" | "balanced" | "small" | No | default "balanced" |
ocr
Takes 1 file of type PDF.
| Option | Type | Required | Limits |
|---|---|---|---|
languages | array of "eng" | "spa" | "hin" | "fra" | "deu" | "jpn" | "chi_sim" | "ara" | "por" | "heb" | Yes | 1 to 3 items |