API Documentation

pdflayer API

The pdflayer API was built to provide a quick and seamless way to automate HTML to PDF conversion in any application. Its lightweight RESTful infrastructure is based on an efficient combination of the most powerful PDF rendering engines available, making it the most cost-effective and reliable option for anyone looking to process small or large numbers of documents within short time windows.

The pdflayer API comes with a full set of customization functionalities, including document configuration, a series of layout adjustment options, authentication and security, design and branding tweaks, and much more.

The following documentation intends to outline in detail the pdflayer API's specification, access and use of any features and parameters currently available.


Access & Specification

API Access Key & Authentication

After signing up, every user is assigned a personal API Access Key - a unique "password" used to make requests to the pdflayer API.

To authenticate with the pdflayer API, simply attach your access_key to the base endpoint URL:

http://api.pdflayer.com/api/convert?access_key=YOUR_ACCESS_KEY  
                

Get your free API Access Key


HTTP GET & POST

The pdflayer API and its functionalities are primarily configured to be used via HTTP POST. For customers looking to make API requests via HTTP GET the pdflayer API is also capable of handling GET API requests using its straightforward URL structure.

However, some API functionalities are not supported using HTTP GET. Throughout this documentation you will occasionally come across HTTP POST only tags, indicating that the respective API feature or parameter is only supported via HTTP POST.


3-Step Quickstart Guide

For maximum compatibility with any existing programming language the pdflayer API is based on simple URL-based HTTP requests. The next three steps will outline in the most basic fashion how an API request is built.


Step 1: Base URL

Each API request is based at the following URL:

http://api.pdflayer.com/api/convert
                


Step 2: Required parameters

Simply authenticate with the API by appending your access_key and providing either a URL using the document_url parameter or raw HTML code using the document_html parameter.


Parameter Description
access_key Key used to authenticate with the API - find it in your Account Dashboard
document_url The full URL (including the HTTP Protocol) of the website you want to convert to a PDF document, e.g. http://example.com/invoice.html
document_html HTTP POST only - raw HTML code you would like to convert to a PDF document.


Step 3: Optional parameters

In addition to the few required parameters, there is a series of functionalities and parameters that can be used to fully configure and customize your PDF document. Find below a summary:


Parameter Description Default
document_name specify a PDF name of up to 180 characters. pdflayer.pdf
custom_unit set to px (Pixels), pt (Points), in (Inches) or mm (Millimeters) px
user_agent set to your preferred User-Agent header string See below
accept_lang set to your preferred Accept-Language header string en-US
text_encoding set to your preferred text encoding string utf-8
ttl the time (in seconds) a generated PDF is cached 2,592,000
force set to 1 to force new PDF -
inline set to 1 to display PDF document inline Attachment, triggers download
auth_user specify username used to access password-protected site -
auth_pass specify password used to access password-protected site -
encryption set to 40 (40-bit) or 128 (128-bit) -
owner_password specify owner password to password protect PDF -
user_password specify user password to password protect PDF -
Misc Options a series of configuration options [Learn more] -
Permissions a series of permission options [Learn more] -
page_size set to preferred page size, e.g. A4, A5, etc. A4
page_width specify page width (numeric), e.g. 200 (overrides page_size) A4 width
page_height specify page height (numeric), e.g. 600 (overrides page_size) A4 height
orientation set to portrait or landscape portrait
margin_top set to preferred top margin value (numeric), e.g. 5 -
margin_bottom set to preferred bottom margin value (numeric), e.g. 5 -
margin_left set to preferred left margin value (numeric), e.g. 5 -
margin_right set to preferred right margin value (numeric), e.g. 5 -
header_spacing set to preferred header spacing value (numeric), e.g. 10 -
header_text set to preferred header text, e.g. This is my heading -
header_align set to left, center or right center
header_url set to (urlencoded) URL containing your preferred header HTML elements -
header_html HTTP POST only - specify raw HTML as header element -
footer_spacing set to preferred footer spacing value (numeric), e.g. 10 -
footer_text set to preferred footer text, e.g. This is my footer -
footer_align set to left, center or right center
footer_url set to (urlencoded) URL containing your preferred footer HTML elements -
footer_html HTTP POST only - specify raw HTML as footer element -
viewport Set to preferred viewport "width x height", e.g. 320x480 1440x900
css_url inject a custom CSS stylesheet using a (urlencoded) URL -
delay specify a delay (in seconds) before PDF is captured -
dpi specify the DPI resolution (numerical) between 10 and 10000 96
zoom specify page zoom factor between 0 and 50 -
watermark_url specify a watermark URL (urlencoded) containing a PNG or JPG image -
watermark_offset_x specify a horizontal watermark offset, e.g. 10 -
watermark_offset_y specify a vertical watermark offset, e.g. 10 -
watermark_opacity specify watermark opacity percentage (numeric) between 0 and 100 20
watermark_in_background set to 1 to place watermark behind text -
Page Numbering Page numbering options including dynamic tags [Learn more] -
title specify a PDF document title of max. 150 characters -
subject specify a PDF document subject of max. 150 characters -
creator specify a PDF document creator name of max. 150 characters pdflayer.com
author specify a PDF document author name of max. 150 characters -


