Customizing the PDF

ND
Last updated 2 months ago

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

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.

Form data
JSON

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"
}

This is an example of submitting parameters as a JSON object, again 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"
}

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

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)