Customizing the PDF

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.

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

Default: Letter

scale

Allows you to scale the size of the page content up or down. The minimum scale value is 0.1 and the maximum is 2.

Default: 1

screen

Set this to "true" to ignore any print styles on the page, and instead emulate the screen CSS media type.

Default: false

header_template

footer_template

Default: No header or footer

wait_network

Set this to "true" to cause Paperplane to wait until network activity has paused before generating the PDF.

This option is useful if you're using a client-side framework like React or Angular to build your document. When using client-side frameworks, PDFs can sometimes be captured too early and miss some content or images. By waiting until all network activity has stopped for a short period, it's usually possible to reliably generate the PDF once all page content has been loaded. Using this option is recommended if you're using any sort of client-side javascript framework.

Default: false

wait_network_time

For use in conjunction with wait_network. This option controls how many seconds of network inactivity is required before the PDF is captured.

The wait_network_time value must be a number between 0 and 20.

Default: 2 seconds (used if wait_network is set but this option is not)

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: 3 seconds

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

attachment

Setting this to "true" will result in the file being downloaded by the browser rather than displayed inline.

Default: false

username

If set, this username will be used if HTTP Basic Auth is requested.

Default: Not set

password

If set, this password will be used if HTTP Basic Auth is requested. If password is set, you must also provide a username.

Default: Not set

http_success

Setting this to "true" will result in the PDF conversion job failing (with the creation_failed status) if the HTTP response from the URL is in the 400 or 500 range. For example, 401, 404 etc.

Default: false

Custom page sizes

To use a custom page size, provide height and width values within the page_size parameter.

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)

PreviousAPI reference NextWebhooks

Last updated 3 years ago

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.

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

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 below to learn how to do this.

Default: Letter

scale

Allows you to scale the size of the page content up or down. The minimum scale value is 0.1 and the maximum is 2.

Default: 1

screen

Set this to "true" to ignore any print styles on the page, and instead emulate the screen CSS media type.

Default: false

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 for more information about setting up a template.

Default: No header or footer

wait_network

Set this to "true" to cause Paperplane to wait until network activity has paused before generating the PDF.

Default: false

wait_network_time

For use in conjunction with wait_network. This option controls how many seconds of network inactivity is required before the PDF is captured.

The wait_network_time value must be a number between 0 and 20.

Default: 2 seconds (used if wait_network is set but this option is not)

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: 3 seconds

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.

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

attachment

Setting this to "true" will result in the file being downloaded by the browser rather than displayed inline.

This option is mainly useful when . If you're using the Amazon SDK, then you have the option of setting "content disposition" to "attachment" when generating the URL, which will have the same effect.

Default: false

username

If set, this username will be used if HTTP Basic Auth is requested.

For more information see our .

Default: Not set

password

If set, this password will be used if HTTP Basic Auth is requested. If password is set, you must also provide a username.

For more information see our .

Default: Not set

http_success

Setting this to "true" will result in the PDF conversion job failing (with the creation_failed status) if the HTTP response from the URL is in the 400 or 500 range. For example, 401, 404 etc.

Default: false

Custom page sizes

To use a custom page size, provide height and width values within the page_size parameter.

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)