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.
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
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.
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
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 »
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
.
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.
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]"
}
}
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. |
104 |
"usage_limit_reached" |
User has reached or exceeded his Subscription Plan's monthly API Request Allowance. |
106 |
"rate_limit_reached" |
User has exceeded the maximum allowed rate limitation and is referred to the "Rate Limits" section of the API Documentation. |
102 |
"inactive_user" |
The user's account is not active. User will be prompted to get in touch with Customer Support. |
312 |
"document_url_not_found" |
The specified document URL could not be found [Status: 404]. |
313 |
"missing_document_source" |
User did not specify a document source. User will be prompted to specify either document_url or document_html |
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] »
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.
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.
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 |
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 |
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 »
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.
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 |
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 |
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.
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 |
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 | - |
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 | - |
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 | - |
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 |
- |
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 |
- |
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 |
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 | - |
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 |
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 |
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.
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 |
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 | - |
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.
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 |
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 | - |
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 [...]
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 |
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 [...]
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) | - |
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 |
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 | - |
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 |
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 [...]
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%) |
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 |
- |
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 | - |
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 | - |
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 |
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 | - |
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); |
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].
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.
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 |
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.
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.
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.
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.
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.
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.
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.
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!