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/
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
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.
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."
}
}
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.
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 |
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
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. |
If the document_url
parameter contains any
special characters such as & or ? then it must be url
encoded if sent in a GET request.
For example, if you wish to capture the URL "https://www.example.com?q=hello&page=2" you would need to URL encode this to become https%3A%2F%2Fwww.example.com%3Fq%3Dhello%26page%3D2
If you are still not 100% sure you can find more information about URL encoding here https://www.w3schools.com/tags/ref_urlencode.ASP
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. |
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
The no_hyperlinks
parameter is a boolean integer value and
allows you to request the resulting PDF document to be generated without any active hyperlinks
in the content.
If set to 1 then any hyperlinks will be deactivated and not clickable.
This can be set to 1 or 0.
By default, this is set to 0 so hyperlinks will be active and clickable in the PDF.
https://pdfzoneapi.com/api/v1/convert?access_key=YOUR_ACCESS_KEY&document_url=https://pdfzoneapi.com&no_hyperlinks=1
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
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
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
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
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
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
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
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
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
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
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
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
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
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.
If the css_url
parameter contains any
special characters such as & or ? then it must be url
encoded.
For example, if you wish to capture the URL "https://www.example.com/css.css?v=1" you would need to URL encode this to become https%3A%2F%2Fwww.example.com%2Fcss.css%3Fv%3D1
If you are still not 100% sure you can find more information about URL encoding here https://www.w3schools.com/tags/ref_urlencode.ASP
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
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
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
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
There are two different types of custom header elements that can be included in a PDF document:
A custom header HTTP URL (header_url
) or raw HTML element
(header_html
).
By default, these are not set.
https://pdfzoneapi.com/api/v1/convert?access_key=YOUR_ACCESS_KEY&document_url=https://pdfzoneapi.com&header_url=https://pdfzoneapi.com/header_url.html
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
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
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