Customizing the PDF

Last updated 28 days ago

Learn how to set margins, headers, footers and other options.

Job parameters
When creating jobs, the following parameters are available to customize the PDF output.
You can set these parameters either as form data or as a JSON object in the body of the request.
JSON
Form data
This is an example of submitting parameters as a JSON object, using the curl command line tool. This example uses an external file - body.json - which contains the API parameters as JSON-formatted data.
body.json
{
  "url": "https://en.wikipedia.org/wiki/Airplane",
  "footer_template": "<div style=\"width=100%; font-size: 12px; text-align: center\">Page <span class=\"pageNumber\"></span> of <span class=\"totalPages\"></span></div>",
  "margin_bottom": "2cm"
}
curl -u myapp-api-key: \
  --data @body.json \
  --header "Content-Type: application/json" \
  https://api.paperplane.app/jobs
​
{
  "id": "29d89d2f-1a4f-4bcc-a2ff-16ca6e90e635",
  "url": "https://en.wikipedia.org/wiki/Airplane",
  "status": "queued",
  "done": false,
  "object": "job"
}
Here's how you might use curl to make a request using form data from the command line:
$ curl -u myapp-api-key: https://api.paperplane.app/jobs \
  -d url="https://en.wikipedia.org/wiki/Airplane" \
  -d margin_top=0.5cm \
  -d margin_bottom=0.5cm \
  -d page_size=A4
​
{
  "id": "a43ad1ff-ee2a-4c32-b279-eef51cc46d12",
  "url": "https://en.wikipedia.org/wiki/Airplane",
  "status": "queued",
  "done": false,
  "object": "job"
}
Parameter name
Description
url (required)
The url parameter is required and is the web address that will be loaded and used to render the PDF.
landscape
Set this to “true” to use landscape orientation.
​
Default: false
margin_top
margin_right
margin_bottom
margin_left
Use these parameters to set the size of the page margins. The value must be a number and by default will be interpreted as inches. You can set a margin size in centimetres by suffixing the value with “cm”. For example, these are all valid margins:

1 (interpreted as 1 inch)
1.25 (interpreted as 1.25 inches)
1.25in
1.25cm
Default: 1cm
page_size
The page size can be set to one of the following values:
​
Letter
Legal
A3
A4
A5
Alternatively you can specify a custom page size. See the section on custom page sizes below to learn how to do this.
​
Default: Letter
header_template
footer_template
These parameters allow you to provide an HTML template that will be used to insert a header or footer on each page. Take a look at the header and footer templates guide for more information about setting up a template.
​
Default: No header or footer
wait_time
If the page content isn't immediately visible, you can instruct Paperplane to wait up to 20 seconds before generating the PDF. This delay will allow time for your content to fully load.
​
The wait_time value must be a number between 0 and 20.
​
Default: 0 (No wait time)
wait_css_selector
If the page content is not immediately visible, you can instruct Paperplane to wait for an element matching a specific CSS selector to be loaded.
​
This is an alternative to the wait_time option which gives you finer control over exactly when the PDF starts generating. You might find this useful if you have a single-page app or a page with a lot of dynamic content.
​
You can set wait_css_selector to any valid CSS selector - for example:
​
.container
body > .container
#main-content
Default: Not set (Does not wait for any matching element)
file_name
Sets a custom file name to use when uploading to S3. If not set, the PDF will be uploaded as [id].pdf - for example acf9e87a-ab9f-4340-986b-647c7db28b64.pdf.

Files can be placed in a directory structure by using / to separate directory names - for example Reports/Customer-1234/2019-01-01.pdf.

Note that if you use the same file name twice, the existing file will be overwritten.
​
Adding a .pdf extension to the file name isn't required, but is strongly recommended.
​
Default: [id].pdf
Custom page sizes
To use a custom page size, provide height and width values within the page_size parameter.
JSON
Form data
Here's an example of specifying a custom page size using JSON:
{
  "url": "https://en.wikipedia.org/wiki/Paper_size",
  "page_size": {
    "height": "10in",
    "width": "10in"
  }
}
Here's an example of using curl to set a custom page size:
$ curl -u myapp-api-key: https://api.paperplane.app/jobs \
  -d url="https://en.wikipedia.org/wiki/Paper_size" \
  -d "page_size[height]"="10in" \
  -d "page_size[width]"="10in"
Size units
You can specify page height or width in millimetres (mm) or inches (in). If you don't specify a unit, inches are assumed. For example, these are all valid heights or widths:
11.5in
8in
300mm
155mm
12 (interpreted as 12 inches)

API reference

Webhooks

Parameter name	Description
`url` (required)	The url parameter is required and is the web address that will be loaded and used to render the PDF.
`landscape`	Set this to “true” to use landscape orientation. Default: false
`margin_top` `margin_right` `margin_bottom` `margin_left`	Use these parameters to set the size of the page margins. The value must be a number and by default will be interpreted as inches. You can set a margin size in centimetres by suffixing the value with “cm”. For example, these are all valid margins: 1 (interpreted as 1 inch) 1.25 (interpreted as 1.25 inches) 1.25in 1.25cm Default: 1cm
`page_size`	The page size can be set to one of the following values: Letter Legal A3 A4 A5 Alternatively you can specify a custom page size. See the section on custom page sizes below to learn how to do this. Default: Letter
`header_template` `footer_template`	These parameters allow you to provide an HTML template that will be used to insert a header or footer on each page. Take a look at the header and footer templates guide for more information about setting up a template. Default: No header or footer
`wait_time`	If the page content isn't immediately visible, you can instruct Paperplane to wait up to 20 seconds before generating the PDF. This delay will allow time for your content to fully load. The `wait_time` value must be a number between 0 and 20. Default: 0 (No wait time)
`wait_css_selector`	If the page content is not immediately visible, you can instruct Paperplane to wait for an element matching a specific CSS selector to be loaded. This is an alternative to the `wait_time` option which gives you finer control over exactly when the PDF starts generating. You might find this useful if you have a single-page app or a page with a lot of dynamic content. You can set `wait_css_selector` to any valid CSS selector - for example: `.container` `body > .container` `#main-content` Default: Not set (Does not wait for any matching element)
`file_name`	Sets a custom file name to use when uploading to S3. If not set, the PDF will be uploaded as `[id].pdf` - for example `acf9e87a-ab9f-4340-986b-647c7db28b64.pdf`. Files can be placed in a directory structure by using `/` to separate directory names - for example `Reports/Customer-1234/2019-01-01.pdf`. Note that if you use the same file name twice, the existing file will be overwritten. Adding a `.pdf` extension to the file name isn't required, but is strongly recommended. Default: `[id].pdf`