PDFZOID

Documentation

Table of Contents

Overview

PDFzoid is a HTTP API to work with PDF documents. It fast and secure way to generate PDFs, modify existing files, extract text or images and more. Additionally you can run multiple PDF operations in single HTTP request by using PDFzoid pipeline API.

API Authentication

To run API you should request special API key – please contact us to get more details.

Doc operations

Currently we are supporting following operations:

  • Generate PDF by URL
  • Generate PDF by sending HTML template (multiple CSS files are supported)
  • Range/Drop/Insert pages in document
  • Split/Merge PDF files
  • Insert operation.
  • Convert some PDF page to image (can be used as preview)

Generate by Url

Simply generate PDF based on some web page. Web page should be public (no authentication, no private network) and accessible over Internet.

To generate PDF make GET request like:

curl --location --request GET 'https://api.pdfzoid.apizoid.com/v1/pdf/doc/generate/url?url=https://apizoid.com/' \
--header 'x-apizoid-key: XXXX_YOURKEY_XXXX'

Required parameters:
url - web page URL

Result:
PDF file

Generate by html template

Another option to generate PDF file is to use HTML template. API supports CSS inside HTML template file or by passing extra CSS files in request.

curl --location --request POST 'https://api.pdfzoid.apizoid.com/v1/pdf/doc/generate/html' \
--header 'x-apizoid-key: XXXX_YOURKEY_XXXX' \
--form 'html=@"./sample_html.html"' \
--form 'css=@"./sample_html.css"' \
--form 'css=@"./sample_html2.css"'

Required parameters:
html - HTML template file

Optional parameters:
css - CSS files. Multiple CSS files are supported

Result:
PDF file

Range pages

To get some specific range of pages (like only first 10 pages or pages from 5 to 15) you can use following request:

curl --location --request POST 'https://api.pdfzoid.apizoid.com/v1/pdf/doc/range?offset=2&limit=2' \
--header 'x-apizoid-key: XXXX_YOURKEY_XXXX' \
--form 'file=@"./wiki_long_text.pdf"'

Required parameters:
file - origin PDF file

Optional parameters:
offset - how many pages to skip from start. Default is 0
limit - how many pages to process. If not provided all pages starting from offset will be processed

Result:
ranged PDF file

Drop pages

Just removes some pages from document. Behavior is opposite to range.

curl --location --request POST 'https://api.pdfzoid.apizoid.com/v1/pdf/doc/drop?offset=1&limit=2' \
--header 'x-apizoid-key: XXXX_YOURKEY_XXXX' \
--form 'file=@"./wiki_long_text.pdf"'

Required parameters:
file - origin PDF file

Optional parameters:
offset - how many pages to skip from start. Default is 0
limit - how many pages to process. If not provided all pages starting from offset will be processed

Result:
PDF file without some pages

Insert pages

One PDF document can be inserted into another by calling following API:

curl --location --request POST 'https://api.pdfzoid.apizoid.com/v1/pdf/doc/insert?offset=2' \
--header 'x-apizoid-key: XXXX_YOURKEY_XXXX' \
--form 'origin=@"./wiki_long_text.pdf"' \
--form 'newpart=@"./wiki_mainpage.pdf"'

Required parameters:
origin - PDF file to insert into
newpart - PDF file to be inserted

Optional parameters:
offset - how many pages to skip from start. Default is 0

Result:
PDF file with new part

Split document

PDF document can be divided to multiple files:

curl --location --request POST 'https://api.pdfzoid.apizoid.com/v1/pdf/doc/split?npages=3' \
--header 'x-apizoid-key: XXXX_YOURKEY_XXXX' \
--form 'file=@"./wiki_long_text.pdf"'

Required parameters:
file - PDF file to split

Optional parameters:
npages - how many pages will be in each file. Default is 1

Result:
zip file with list of PDF parts

Merge pdf documents

Multiple PDF files can be merged to single one by calling:

curl --location --request POST 'https://api.pdfzoid.apizoid.com/v1/pdf/doc/merge' \
--header 'x-apizoid-key: XXXX_YOURKEY_XXXX' \
--form 'files=@"./wiki_long_text.pdf"' \
--form 'files=@"./wiki_mainpage.pdf"'

Required parameters:
files - PDF files. Multiple files supported. Minimal number of files to merge is 2 and maximum is 10

Result:
Single PDF file

Get document preview

Any page inside PDF document can be converter to image which then can be used as preview for example.

To get page preview please call following API:

curl --location --request POST 'https://api.pdfzoid.apizoid.com/v1/pdf/doc/preview?offset=5&dpi=50' \
--header 'x-apizoid-key: XXXX_YOURKEY_XXXX' \
--form 'file=@"./wiki_long_text.pdf"'

Required parameters:
file - PDF file to split

Optional parameters:
offset - how many pages to skip from start. Default is 0
dpi - image quality

Result:
Image file

Content operations

PDFzoid provides bunch of APIs to work with PDF content:

  • Extract text from PDF document
  • Extract images
  • Add image to PDF file – watermarks, stamps, barcodes or any other image you need to be placed on top of document

Extract text

Text can be extracted from PDF document by calling following API:

curl --location --request POST 'https://api.pdfzoid.apizoid.com/v1/pdf/content/text/get?offset=2&limit=2' \
--header 'x-apizoid-key: XXXX_YOURKEY_XXXX' \
--form 'file=@"./wiki_long_text.pdf"'

