API Documentation

Introduction

The PDFZONEAPI is a JSON REST API that provides lightning-fast, high-quality PDFs of websites, HTML or URLs.

API requests are made using a friendly URL structure and successful results are returned as PDF files or errors in JSON format, providing a simple integration and full compatibility with any application, programming language or framework.

This API documentation explains all the parameters and features with API call examples that can be tested in your browser.

                        
                        https://pdfzoneapi.com/api/v1/
                    

Authentication

After signing up you will receive an API access key (shown in your dashboard) used to access any of the API endpoints.

To authenticate with the API you must provide your API access key in the access_key parameter of the API endpoint URL:

                        
                       https://pdfzoneapi.com/api/v1/convert?access_key=YOUR_ACCESS_KEY&document_url=https://pdfzoneapi.com
                    

Requests

The API can be called using both HTTP GET and POST requests. However we recommend using POST as some parameters may not be compatible with GET requests due to the encoding required or size limitations.

Any parameters which are not supported via GET requests will be marked accordingly in this documentation with a HTTP POST ONLY notification badge.

Errors

If your request fails the API will return a JSON response containing a 3-digit error code along with an internal error type and a plain text "info" parameter with suggestions on how to correct the error.

Below is an example error caused by providing an invalid API Access Key.

{
  "success": false,
  "error": {
    "code": 102,
    "type": "invalid_access_key",
    "info": "You supplied an invalid Access Key."
  }
}

API error codes:

Code Type Description
101 missing_access_key You did not supply an Access Key.
102 invalid_access_key You supplied an invalid Access Key.
104 usage_limit_reached You have reached your subscription plan's monthly API request allowance.
311 invalid_document_url You have supplied an invalid URL for the "document_url" parameter.
404 404_not_found The requested API resource does not exist.
429 too_many_requests You have exceeded the maximum allowed rate limitation as defined by your subscription plan. Please refer to the Rate Limits section of the API Documentation.
500 server_error Something went wrong - Internal server error.

Please Note: This is not a complete list of errors. If you come receive an error message you are not sure about please contact our support.

Rate Limits

Requests to the API are rate limited based on your current subscription plan:

Subscription Plan API Rate Limit
Free 1 Simultaneous Request
Startup 5 Simultaneous Requests
Pro 10 Simultaneous Requests
Advanced 20 Simultaneous Requests

Convert Overview

The convert endpoint allows you to send HTML code or any website or URL and have it returned as a PDF document.

                            
                            https://pdfzoneapi.com/api/v1/convert
                        
Required Parameters:

You must provide your API access key and one of the document_url or document_html parameters.