Sample API request:


The following API request makes use of some of the above optional parameters in order to convert a standard HTML invoice to a PDF document.

http://api.pdflayer.com/api/convert
    ? access_key = YOUR_ACCESS_KEY
    & document_url = https://pdflayer.com/downloads/invoice.html
                


URL Encoding


Strictly speaking, it is always a safer method to URL encode URL before passing it into any of the API's parameters. However, URL encoding is required in case your the respective URL contains the special character &.

Example URLs:

Find below an example url that is required to be URL encoded in order to be processed correctly.

http://website.com?parameter=example&file=invoice.html
                

Example query:

This is how the example URL above has to be passed into an API request:

http://api.pdflayer.com/api/convert
    ? access_key = YOUR_ACCESS_KEY
    & document_url = http%3A%2F%2Fwebsite.com%3Fparameter%3Dexample%26file%3Dinvoice.html
    [...]
                

Not sure about URL encoding? Have a look at this reference page »


256-bit HTTPS Encryption

Customers subscribed to the Basic Plan and upwards may establish a secure connection (industry-standard SSL) to the pdflayer API, simply by attaching an s to the HTTP Protocol.

https://api.pdflayer.com/api/convert
                

Important: Please be advised that when processing sensitive data through third party services it is highly recommended to always connect securely via https.


Rate Limits

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

Subscription Plan Rate Limit
Free 2 Requests / Minute
Basic 30 Requests / Minute
Professional 45 Requests / Minute
Enterprise 45 Requests / Minute

Important: In order to ensure maximum API performance, we recommend Basic, Professional and Enterprise Plan users to limit their usage to a maximum of 1 API request per 2 seconds.

If your rate limit for a given minute has been exceeded, the API will return an error carrying the type rate_limit_reached. This error is listed in the API Error Codes section below.


API Error Codes

If your query fails, the pdflayer API will return "success": false, along with a 3-digit error-code, an internal error type and a plain text "info" object containing suggestions for the user.

Find below an example error - triggered when no URL was specified:

{
  "success": false,
  "error": {
    "code": 311,
    "type": "invalid_document_url",
    "info": "You have specified an invalid document URL. [Make sure to include the HTTP protocol - example: http://example.com/invoice.html]"    
  }
}
                


Common API errors:


Type Message Description
404 "404_not_found" User requested a resource which does not exist.
101 "missing_access_key" User did not supply an Access Key.
101 "invalid_access_key" User entered an invalid Access Key.
103 "invalid_api_function" User requested a non-existent API endpoint or function.
311 "invalid_document_url" User did not provide a syntactically valid document URL.

show more


Important: This list of errors is not conclusive. If you come across an error message you are not sure about, please contact support at [email protected] »


Sandbox Mode

For document testing and debugging the pdflayer API offers a Sandbox (testing) mode, enabling users to make API requests that do not count towards their monthly API request volume. To enter Sandbox mode, simply append the API's test parameter and set it to 1.

Example API Request:

https://api.pdflayer.com/api/convert
    ? access_key = YOUR_ACCESS_KEY
    & document_url = http://example.com/document.html
    & test = 1
    [...]
                

Please note: Sandbox API requests always come with a red "Sample" watermark image.


Secret Key

For users intending to expose API request URLs on their website, it is highly recommended to make use of the pdflayer API's URL encryption method, which lets you generate a unique Secret Key for every API request and simply append it to the respective API request URL.

In order to prevent your publicly displayed API request URL from being abused, please follow the steps below:

Step 1: Define your document URL

First of all, define the URL of the website you want to generate a PDF from.

In our example we will use the following URL:

http://example.com/document.html
                

Step 2: Define your Secret Keyword

A Secret Keyword can be any secret word or phrase of your choice. As the next step, please make sure you have defined it in your account dashboard. If not, you can simply add a secret keyword here.

In our example we will use the following Secret Keyword:

mysecretkeyword
                

Step 3: Combine

Now you will need to combine these two parts (URL & secret keyword) into one, resulting in:

http://example.com/document.htmlmysecretkeyword
                

Step 4: Generate your md5 Secret Key