Required parameters:
file - origin PDF file

Optional parameters:
offset - how many pages to skip from start. Default is 0
limit - how many pages to process. If not provided all pages starting from offset will be processed

Result:
Extracted text

Extract images

Following API can be used to extract images from PDF file:

curl --location --request POST 'https://api.pdfzoid.apizoid.com/v1/pdf/content/images/get?offset=2&limit=2' \
--header 'x-apizoid-key: XXXX_YOURKEY_XXXX' \
--form 'file=@"./wiki_long_text.pdf"'

Required parameters:
file - origin PDF file

Optional parameters:
offset - how many pages to skip from start. Default is 0
limit - how many pages to process. If not provided all pages starting from offset will be processed

Result:
zip file with images

Add image

To add some image to existing PDF file following API could be used:

curl --location --request POST 'https://api.pdfzoid.apizoid.com/v1/pdf/content/images/add?offset=2&limit=2&x=100&y=100&width=150&height=100' \
--header 'x-apizoid-key: XXXX_YOURKEY_XXXX' \
--form 'pdf=@"./wiki_long_text.pdf"' \
--form 'img=@"./barcode.png"'

Required parameters:
pdf - origin PDF file
img - image file

Optional parameters:
offset - how many pages to skip from start. Default is 0
limit - how many pages to process. If not provided all pages starting from offset will be processed
x - image horizontal position from left side. Default is 0
y - image vertical position from bottom side. Default is 0
width - image size. Default is 1
height - image size. Default is 1

Result:
PDF file

PDF pipelines

Pipelines can be used to run multiple PDF operations in single API call. Single operation in pipeline is called pipeline step. Each pipeline request can contain up to 10 steps.

All document & content operations are supported but please pay attention – next operation accepts previous result so operations like split document, extract text and images, get page preview can be used only as ending step but pdf generation by URL or HTML can be run only as a first step.

Parameters and placeholders

Each pipeline step consists of 2 parts – operation name and map of parameters. Parameters naming is the same as in origin doc and content API. For example doc-range operation has 1 required parameter “file” (in case if it first step, otherwise previous step result will be used as “file”) and two optional parameters “offset” and “limit”.

To link binary parameters (like “file” or “img”) with step parameter please use placeholders:

curl --location --request POST 'https://api.pdfzoid.apizoid.com/v1/pdf/pipeline/run' \
--header 'x-apizoid-key: XXXX_YOURKEY_XXXX' \
--form 'pipeline="{
   \"steps\":[
      {
         \"name\":\"generate-html\",
         \"params\":{
            \"html\":\"${html_file}\",
            \"css\": \"${css_files}\"
         }
      },
      {
         \"name\":\"add-image\",
         \"params\":{
            \"img\": \"${my_barcode}\",
            \"x\": 100,
            \"y\": 100,
            \"width\": 100,
            \"height\": 75
         }
      }
   ]
}
"' \
--form 'html_file=@"./sample_html.html"' \
--form 'css_files=@"./sample_html.css"' \
--form 'css_files=@"./sample_html2.css"' \
--form 'my_barcode=@"./barcode.png"'

Required parameters:
pipeline - json representation of pipeline

Optional parameters:
List of files required by pipeline steps. File parameter name could be any like my_barcode in example. Just map this name to necessary step parameter with placeholder ${file_param_name} (in example its mapped to add-name step to img as ${my_barcode})

Supported operations

OperationStart onlyEnd only
generate-html+
generate-url+
doc-range
doc-drop
doc-insert
doc-split+
doc-merge+
doc-preview+
extract-text+
extract-images+
add-image

Pipeline examples

Example 1: generate PDF by URL, range 0-5 and split result:

curl --location --request POST 'https://api.pdfzoid.apizoid.com/v1/pdf/pipeline/run' \
--header 'x-apizoid-key: XXXX_YOURKEY_XXXX' \
--form 'pipeline="{
   \"steps\":[
      {
         \"name\":\"generate-url\",
         \"params\":{
            \"url\":\"https://en.wikipedia.org/wiki/Wikipedia\"
         }
      },
      {
         \"name\":\"doc-range\",
         \"params\":{
            \"limit\":\"5\",
            \"offset\": 0
         }
      },
      {
         \"name\":\"doc-split\",
         \"params\":{
            \"npages\":\"2\"
         }
      } 
   ]
}
"'

Example 2: drop 5-10, add image and get first page preview

curl --location --request POST 'https://api.pdfzoid.apizoid.com/v1/pdf/pipeline/run' \
--header 'x-apizoid-key: XXXX_YOURKEY_XXXX' \
--form 'pipeline="{
   \"steps\":[
      {
         \"name\":\"doc-drop\",
         \"params\":{
            \"file\":\"${my_pdf}\",
            \"offset\": 5,
            \"limit\": 10
         }
      },
      {
         \"name\":\"add-image\",
         \"params\":{
            \"img\": \"${my_barcode}\",
            \"x\": 100,
            \"y\": 100,
            \"width\": 100,
            \"height\": 75
         }
      },
      {
         \"name\":\"doc-preview\",
         \"params\":{
            \"offset\": 0
         }
      }
   ]
}
"' \
--form 'my_pdf=@"./wiki_long_text.pdf"' \
--form 'my_barcode=@"./barcode.png"'
Pricing

Currently we are in the middle of testing phase so using PDFzoid is completely free but you still need API key. To get it please contact us.