Parameter description
access_key Your API Access Key (Found in your dashboard).
document_url The full URL (including protocol) of the website you want to convert to a PDF document from, e.g. https://www.yahoo.com
document_html
HTTP POST ONLY
The raw HTML code required to produce the PDF document.
Optional Parameters:
Parameter Description Default
sandbox An integer boolean value. If set to 1 then a watermark will be added to the PDF document and no API credits will be deducted. This allows you to test your settings without using any credits. 0
document_name A string with a maximum length of 180 characters to be used as the returned PDF document's filename. pdfzoneapi.pdf
custom_unit A string which defines the unit of measure to be used when specifying other document units like page dimensions or margins. This can be one of the following values: "px", "mm", "in" or "pt" px
user_agent A string used to set a custom User-Agent HTTP header when requesting the a website or URL. This allows you to emulate different devices or platforms. The latest desktop chrome browser
accept_lang A string used to set a custom Accept-Language HTTP header when requesting the URL. This allows you to emulate different languages. en-US,en;q=0.5
ttl An integer value in seconds used to control when a new PDF document should be generated if one is cached already. 2592000 (30 days)
delay An integer value used to define how many seconds should be waited before the PDF is generated. This is useful when sites may be slow to load.
force An integer boolean value. If set to 1 then a new PDF document will be generated. If set to 0 then we will use a version if one exists below the ttl value. 0
inline An integer boolean value. If set to 1 then the PDF document will be returned inline and a browser will not show a download dialogue. 0
auth_user A string used to specify the HTTP authentication username when accessing a password protected URL using the document_url parameter
auth_pass A string used to specify the HTTP authentication password when accessing a password protected URL using the document_url parameter
encryption An integer value used to specify the encryption strength in bits to be used to secure the resulting PDF document. This can be the values "40" or "128".
owner_password A string used to specify the PDF document owner password when the file is encrypted. This can be a maximum of 32 characters.
user_password A string used to specify the PDF document user password when the file is encrypted. This can be a maximum of 32 characters.
no_images An integer boolean value. If set to 1 then images will be disabled in the generated PDF document. 0
no_hyperlinks An integer boolean value. If set to 1 then hyperlinks will be disabled in the generated PDF document. 0
no_backgrounds An integer boolean value. If set to 1 then css backgrounds will be disabled when rendering the HTML to generate the PDF document. 0
no_javascript An integer boolean value. If set to 1 then javascript will be disabled when rendering the HTML to generate the PDF document. 0
no_dialogs An integer boolean value. If set to 1 then popups will be closed when rendering the HTML to generate the PDF document. 0
use_print_media An integer boolean value. If set to 1 then the @media print CSS will be enabled when rendering the HTML to generate the PDF document. 0
greyscale An integer boolean value. If set to 1 then the PDF document will be generated in greyscale with no colours. 0
no_print An integer boolean value. If set to 1 then the generated PDF document not allow printing. 0
no_modify An integer boolean value. If set to 1 then the generated PDF document not allow modifications. 0
no_copy An integer boolean value. If set to 1 then the generated PDF document not allow the copying of any text. 0
page_size A string value used to define the PDF documents page size. This can be one of the following values: "Letter", "Legal", "Tabloid", "Ledger", "A0", "A1", "A2", "A3", "A4", "A5", "A6" A4
page_width An integer value used to define the PDF documents page width. This is to be supplied in the units set in the custom_unit parameter, will override the page_size parameter and must be used in conjunction with the page_height parameter.
page_height An integer value used to define the PDF documents page height. This is to be supplied in the units set in the custom_unit parameter, will override the page_size parameter and must be used in conjunction with the page_width parameter.
orientation A string value used to define the PDF documents page orientation. This can be one of the following values: "portrait", "landscape". portrait
margin_top An integer value used to define the PDF document pages top margin. This is to be supplied in the units set in the custom_unit parameter. 10
margin_right An integer value used to define the PDF document pages right margin. This is to be supplied in the units set in the custom_unit parameter. 10
margin_bottom An integer value used to define the PDF document pages bottom margin. This is to be supplied in the units set in the custom_unit parameter. 10
margin_left An integer value used to define the PDF document pages left margin. This is to be supplied in the units set in the custom_unit parameter. 10
viewport A string value used to define the viewport used to generate PDF document. This allows you to emulate different display sizes and should be in the format WIDTH x HEIGHT. 1440x900
css_url A string value used to define a URL to an extra .css file that will be imported before the PDF is generated.
title A string value used to define the meta title attribute in the generated PDF file. This can be a maximum of 150 characters.
subject A string value used to define the meta subject attribute in the generated PDF file. This can be a maximum of 150 characters.
creator A string value used to define the meta creator attribute in the generated PDF file. This can be a maximum of 150 characters.
author A string value used to define the meta author attribute in the generated PDF file. This can be a maximum of 150 characters.
header_url A string value used to define the url which should be loaded to provide the HTML header for the PDF file generation.
header_html
HTTP POST ONLY
A string value used to define the HTML which will be used in the header for the PDF file generation.
footer_url A string value used to define the url which should be loaded to provide the HTML footer for the PDF file generation.
footer_html
HTTP POST ONLY
A string value used to define the HTML which will be used in the footer for the PDF file generation.
watermark_url A string value used to define the url which should be loaded to provide an image to be used as a watermark for the PDF file generation.
Watermark image extension can be one of the following values: "png" or "jpg".
watermark_opacity An integer value used to define the opacity of the watermark image. 20
watermark_offset_x An integer value used to define the x-axis offset from the left of the page of the watermark image. By default the image will be centered in the middle of the page.
watermark_offset_y An integer value used to define the y-axis offset from the top of the page of the watermark image. By default the image will be centered in the middle of the page.

