Quickstart Guide
The PDFlayer API is extremely easy to use. It only takes a few lines of code to make your first validation request. All registered users, whether on a free or paid plan, can use our Quickstart Guide to explore the full range of API functionalities with just one click.
- Existing users: Access the Quickstart Guide below.
- New users: Create an account and get started in minutes.
To ensure maximum compatibility with any existing programming language, the PDFlayer API uses simple HTTP requests with URLs. The following steps outline, in the most basic terms, how an API request is built.
Step 1: Get Your API Access Key
Sign up for a free PDFlayer account at pdflayer.com and obtain your personal API Access Key.
This key authenticates your requests and ensures that you have access to the API features provided by your subscription plan.
Step 2: Base URL
Each API request is based on the following URL:
Step 3: 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 4: Optional Parameters
In addition to the few required parameters, there is a set of functionalities and parameters that can be used to fully configure and customize your PDF document.
Find below a summary: Configuration
| 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] | - |
Find below a summary: Layout
| Parameter | Description | Default |
|---|---|---|
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 |
Find below a summary: Customization
| Parameter | Description | Default |
|---|---|---|
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] | - |
Find below a summary: Document Details
| Parameter | Description | Default |
|---|---|---|
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 uses some of the above optional parameters to convert a standard HTML invoice to a PDF.
URL Encoding
Strictly speaking, it is always safer to URL-encode the URL before passing it into any API parameter. 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.
Example query:
This is how the example URL above has to be passed into an API request:
Not sure about URL encoding? Have a look at this reference page »