Finally, create an md5 hash of the combined parts. (this will be your secret_key)

2fc63a2144965d3695bf370011cdc9fb
                

Now that you have your Secret Key, you can simply append to your API request URL using the API's secret_key parameter and rest assured that your API access is - as long as you'll keep your Secret Keyword secret - safe from abuse.

Sample API Request:

https://api.pdflayer.com/api/convert
    ? access_key = YOUR_ACCESS_KEY
    & document_url = http://example.com/document.html
    & secret_key = 2fc63a2144965d3695bf370011cdc9fb
    [...]
                

Important: Please note that as long a Secret Keyword is specified in your Account Dashboard it the use of the document_html parameter is not possible.


Document Configuration

Document Name

By default, PDF documents generated by the pdflayer API are named pdflayer.pdf. Using the API's document_name parameter you can specify a custom name for your final PDF document.

Example API Request:

https://api.pdflayer.com/api/convert
    ? access_key = YOUR_ACCESS_KEY
    & document_url = http://example.com/document.html
    & document_name = MyPDF
    [...]
                

Parameter specification:


Parameter Condition Default
document_name Max. 180 characters pdflayer.pdf


Document Units

The default document unit is px. A custom unit can be specified by appending the API's custom_unit parameter and setting it to one of the four supported document units.

Example API Request:

https://api.pdflayer.com/api/convert
    ? access_key = YOUR_ACCESS_KEY
    & document_url = http://example.com/document.html
    & custom_unit = mm
    [...]
                

Parameter specification:


Parameter Supported Units Default
custom_unit mm, in, px, pt px


HTTP User-Agent Header

The API's user_agent parameter is used to adjust the final PDF document to a certain device setting. In many cases this parameter is used to ensure more consistent functionality of the Viewport Control feature.

In order to specify a custom HTTP User-Agent header, simply append the respective User-Agent string to the user_agent parameter.

Example API Request:

https://api.pdflayer.com/api/convert
    ? access_key = YOUR_ACCESS_KEY
    & document_url = http://example.com/document.html
    & user_agent = Mozilla/5.0 (Windows NT 6.1; WOW64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/42.0.2311.135 Safari/537.36    
    [...]
                

Common HTTP User-Agent Headers:


System UA String
Chrome Generic Win7 64-bit Mozilla/5.0 (Windows NT 6.1; WOW64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/42.0.2311.135 Safari/537.36
Chrome Generic MacOSX Mozilla/5.0 (Macintosh; Intel Mac OS X 10_10_3) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/42.0.2311.135 Safari/537.36
Safari 8.0 MacOSX Mozilla/5.0 (Macintosh; Intel Mac OS X 10_10_3) AppleWebKit/600.6.3 (KHTML, like Gecko) Version/8.0.6 Safari/600.6.3
Firefox Generic Win7 64-bit Mozilla/5.0 (Windows NT 6.1; WOW64; rv:37.0) Gecko/20100101 Firefox/37.0

Find a detailed list of HTTP User-Agent headers here »


HTTP Accept-Language Header

By default, PDF documents processed by the pdflayer API don't come with a specific HTTP Accept-Language header. An Accept-Language header can be specified by appending the respective string to the API's accept_lang parameter.

Example API Request:

https://api.pdflayer.com/api/convert
    ? access_key = YOUR_ACCESS_KEY
    & document_url = http://example.com/document.html
    & accept_lang = en-US
    [...]
                

Common HTTP Accept-Language Headers:


Language Accept-Language String
English (general) en
German de
Spanish es
Italian it
English (US) en-US
English (UK) en-GR
Spanish (Spain) es-ES
Spanish (Mexico) es-MX

You can find a comprehensive list of accept-language strings here.


Text Encoding

By default, pdflayer API requests come with a standard UTF-8 text encoding header. A custom text encoding header can be specified simply by appending the respective text encoding string to the API's text_encoding parameter.

Example API Request:

https://api.pdflayer.com/api/convert
    ? access_key = YOUR_ACCESS_KEY
    & document_url = http://example.com/document.html
    & text_encoding = utf-16
    [...]
                

Parameter specification:


Parameter Condition Default
text_encoding - UTF-8


TTL (Caching Time)

By default, generated PDFs are cached for a period of 30 days (2,592,000 seconds). Using the API's ttl parameter you can specify a custom caching time (in seconds) lower than the default setting.

The example API query below requests the final PDF to be cached for 259,200 seconds (3 days).

Example API Request:

https://api.pdflayer.com/api/convert
    ? access_key = YOUR_ACCESS_KEY
    & document_url = http://example.com/document.html
    & ttl = 259200
    [...]
                

Parameter specification:


Parameter Condition Default
ttl Maximum value: 2592000 2592000


Force New PDF

As mentioned earlier, by default PDF documents are cached for 30 days upon creation. (Learn more about TTL - Caching Time)

By setting the pdflayer API's force parameter to 1 the API will be requested to generate a new PDF each time the API request URL is called.

Example API Request:

https://api.pdflayer.com/api/convert
    ? access_key = YOUR_ACCESS_KEY
    & document_url = http://example.com/document.html
    & force = 1
    [...]
                

Please note: Each call of an API request URL including the force functionality counts towards your monthly API request volume.


Inline/Attachment Parameter

By default, accessing a pdflayer API request URL in a browser will trigger the download of the generated PDF (attachment behaviour). By setting the API's inline parameter to 1 the API will be requested to display the PDF in the browser instead (inline behaviour).

Example API Request:

https://api.pdflayer.com/api/convert
    ? access_key = YOUR_ACCESS_KEY
    & document_url = http://example.com/document.html
    & inline = 1
    [...]
                

Parameter specification:


Parameter Condition Default
inline - Deactivated - Attachment, triggering download


Password-Protected Sites

The pdflayer API is also capable of generating PDFs from password-protected websites. The parameters auth_user and auth_pass are used to authenticate with a password-protected website.

Example API Request:

https://api.pdflayer.com/api/convert
    ? access_key = YOUR_ACCESS_KEY
    & document_url = http://example.com/document.html
    & auth_user = myUsername
    & auth_pass = myPassword
    [...]
                

Parameter specification:


Parameter Condition Default
auth_user Maximum: 1,000 characters -
auth_pass Maximum: 1,000 characters -


PDF Encryption

There are two encryption levels available for PDFs generated by the pdflayer API: 40-bit and 128-bit. In order to activate encryption, set the API's encryption parameter to 40 or 128.

Example API Request:

https://api.pdflayer.com/api/convert
    ? access_key = YOUR_ACCESS_KEY
    & document_url = http://example.com/document.html
    & encryption = 128
    [...]
                

Parameter specification:


Parameter Supported Encryption Levels Default
encryption 40, 128 -


PDF Authentication

The pdflayer API offers two levels of PDF password protection: owner password and user password. These can be specified by appending the owner_password and/or user_password parameter(s) and setting them to their respective password value.

Supplying an owner password grants unlimited access to the PDF including changing the passwords and Permission Options. A user password, on the other hand, must be supplied in order to view the document and to perform operations allowed by the Permission Options.

Example API Request:

https://api.pdflayer.com/api/convert
    ? access_key = YOUR_ACCESS_KEY
    & document_url = http://example.com/document.html
    & owner_password = myOwnerPassword
    & user_password = myUserPassword
    [...]
                

Parameter specification:


Parameter Supported Encryption Levels Default
owner_password Maximum: 32 characters -
user_password Maximum: 32 characters -


Misc Options

In addition to the above mentioned document configuration parameters, there is a series of extra settings that can be specified for final PDF document. Please find them in the table below:

Example API Request:

https://api.pdflayer.com/api/convert
    ? access_key = YOUR_ACCESS_KEY
    & document_url = http://example.com/document.html
    & no_hyperlinks = 1
    & grayscale = 1
    [...]
                

Parameter specification:


Parameter Description Default
no_images Set to 1 in order to disable images -
no_hyperlinks Set to 1 in order to disable hyperlinks -
no_backgrounds Set to 1 in order to disable CSS backgrounds -
no_javascript Set to 1 in order to disable JavaScript -
use_print_media Set to 1 in order to activate CSS @media print declarations -
grayscale Set to 1 in order to remove all colours -
low_quality Set to 1 in order to generate low quality PDF -
forms Set to 1 in order to enable forms on your PDF -


Permission Options

There is a number of permission options that can be configured prior to generating a PDF using the pdflayer API. After creating the PDF, these options can only be altered or disabled by a user supplying an owner password. Learn more about PDF Authentication »

Please note that the specification of at least one of the following parameters is required in order to be able to configure permission options: owner_password, user_password or encryption

Example API request using permission options:

https://api.pdflayer.com/api/convert
    ? access_key = YOUR_ACCESS_KEY
    & document_url = http://example.com/document.html
    & encryption = 128
    & no_print = 1
    & no_modify = 1
    & no_copy = 1
    [...]
                

Parameter specification:


Parameter Description Default
no_print Set to 1 in order to disable printing of the final PDF document -
no_modify Set to 1 in order to disable modification of the final PDF document -
no_copy Set to 1 in order to disable the possibility to copy any text of the final PDF document -


Layout

Preconfigured Page Sizes

By default, a PDF's page size is set to A4. Using the API's page_size parameter a custom page size can be specified. Please find in the table below all page sizes supported by the pdflayer API.

Example API Request:

https://api.pdflayer.com/api/convert
    ? access_key = YOUR_ACCESS_KEY
    & document_url = http://example.com/document.html
    & page_size = A5
    [...]
                

Supported page sizes:


Type Sizes
A A0, A1, A2, A3, A4, A5, A6, A7, A8, A9
B B0, B1, B2, B3, B4, B5, B6, B7, B8, B9
Other C5E, Comm10E, DLE, Executive, Folio, Ledger, Legal, Letter, Tabloid


Dimensions

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

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

Example API Request:

https://api.pdflayer.com/api/convert
    ? access_key = YOUR_ACCESS_KEY
    & document_url = http://example.com/document.html
    & page_width = 200
    & page_height = 500
    [...]
                

Parameter specification:


Parameter Condition Default
page_width numeric -
page_height numeric -


Orientation

By default, a PDF's orientation is set to portrait. Using the API's orientation parameter the PDF document's orientation can be set to either portrait or landscape.

Example API Request:

https://api.pdflayer.com/api/convert
    ? access_key = YOUR_ACCESS_KEY
    & document_url = http://example.com/document.html
    & orientation = landscape
    [...]
                

Parameter specification:


Parameter Supported Orientation Modes Default
orientation portrait, landscape portrait


Margins

A PDF's default margin is set to 10 millimeters on each side. Using the parameters margin_top, margin_bottom, margin_left and margin_right vertical and horizontal margins (in the selected Document Unit) can be specified.

Example API Request:

https://api.pdflayer.com/api/convert
    ? access_key = YOUR_ACCESS_KEY
    & document_url = http://example.com/document.html
    & margin_top = 0
    & margin_bottom = 0
    & margin_left = 0
    & margin_right = 0
    [...]
                

Parameter specification:


Parameter Condition Default
margin_top numeric 10mm
margin_bottom numeric 10mm
margin_left numeric 10mm
margin_right numeric 10mm


Header

There are two different types of custom header elements that can be included in a PDF document: A header text or a custom header HTTP URL or raw HTML element.

Header Text

A simple header text can be specified by appending the pdflayer API's header_text parameter to your API request URL and setting it to your preferred header text. By default, this header text is aligned at the center of the document. The API's header_align parameter enables you to specify a custom header alignment, choosing from left, right or center.

Example API Request:

https://api.pdflayer.com/api/convert
    ? access_key = YOUR_ACCESS_KEY
    & document_url = http://example.com/document.html
    & header_text = myHeaderText
    & header_align = left
    [...]
                

Parameter specification:


Parameter Condition Default
header_text - -
header_align center, left or right center


Header URL or Raw HTML Element

As an alternative to specifying a header text, the pdflayer API is also capable of including the HTML contents of an external HTTP URL or raw HTML code as a header element in your final PDF document.

Example API Request using a HTTP header URL:

https://api.pdflayer.com/api/convert
    ? access_key = YOUR_ACCESS_KEY
    & document_url = http://example.com/document.html
    & header_url = http://example.com/myHeader.html
    [...]
                

Parameter specification:


Parameter Condition Default
header_url HTTP GET & or HTTP POST -
header_html HTTP POST only -


Header Spacing


By default, there is no extra space between a header element and the PDF document content. A header spacing can be specified by appending your preferred numeric value to the API's header_spacing parameter.

Example API Request using a HTTP header URL:

https://api.pdflayer.com/api/convert
    ? access_key = YOUR_ACCESS_KEY
    & document_url = http://example.com/document.html
    & header_text = myHeaderText
    & header_spacing = 15
    [...]
                

Just like with the PDF Header, there are two different types of custom footer elements that can be included in a PDF document: A footer text or a custom footer HTTP URL or raw HTML element.

Footer Text

A simple footer text can be specified by appending the pdflayer API's footer_text parameter to your API request URL and setting it to your preferred footer text. By default, this footer text is aligned at the center of the document. The API's footer_align parameter enables you to specify a custom footer alignment, choosing from left, right or center.

Example API Request:

https://api.pdflayer.com/api/convert
    ? access_key = YOUR_ACCESS_KEY
    & document_url = http://example.com/document.html
    & footer_text = myFooterText
    & footer_align = left
    [...]
                

Parameter specification:


Parameter Condition Default
footer_text - -
footer_align center, left or right center


Footer URL or Raw HTML Element

As an alternative to specifying a footer text, the pdflayer API is also capable of including the HTML contents of an external HTTP URL or raw HTML code as a footer element in your final PDF document.

Example API Request using a HTTP footer URL:

https://api.pdflayer.com/api/convert
    ? access_key = YOUR_ACCESS_KEY
    & document_url = http://example.com/document.html
    & footer_url = http://example.com/myFooter.html
    [...]
                

Parameter specification:


Parameter Condition Default
footer_url HTTP GET & or HTTP POST -
footer_html HTTP POST only -


Footer Spacing


By default, there is no extra space between a footer element and the PDF document content. A footer spacing can be specified by appending your preferred numeric value to the API's footer_spacing parameter.

Example API Request using a HTTP footer URL:

https://api.pdflayer.com/api/convert
    ? access_key = YOUR_ACCESS_KEY
    & document_url = http://example.com/document.html
    & footer_text = myFooterText
    & footer_spacing = 15
    [...]
                

Viewport Control

The pdflayer API's default viewport setting is 1440x900. You can specify a custom viewport size by setting the viewport parameter to your desired dimensions. (format: width x height, in pixels)

Important: When requesting mobile-sized viewports, it is highly recommended to also specify a user_agent parameter, as certain websites tend to ignore mobile viewports that come without specified HTTP User-Agent headers (See User-Agent parameter).

Example API request using permission options:

https://api.pdflayer.com/api/convert
    ? access_key = YOUR_ACCESS_KEY
    & document_url = http://example.com/document.html
    & viewport = 320x480
    [...]
                

Parameter specification:


Device Viewport
iPhone 4 (s) 320x480
iPhone 5 (c/s) 320x568
iPhone 6 375x667
iPhone 6 Plus 414x736
iPad (2/Mini/Retina) 1024x768
Samsung Galaxy S3, S4, S5 360x640
Macbook 13" 1440x900
iMac 27" 2560x1440


Customization

CSS Injection

By appending an HTTP URL containing valid CSS code to the API's css_url parameter custom styles can be injected into the target URL/HTML before a PDF conversion is performed.

The sample API request below contains a link to an example CSS StyleSheet containing the following declaration:

body {
	background: #00ff00 !important;
}
                

Example API Request:

https://api.pdflayer.com/api/convert
    ? access_key = YOUR_ACCESS_KEY
    & document_url = http://example.com/document.html
    & css_url = https://pdflayer.com/downloads/css_inject.css
    [...]
                

Delay

The pdflayer API's delay parameter enables you to specify a custom delay time (in milliseconds) before the PDF is generated. This feature may be useful if certain contents of the target website appear after the initial page load. (e.g. CSS animations, JavaScript effects, etc.)

Example API Request:

https://api.pdflayer.com/api/convert
    ? access_key = YOUR_ACCESS_KEY
    & document_url = http://example.com/document.html
    & delay = 1000
    [...]
                

Parameter specification:


Parameter Supported Delay Range Default
delay 10 < 20000 (0.01 seconds < 20 seconds) -


DPI Resolution

By default, PDFs are generated with an overall DPI (Dots Per Inch) of 96. A custom overall DPI resolution can be specified by appending the API's dpi parameter and setting it to your preferred numerical DPI value.

Example API Request:

https://api.pdflayer.com/api/convert
    ? access_key = YOUR_ACCESS_KEY
    & document_url = http://example.com/document.html
    & dpi = 1000
    [...]
                

Parameter specification:


Parameter Supported DPI Range Default
dpi 10 < 10000 96


Zoom Factor

By default, PDF document content is generated according to the size and dimensions of the original URL/HTML content. Using the API's zoom parameter a custom HTML zoom factor between 0 and 50 can be specified.

Example API Request:

https://api.pdflayer.com/api/convert
    ? access_key = YOUR_ACCESS_KEY
    & document_url = http://example.com/document.html
    & zoom = 1
    [...]
                

Parameter specification:


Parameter Supported Zoom Range Default
zoom 0 < 50 -


Page Numbering

The pdflayer API offers a series of pre-composed page numbering tags that can be used to compile custom header or footer numbering texts. Each of the page numberng tags listed in the table below can be used in combination with the header_text or footer_text parameters.

Example API Request:

https://api.pdflayer.com/api/convert
    ? access_key = YOUR_ACCESS_KEY
    & document_url = http://example.com/document.html
    & header_text = This is page number [page] of [sitepages]  
    [...]
                

Supported page numbering tags:


Tag Description
[page] Number of the page currently being printed
[frompage] Number of the first page to be printed
[topage] Number of the last page to be printed
[webpage] URL of the webpage being printed
[date] Current date in system local format
[isodate] Current date in ISO 8601 extended format
[time] Current time in system local format
[title] Title of the current page object
[doctitle] Title of the output document
[sitepage] Number of the page in the current site being converted
[sitepages] Number of pages in the current site being converted


Page Numbering Offset


By default, the pdflayer API's page numbering offset is set to 0, which means that page numbering starts on the first printed page of the PDF document.

A custom page numbering offset can be specified by appending the API's page_numbering_offset and setting it to the number of pages to be skipped before page numbering begins.

Example API Request:

https://api.pdflayer.com/api/convert
    ? access_key = YOUR_ACCESS_KEY
    & document_url = http://example.com/document.html
    & page_numbering_offset = 1
    [...]
                

Watermark

The pdflayer API offers the possibility to use 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.

Watermark Opacity

A watermark's default opacity is set to 20 (20%). Using the API's watermark_opacity parameter a custom numeric opacity value can be configured.

Example API Request:

https://api.pdflayer.com/api/convert
    ? access_key = YOUR_ACCESS_KEY
    & document_url = http://example.com/document.html
    & watermark_url = http://example.com/watermark.png  
    & watermark_opacity = 25  
    [...]
                

Parameter specification:


Parameter Condition Default
watermark_url Supported image formats: PNG, JPG -
watermark_opacity numeric 20 (20%)


Watermark Positioning


By default, watermark images are aligned at the top left of the page. Two parameters are offered that can be used to horizontally and vertically align a watermark image: watermark_offset_x and watermark_offset_y.

Watermark Placement

By default, watermark images are placed in front of the PDF document's content (texts, images, etc.). By setting the API's watermark_in_background to 1 watermark images will be placed in the PDF document's background.

Example API Request:

https://api.pdflayer.com/api/convert
    ? access_key = YOUR_ACCESS_KEY
    & document_url = http://example.com/document.html
    & watermark_url = http://example.com/watermark.png
    & watermark_offset_x = 15  
    & watermark_offset_y = 30  
    [...]
                

Parameter specification:


Parameter Condition Default
watermark_offset_x numeric -
watermark_offset_y numeric -
watermark_in_background Set to 1 to activate -


Document Details

Document Title

A PDF document title can be specified by appending the API's title parameter and setting it to your preferred title.

Example API Request:

https://api.pdflayer.com/api/convert
    ? access_key = YOUR_ACCESS_KEY
    & document_url = http://example.com/document.html
    & title = MyTitle
    [...]
                

Parameter specification:


Parameter Condition Default
title Maximum: 150 characters -


Subject

A PDF document subject can be specified by appending the API's subject parameter and setting it to your preferred subject.

Example API Request:

https://api.pdflayer.com/api/convert
    ? access_key = YOUR_ACCESS_KEY
    & document_url = http://example.com/document.html
    & subject = MySubject
    [...]
                

Parameter specification:


Parameter Condition Default
subject Maximum: 150 characters -


Document Creator

By default, PDFs generated by the pdflayer API will carry the creator name pdflayer.com. A custom PDF document creator name can be specified by appending the API's creator parameter and setting it to your preferred creator name.

Example API Request:

https://api.pdflayer.com/api/convert
    ? access_key = YOUR_ACCESS_KEY
    & document_url = http://example.com/document.html
    & creator = MyCreatorName
    [...]
                

Parameter specification:


Parameter Condition Default
creator Maximum: 150 characters pdflayer.com


Document Author

A PDF document author name can be specified by appending the API's author parameter and setting it to your preferred author name.

Example API Request:

https://api.pdflayer.com/api/convert
    ? access_key = YOUR_ACCESS_KEY
    & document_url = http://example.com/document.html
    & author = MyAuthorName
    [...]
                

Parameter specification:


Parameter Condition Default
author Maximum: 150 characters -


Language Examples

PHP

This is an integration guide for a PHP cURL-based PHP class built to simplify the use the pdflayer API in PHP. In order to get started as quickly as possible, please follow the steps below:

Installation:


1. Click here to download the compressed PHP class ("pdflayer.class.php.zip").

2. Upload the contained PHP class file ("pdflayer.class.php") to a web accessible location on your server (e.g. "public_html").

Configuration:


3. In the PHP class, set the variable access_key to your API access key and (optional; only if you are using a Secret Key) the variable secret_keyword to your Secret Keyword.

Usage:


Find below the most basic use of the pdflayer PHP class. All available methods are listed in the table below.

include('../pdflayer.class.php');

//Instantiate the class
$html2pdf = new pdflayer();

//set the URL to convert
$html2pdf->set_param('document_url','https://pdflayer.com/downloads/invoice.html');

//start the conversion
$html2pdf->convert();

//display the PDF file
$html2pdf->display_pdf();
                

Methods:


Method Description Syntax
display_pdf Display the PDF (inline-behaviour) display_pdf();
download_pdf Download the PDF (attachment-behaviour) download_pdf('file_name.pdf');
set_param Specify any pdflayer API parameter set_param(string key, string value);


Help / Support


Any issues with API Integration? Be sure to take a look at our Frequently Asked Questions to see if your question has already been answered.

If there is still something you need assistance with, please get in touch with our support team at [email protected].


Business Continuity - API Overages

Ensuring our customers achieve success is paramount to what we do at APILayer. For this reason, we will be rolling out our Business Continuity plan guaranteeing your end users will never see a drop in coverage. Every plan has a certain amount of API calls that you can make in the given month. However, we would never want to cut your traffic or impact user experience negatively for your website or application in case you get more traffic.

What is an overage?

An overage occurs when you go over a quota for your API plan. When you reach your API calls limit, we will charge you a small amount for each new API call so we can make sure there will be no disruption in the service we provide to you and your website or application can continue running smoothly.

Prices for additional API calls will vary based on your plan. See table below for prices per call and example of an overage billing.

Plan Name Monthly Price Number of Calls Overage Price per call Overage Total price
Basic $9.99 1,000 0.014985 1500 $32.47
Professional $39.99 10,000 0.0059985 12,000 $111.97
Enterprise $119.99 100,000 0.00179985 20,000 $155.99

Why does APILayer have overage fees?

Overage fees allow developers to continue using an API once a quota limit is reached and give them time to upgrade their plan based on projected future use while ensuring API providers get paid for higher usage.

How do I know if I will be charged for overages?

When you are close to reaching your API calls limit for the month, you will receive an automatic notification (at 75%, 90% and 100% of your monthly quota). However, it is your responsibility to review and monitor for the plan’s usage limitations. You are required to keep track of your quota usage to prevent overages. You can do this by tracking the number of API calls you make and checking the dashboard for up-to-date usage statistics.

How will I be charged for my API subscription?

You will be charged for your monthly subscription plan, plus any overage fees applied. Your credit card will be billed after the billing period has ended.

What happens if I don’t have any overage fees?

In this case, there will be no change to your monthly invoice. Only billing cycles that incur overages will see any difference in monthly charges. The Business Continuity plan is an insurance plan to be used only if needed and guarantees your end users never see a drop in coverage from you.

What if I consistently have more API calls than my plan allows?

If your site consistently surpasses the set limits each month, you may face additional charges for the excess usage. Nevertheless, as your monthly usage reaches a certain threshold, it becomes more practical to consider upgrading to the next plan. By doing so, you ensure a smoother and more accommodating experience for your growing customer base.

I would like to upgrade my plan. How can I do that?

You can easily upgrade your plan by going to your Dashboard and selecting the new plan that would be more suitable for your business needs. Additionally, you may contact your Account Manager to discuss a custom plan if you expect a continuous increase in usage.


Introducing Platinum Support - Enterprise-grade support for APILayer

Upgrade your APIlayer subscription with our exclusive Platinum Support, an exceptional offering designed to enhance your business’ API management journey. With Platinum Support, you gain access to a host of premium features that take your support experience to a whole new level.

What does Platinum Support include?

Standard Support Platinum Support
General review on the issue
Access to knowledge base articles
Email support communication
Regular products updates and fixes
Dedicated account team
Priority Email Support with unlimited communication
Priority bug and review updates
Option for quarterly briefing call with product Management
Features requests as priority roadmap input into product

Priority Email Support: Experience unrivaled responsiveness with our priority email support. Rest assured that your inquiries receive top-priority attention, ensuring swift resolutions to any issues.

Unlimited Communication: Communication is key, and with Platinum Support, you enjoy unlimited access to our support team. No matter how complex your challenges are, our experts are here to assist you every step of the way.

Priority Bug Review and Fixes: Bugs can be a headache, but not with Platinum Support. Benefit from accelerated bug review and fixes, minimizing disruptions and maximizing your API performance.

Dedicated Account Team: We understand the value of personalized attention. That's why Platinum Support grants you a dedicated account team, ready to cater to your specific needs and provide tailored solutions.

Quarterly Briefing Call with Product Team: Stay in the loop with the latest updates and insights from our Product team. Engage in a quarterly briefing call to discuss new features, enhancements, and upcoming developments.

Priority Roadmap Input: Your input matters! As a Platinum Support subscriber, your feature requests receive top priority, shaping our product roadmap to align with your evolving requirements.

Don't settle for the standard when you can experience the exceptional. Upgrade to Platinum Support today and supercharge your APIlayer experience!