Sandbox

The sandbox parameter is a boolean integer value and allows you to test your settings and preview how a PDF will look without depleting your API credits.

If set to 1 then the PDF will be generated with a large red "sandbox" watermark in the center of each page of the document and no API credits will be deducted.

This can be set to 0 or 1.

By default, this is set to 0 so the resulting PDF will not contain the "sandbox" watermark.

                        
                       https://pdfzoneapi.com/api/v1/convert?access_key=YOUR_ACCESS_KEY&document_url=https://pdfzoneapi.com&sandbox=1
                    

Document Name

The document_name parameter is a string with a maximum length of 180 characters which will be used as the file name for the generated PDF document.

By default, this is set to the value "pdfzoneapi.pdf" so the resulting PDF will be named "pdfzoneapi.pdf".

If you do not include the ".pdf" file extension it will be appended and any reserved or invalid characters will be replaced with a "-".

If you need to find which charters are not allowed in filenames then please visit this link https://www.wikipedia.org/wiki/Filename#Reserved_characters_and_words

                        
                       https://pdfzoneapi.com/api/v1/convert?access_key=YOUR_ACCESS_KEY&document_url=https://pdfzoneapi.com&document_name=invoice_1234
                    

Custom Unit

The custom_unit parameter is a string which can be used to set the measurement units for the document when specifying the values in other parameters.

This can be one of the following values: "px", "mm", "in" or "pt"

By default, this is set to "px".

                        
                       https://pdfzoneapi.com/api/v1/convert?access_key=YOUR_ACCESS_KEY&document_url=https://pdfzoneapi.com&custom_unit=in
                    

User Agent

The user_agent parameter is a string value that allows you to specify a custom User-Agent HTTP header to be sent with the URL request enabling you to emulate different devices.

A list of common User-Agent strings can be found at https://developers.whatismybrowser.com/

By default, this is set to the most recent Google Chrome desktop browser.

                        
                       https://pdfzoneapi.com/api/v1/convert?access_key=YOUR_ACCESS_KEY&document_url=https://pdfzoneapi.com&user_agent=Mozilla/5.0 (Linux; U; Android 2.2) AppleWebKit/533.1 (KHTML, like Gecko) Version/4.0 Mobile Safari/533.1
                    

Accept Language

The accept_lang parameter is a string value that allows you to specify a custom Accept-Language HTTP header to be sent with the URL request enabling you to emulate different browser languages.

A list of common language strings can be found at http://4umi.com/web/html/languagecodes.php

By default this is set to "en-US,en;q=0.5" (US English).

                        
                       https://pdfzoneapi.com/api/v1/convert?access_key=YOUR_ACCESS_KEY&document_url=https://pdfzoneapi.com&accept_lang=fr-FR
                    

TTL

The ttl (Time To Live) parameter is an integer value and allows you to request the PDF image to be cached for a specific number of seconds.

This can be set to a maximum of 2592000 (30 days).

By default, this is set to 2592000 so the PDF document will be cached for 30 days.

                        
                       https://pdfzoneapi.com/api/v1/convert?access_key=YOUR_ACCESS_KEY&document_url=https://pdfzoneapi.com&ttl=86400
                    

Delay

The delay parameter is an integer value and allows you to request the PDF document to be delayed for a specific number of seconds.

This can be set to a maximum of 60.

By default, this is not set so the PDF document will be taken after the site has fully loaded.

                        
                       https://pdfzoneapi.com/api/v1/convert?access_key=YOUR_ACCESS_KEY&document_url=https://pdfzoneapi.com&delay=30
                    

Force

The force parameter is a boolean integer value and allows you to request the PDF document to be regenerated each time so no cache is used.

This can be set to 1 or 0.

By default, this is set to 0 so the ttl value will be used.

                        
                       https://pdfzoneapi.com/api/v1/convert?access_key=YOUR_ACCESS_KEY&document_url=https://pdfzoneapi.com&force=1
                    

Inline

The inline parameter is a boolean integer value and allows you to request the resulting PDF document to be returned with a HTTP header to control how a browser will react.

If set to 1 then a browser will try to view the PDF rather than showing a download dialogue.

This can be set to 1 or 0.

By default, this is set to 0 so a browser making this call will try to download the PDF document.

                        
                       https://pdfzoneapi.com/api/v1/convert?access_key=YOUR_ACCESS_KEY&document_url=https://pdfzoneapi.com&inline=1
                    

Auth User

The auth_user parameter is a string that allows you to provide the username to be used when accessing a password protected URL or website.

By default, this is not set.

                        
                       https://pdfzoneapi.com/api/v1/convert?access_key=YOUR_ACCESS_KEY&document_url=https://pdfzoneapi.com&auth_user=steve
                    

Auth Pass

The auth_pass parameter is a string that allows you to provide the password to be used when accessing a password protected URL or website.

By default, this is not set.

                        
                       https://pdfzoneapi.com/api/v1/convert?access_key=YOUR_ACCESS_KEY&document_url=https://pdfzoneapi.com&auth_pass=pass123
                    

Encryption

The encryption parameter is an integer value and allows you to request the level of encryption in bytes to be used to protect the PDF document.

This can be set to either 40 or 128.

By default, this is not set.

                        
                       https://pdfzoneapi.com/api/v1/convert?access_key=YOUR_ACCESS_KEY&document_url=https://pdfzoneapi.com&encryption=128
                    

Owner Password

The owner_password parameter is a string that allows you to set the owner level password to be used to protect the generated PDF document.

This can be a maximum of 32 characters.

By default, this is not set.

                        
                       https://pdfzoneapi.com/api/v1/convert?access_key=YOUR_ACCESS_KEY&document_url=https://pdfzoneapi.com&owner_password=pass123
                    

User Password

The user_password parameter is a string that allows you to set the user level password to be used to protect the generated PDF document.

This can be a maximum of 32 characters.

By default, this is not set.

                        
                       https://pdfzoneapi.com/api/v1/convert?access_key=YOUR_ACCESS_KEY&document_url=https://pdfzoneapi.com&user_password=pass123
                    

No Images

The no_images parameter is a boolean integer value and allows you to request the resulting PDF document to be generated without any images in the content.

If set to 1 then images will be excluded.

This can be set to 1 or 0.

By default, this is set to 0 so images will be shown in the PDF.

                        
                       https://pdfzoneapi.com/api/v1/convert?access_key=YOUR_ACCESS_KEY&document_url=https://pdfzoneapi.com&no_images=1
                    

No Backgrounds

The no_backgrounds parameter is a boolean integer value and allows you to request the resulting PDF document to be generated without any CSS backgrounds.

If set to 1 then any CSS backgrounds will be removed.

This can be set to 1 or 0.

By default, this is set to 0 so CSS backgrounds will be shown.

                        
                       https://pdfzoneapi.com/api/v1/convert?access_key=YOUR_ACCESS_KEY&document_url=https://pdfzoneapi.com&no_backgrounds=1
                    

No JavaScript

The no_javascript parameter is a boolean integer value and allows you to request the resulting PDF document to be generated without any JavaScript being run.

If set to 1 then JavaScript will be disabled.

This can be set to 1 or 0.

By default, this is set to 0 so JavaScript will be active.

                        
                       https://pdfzoneapi.com/api/v1/convert?access_key=YOUR_ACCESS_KEY&document_url=https://pdfzoneapi.com&no_javascript=1
                    

No Dialogs

The no_dialogs parameter is a boolean integer value and closes popups disallowing the PDF document to be taken.

If set to 1 then dialogs will be closed.

This can be set to 1 or 0.

By default, this is set to 0 so dialogs will be shown in the PDF document.

                        
                       https://pdfzoneapi.com/api/v1/convert?access_key=YOUR_ACCESS_KEY&document_url=https://pdfzoneapi.com&no_dialogs=1
                    

Use Print Media

The use_print_media parameter is a boolean integer value and allows you to request the resulting PDF document to be generated using the "print" media type.

If set to 1 then the "print" media type will be used and any CSS @media print declarations will become active.

This can be set to 1 or 0.

By default, this is set to 0 so the "screen" media type will be used.

                        
                       https://pdfzoneapi.com/api/v1/convert?access_key=YOUR_ACCESS_KEY&document_url=https://pdfzoneapi.com&use_print_media=1
                    

Greyscale

The greyscale parameter is a boolean integer value and allows you to request the resulting PDF document to be generated in greyscale.

If set to 1 then greyscale will be used and all colours removed.

This can be set to 1 or 0.

By default, this is set to 0 so the PDF will show all colours.

                        
                       https://pdfzoneapi.com/api/v1/convert?access_key=YOUR_ACCESS_KEY&document_url=https://pdfzoneapi.com&greyscale=1
                    

No Print

The no_print parameter is a boolean integer value and allows you to request the resulting PDF document to be generated with permissions disallowing printing.

If set to 1 then the permissions disallowing printing will be active.

This can be set to 1 or 0.

By default, this is set to 0 so the PDF will allow printing.

Please note that permissions also require at least one of the following parameters to be set: owner_password, user_password or encryption

                        
                       https://pdfzoneapi.com/api/v1/convert?access_key=YOUR_ACCESS_KEY&document_url=https://pdfzoneapi.com&no_print=1
                    

No Modify

The no_modify parameter is a boolean integer value and allows you to request the resulting PDF document to be generated with permissions disallowing modifications.

If set to 1 then the permissions disallowing modifications will be active.

This can be set to 1 or 0.

By default, this is set to 0 so the PDF will allow modifications.

Please note that permissions also require at least one of the following parameters to be set: owner_password, user_password or encryption

                        
                        https://pdfzoneapi.com/api/v1/convert?access_key=YOUR_ACCESS_KEY&document_url=https://pdfzoneapi.com&no_modify=1
                    

No Copy

The no_copy parameter is a boolean integer value and allows you to request the resulting PDF document to be generated with permissions disallowing its content from being copied.

If set to 1 then the permissions disallowing content copying will be active.

This can be set to 1 or 0.

By default, this is set to 0 so the PDF will allow copying.

Please note that permissions also require at least one of the following parameters to be set: owner_password, user_password or encryption

                        
                        https://pdfzoneapi.com/api/v1/convert?access_key=YOUR_ACCESS_KEY&document_url=https://pdfzoneapi.com&no_copy=1
                    

Page Size

The page_size parameter is a string value and allows you to specify the PDF document page size.

This can be set to: "Letter", "Legal", "Tabloid", "Ledger", "A0", "A1", "A2", "A3", "A4", "A5", "A6".

By default, this is set to "A4".

                        
                        https://pdfzoneapi.com/api/v1/convert?access_key=YOUR_ACCESS_KEY&document_url=https://pdfzoneapi.com&page_size=A3
                    

Dimensions

Instead of specifying a preconfigured Page Size the PDFZONEAPI also accepts two page dimension parameters. page_width and page_height.

By default, these are not set.

Please be aware that specifying these dimension parameters will override any specified preconfigured Page Sizes.

                        
                        https://pdfzoneapi.com/api/v1/convert?access_key=YOUR_ACCESS_KEY&document_url=https://pdfzoneapi.com&page_width=1920&page_height=1080
                    

Orientation

The orientation parameter is a string value and allows you to specify the PDF document orientation.

This can be set to "portrait" or "landscape".

By default, this is set to "portrait".

                        
                        https://pdfzoneapi.com/api/v1/convert?access_key=YOUR_ACCESS_KEY&document_url=https://pdfzoneapi.com&orientation=landscape
                    

Margins

Using the parameters margin_top, margin_bottom, margin_left and margin_right vertical and horizontal margins (in the selected Custom Unit) can be specified.

By default, this is set to 10 millimeters on each side.

                        
                        https://pdfzoneapi.com/api/v1/convert?access_key=YOUR_ACCESS_KEY&document_url=https://pdfzoneapi.com&margin_top=0&margin_right=0&margin_bottom=0&margin_left=0
                    

Viewport

The viewport parameter is a string composed of a width and a height as integer pixel values separated by an "x" which allows you to request the website or URL with specific screen size.

Details of common device viewports can be found at https://screensiz.es/.

This can be set to a maximum of 5000x5000 and a minimum of 1x1.

By default, this is set to the value 1440x900 so the captured image will only contain whatever parts of the website fit into the viewport.

                        
                        https://pdfzoneapi.com/api/v1/convert?access_key=YOUR_ACCESS_KEY&document_url=https://pdfzoneapi.com&viewport=600x400
                    

CSS URL

The css_url parameter is a string that allows you to pass the URL of a .css file which will be loaded before the PDF document is taken.

This allows you to customise the page or add watermarks etc.

By default, this is not set.

                        
                       https://pdfzoneapi.com/api/v1/convert?access_key=YOUR_ACCESS_KEY&document_url=https://pdfzoneapi.com&css_url=https://pdfzoneapi.com/css/css_url_example.css
                    

Document Title

The title parameter is a string value and allows you to specify the PDF document title.

By default, this is not set.

                        
                        https://pdfzoneapi.com/api/v1/convert?access_key=YOUR_ACCESS_KEY&document_url=https://pdfzoneapi.com&title=MyTitle
                    

Document Subject

The subject parameter is a string value and allows you to specify the PDF document subject.

By default, this is not set.

                        
                        https://pdfzoneapi.com/api/v1/convert?access_key=YOUR_ACCESS_KEY&document_url=https://pdfzoneapi.com&subject=MySubject
                    

Document Creator

The creator parameter is a string value and allows you to specify the PDF document creator.

By default, this is set to "PDFZONEAPI".

                        
                        https://pdfzoneapi.com/api/v1/convert?access_key=YOUR_ACCESS_KEY&document_url=https://pdfzoneapi.com&creator=MyCreator
                    

Document Author

The author parameter is a string value and allows you to specify the PDF document author.

By default, this is not set.

                        
                        https://pdfzoneapi.com/api/v1/convert?access_key=YOUR_ACCESS_KEY&document_url=https://pdfzoneapi.com&author=MyAuthor
                    

Watermark URL

The watermark_url parameter is a string value and allows you to specify an HTTP URL to add a customizable watermark image to the final PDF document.

Using the API's watermark_url parameter an HTTP URL containing a PNG (recommended) or JPG can be specified.

By default, this is not set.

                        
                        https://pdfzoneapi.com/api/v1/convert?access_key=YOUR_ACCESS_KEY&document_url=https://pdfzoneapi.com&watermark_url=http://example.com/watermark.png
                    

Watermark Opacity

The watermark_opacity parameter is a numeric value and allows you to specify the PDF document watermark opacity.

By default, this is set to 20 (20%).

                        
                        https://pdfzoneapi.com/api/v1/convert?access_key=YOUR_ACCESS_KEY&document_url=https://pdfzoneapi.com&watermark_url=http://example.com/watermark.png&watermark_opacity=25
                    

Watermark Positioning

Two parameters are offered that can be used to horizontally and vertically align a watermark image: watermark_offset_x and watermark_offset_y.

By default, watermark image is aligned at the center of the page

                        
                        https://pdfzoneapi.com/api/v1/convert?access_key=YOUR_ACCESS_KEY&document_url=https://pdfzoneapi.com&watermark_url=http://example.com/watermark.png&watermark_offset_x=15&watermark_offset_y=30