Conversion Parameters

Our API offers parameters for customizing PDF generation from HTML, URLs, and dynamic templates. This section details each parameter, with examples, to help you tailor the output to your needs.

Source Parameters

Content Source

You must provide exactly one of the following content sources: html, url, or templateId (with templateData). These parameters are mutually exclusive – use only one per API request.

html

Type: string

Required: No

Details: Accepts Base64-encoded HTML content, allowing you to provide the HTML directly for generating a PDF.

Usage:

{
  "html": "PGh0bWw+Cjxib2R5Pgo8cD5UZXN0IHBhcmFncmFwaDwvcD4KPC9ib2R5Pgo8L2h0bWw+Cg=="
}

This example generates a PDF containing the text: “Test paragraph”.

tip

Ensure your HTML content is properly encoded in Base64 format before passing it to this parameter. You can use online tools or libraries to perform the conversion.

url

Type: string

Required: No

Details: Accepts any valid URL. This allows specifying the webpage to be converted to a PDF.

Usage:

{
  "url": "https://example.com"
}

templateId

Type: string

Required: No

Details: Specifies the unique identifier (UUID) of a published template to use for PDF generation. When using this parameter, templateData must also be provided to populate the template variables. Templates allow you to separate design from data, making document generation more efficient and maintainable.

Usage:

{
  "templateId": "c2b5f574-19bc-4e34-9049-566176e6dc48",
  "templateData": {
    "customerName": "John Doe",
    "invoiceNumber": "INV-001"
  }
}

Template Management

Templates must be created and published through the Templates Dashboard before they can be used via API.
Learn more about template creation and management.

templateData

Type: object

Required: No (mandatory only if templateId is provided)

Details: Contains the JSON data that replaces placeholder variables in your template to generate the final PDF. Property names in this object must match the variable names used in your template's Handlebars syntax. For example, if your template contains {{customerName}}, your templateData should include a customerName property with the actual value.

Usage:

{
  "templateId": "c2b5f574-19bc-4e34-9049-566176e6dc48",
  "templateData": {
    "invoiceNumber": "INV-001",
    "customerName": "John Doe",
    "items": [
      {
        "name": "Premium Service",
        "price": "199.99"
      }
    ],
    "total": "199.99",
    "isPaid": true
  }
}

Data Privacy

Template data is only used for PDF generation and is not stored, logged, or retained by PDFBolt.

Your data remains private and secure. See our DPA for compliance details.

Page Parameters

emulateMediaType

Type: string

Required: No

Default Value: print

Details: Determines the media type for rendering the PDF.

Allowed Values:

Value	Description
`screen`	Generates a PDF using styles optimized for digital screens.
`print`	Generates a PDF using styles intended for print.

Usage:

{
  "url": "https://example.com",
  "emulateMediaType": "screen"
}

javaScriptEnabled

Type: boolean

Required: No

Default Value: true

Details: Determines whether JavaScript execution is enabled on the source page during PDF generation.

Value	Description
`true`	Enables JavaScript execution. Dynamic content, animations, and interactive elements are rendered accurately.
`false`	Disables JavaScript execution. Improves performance and reduces rendering time, but dynamic or interactive content may not render correctly.

Usage:

{
  "url": "https://example.com",
  "javaScriptEnabled": true
}

httpCredentials

Type: object

Required: No

Details: Enables HTTP Basic Authentication by providing a username and password, allowing access to resources protected by authentication.

Property Name	Type	Description
`username`	`string`	The username for authentication. `required`
`password`	`string`	The password for authentication. `required`

Usage:

{
  "url": "https://example.com",
  "httpCredentials": {
    "username": "john",
    "password": "pa55w0rd"
  }
}

viewportSize

Type: object

Required: No

Details: Defines the viewport dimensions for the page, specifying the width and height in pixels. Both width and height must be included in the viewportSize object and must be integers.

Property Name	Type	Description
`width`	`number`	Width of the viewport in pixels. `required`
`height`	`number`	Height of the viewport in pixels. `required`

Usage:

{
  "url": "https://example.com",
  "viewportSize": {
    "width": 1280,
    "height": 800
  }
}

How viewport size works

Viewport size controls how the page is rendered before PDF conversion, similar to resizing a browser window. This only affects pages that use responsive design with CSS media queries like @media (max-width: 768px). Pages without defined responsive CSS will look the same regardless of viewport size.

isMobile

Type: boolean

Required: No

Default Value: false

Details: Enables or disables mobile device emulation, affecting how the page is rendered and interacted with.

Value	Description
`true`	Simulates a mobile device by respecting the meta viewport tag and enabling touch events.
`false`	Disables mobile emulation, rendering the page as it would appear on a desktop device.

Usage:

{
  "url": "https://example.com",
  "isMobile": true
}

When to use isMobile

Most sites only need viewportSize for mobile layout. Use isMobile: true only for sites that detect mobile devices with JavaScript or use touch-specific CSS.

deviceScaleFactor

Type: number

Required: No

Default Value: 1

Details: Defines the level of scaling applied to the webpage during rendering. A higher scale factor enhances the resolution, making text and images appear sharper in the generated PDF. The allowed values range from 1 to 4.

Usage:

{
  "url": "https://example.com",
  "deviceScaleFactor": 2
}

Performance impact

Using a higher deviceScaleFactor can increase the file size and slightly prolong the processing time for generating the PDF.

extraHTTPHeaders

Type: object

Required: No

Details: Allows you to include additional custom HTTP headers in the request. You can specify up to 10 headers, but the order of the headers is not guaranteed. By default, these headers will be sent with every request the page initiates, including requests for images, stylesheets, scripts, and other resources.

Usage:

{
  "url": "https://example.com",
  "extraHTTPHeaders": {
    "X-extra-header": "test1",
    "X-extra-header2": "test2"
  }
}

Header Scope

To limit headers to only the main page request and exclude sub-resources (images, CSS, JS), set applyExtraHTTPHeadersToAllResources to false. See details below.

applyExtraHTTPHeadersToAllResources

Type: boolean

Required: No

Default Value: true

Details: Determines whether custom HTTP headers specified in extraHTTPHeaders should be applied to all resource requests or only to the main page request.

Value	Description
`true`	Headers are sent with every request initiated by the page, including sub-resources like images, stylesheets, and scripts.
`false`	Headers are sent only with the main page request.

Usage:

{
  "url": "https://example.com",
  "extraHTTPHeaders": {
    "X-Custom-Key": "abc123xyz789"
  },
  "applyExtraHTTPHeadersToAllResources": false
}

Usage Notes

Use this parameter only with extraHTTPHeaders.
Set to false if your headers are only intended for the main page request. This prevents errors when external resources (e.g., CDNs, S3) reject custom headers, which can block assets from loading and result in a blank page.

cookies

Type: Array<Object>

Required: No

Details: Specifies a list of cookies to include in the request. Each cookie must include the name, value, and either an url or a combination of both domain and path to define its scope. Optional properties are available for further customization. A maximum of 10 cookies can be added.

Property Name	Type	Description
`name`	`string`	The name of the cookie. `required`
`value`	`string`	The value of the cookie. `required`
`url`	`string`	Specifies the URL for which the cookie is valid. `required` if `domain` and `path` are not used
`domain`	`string`	Specifies the domain for which the cookie is valid. `required` if `url` is not used
`path`	`string`	The URL path that must exist in the requested URL for the cookie to be sent. `required` with `domain`
`expires`	`number`	Expiration date of the cookie in UNIX timestamp format. `optional`
`httpOnly`	`boolean`	Indicates if the cookie is HTTP-only. `optional`
`secure`	`boolean`	Indicates if the cookie is secure. `optional`

Usage:

{
  "url": "https://example.com",
  "cookies": [
    {
      "name": "sessionId",
      "value": "abc123",
      "domain": "example.com",
      "path": "/"
    },
    {
      "name": "userPreferences",
      "value": "darkMode=true",
      "url": "https://example.com",
      "expires": 1739641833,
      "httpOnly": true,
      "secure": true
    }
  ]
}

waitUntil

Type: string

Required: No

Default Value: load

Details: Specifies the event that defines when the page is considered fully loaded during PDF generation. Select the value that best fits your page's content and loading behavior.

Allowed Values:

Value	Description
`domcontentloaded`	Completes when the `DOMContentLoaded` event fires, meaning the HTML document has been fully parsed.
`load`	Completes when the `load` event fires, ensuring all resources such as images and scripts are loaded.
`networkidle`	Completes when there are no active network requests for at least 500 ms, indicating the page is stable.
`commit`	Completes as soon as a network response is received, and the document begins loading.

Usage:

{
  "url": "https://example.com",
  "waitUntil": "networkidle"
}

waitForFunction

Type: string

Required: No

Details: Waits for a specified JavaScript function to execute and return true within the page’s context, ensuring that certain conditions are met before continuing.

Usage:

{
  "url": "https://example.com",
  "waitForFunction": "() => { return document.readyState === 'complete' && document.fonts.status === 'loaded' && Array.from(document.images).every(img => img.complete); }"
}

What this function does

This example function waits until the document is fully loaded, all fonts are loaded, and all images have finished loading. This ensures your PDF captures the page after all content has properly rendered.

waitForSelector

Type: object

Required: No

Details: Waits for a specified selector to satisfy a given state, such as appearing, disappearing, becoming visible, or hidden in the DOM.

Property Name	Type	Description
`selector`	`string`	CSS selector to target an element. `required`
`state`	`string`	State to wait for. Must be one of the allowed values. `required`

Allowed Values for state:

Value	Description
`attached`	Waits for the element to be present in the DOM.
`detached`	Waits for the element to not be present in the DOM.
`visible`	Waits for the element to have a non-empty bounding box and not have `visibility: hidden`. Elements with `display: none` are excluded.
`hidden`	Waits for the element to be either detached from the DOM, have an empty bounding box or `visibility: hidden`. Opposite of `visible`.

Usage:

{
  "url": "https://example.com",
  "waitForSelector": {
     "selector": "#removable-element",
     "state": "hidden"
    }
}

Invalid selector

Ensure the CSS selector exists on the target page. A non-existent selector will cause a timeout error.

timeout

Type: number

Required: No

Default Value: 30000

Details: Defines the maximum time in milliseconds to wait for the page to load or for specific conditions to be met. Acceptable range is between 0 and 60000 (1 minute). If the timeout is exceeded, the request will fail with a timeout error.

Usage:

{
  "url": "https://example.com",
  "timeout": 30000
}

Common Timeout Mistake

Note that the timeout value must be provided in milliseconds, not seconds. A common mistake is entering 30 instead of 30000 for a 30-second timeout. Ensure your value is within the valid range: 0 – 60000 ms.

Pdf Layout

format

Type: string

Required: No

Default Value: Letter

Details: Specifies the paper format for the generated PDF. If both format and custom dimensions: width or height are provided, the format parameter takes priority.

Allowed Values:

Value	Size in Inches	Size in cm	Size in Feet
`Letter`	8.5in x 11in	21.6cm x 27.9cm	0.666ft x 0.917ft
`Legal`	8.5in x 14in	21.6cm x 35.6cm	0.666ft x 1.167ft
`Tabloid`	11in x 17in	27.9cm x 43.2cm	0.917ft x 1.417ft
`Ledger`	17in x 11in	43.2cm x 27.9cm	1.417ft x 0.917ft
`A0`	33.1in x 46.8in	84cm x 118.9cm	2.757ft x 3.898ft
`A1`	23.4in x 33.1in	59.4cm x 84cm	1.948ft x 2.757ft
`A2`	16.54in x 23.4in	42cm x 59.4cm	1.377ft x 1.948ft
`A3`	11.7in x 16.54in	29.7cm x 42cm	0.974ft x 1.377ft
`A4`	8.27in x 11.7in	21cm x 29.7cm	0.689ft x 0.974ft
`A5`	5.83in x 8.27in	14.8cm x 21cm	0.485ft x 0.689ft
`A6`	4.13in x 5.83in	10.5cm x 14.8cm	0.344ft x 0.485ft

Usage:

{
  "url": "https://example.com",
  "format": "A4"
}

landscape

Type: boolean

Required: No

Default Value: false

Details: Defines the orientation of the generated PDF.

Value	Description
`true`	Generates the PDF in landscape mode.
`false`	Generates the PDF in portrait mode (default).

Usage:

{
  "url": "https://example.com",
  "landscape": true
}

width

Type: string | number

Required: No

Details: Defines the width of the page for the generated PDF. You can specify the width using different units.

Supported Units:

px – pixel
in – inch
cm – centimeter
mm – millimeter

info

If no unit is specified, the value is interpreted as pixels.

Examples:

"width": 100 – sets the page width to 100 pixels.
"width": "100px" – sets the page width to 100 pixels.
"width": "10cm" – sets the page width to 10 centimeters.

Usage:

{
  "url": "https://example.com",
  "width": "15cm"
}

height

Type: string | number

Required: No

Details: Defines the height of the page for the generated PDF. For more information on supported units and examples, see width section.

Usage:

{
  "url": "https://example.com",
  "height": "800px"
}

margin

Type: object

Required: No

Details: Specifies the page margins for the generated PDF. By default, no margins are applied. When using this parameter, at least one margin property (top, right, left, bottom) must be provided. An empty margin object is invalid and will have no effect. For more information on supported units, see width section.

Property Name	Type	Description
`top`	`string` \| `number`	Specifies the top margin.
`right`	`string` \| `number`	Specifies the right margin.
`left`	`string` \| `number`	Specifies the left margin.
`bottom`	`string` \| `number`	Specifies the bottom margin.

Usage:

{
  "url": "https://example.com",
  "margin": {
    "top": "30px",
    "right": "20px",
    "left": "20px",
    "bottom": "30px"
  }
}

pageRanges

Type: string

Required: No

Details: Specifies the page ranges to include in the PDF. Accepts a comma-separated list of page ranges or individual pages, such as 1-3, 5, 8-11. If omitted, the PDF will include all pages by default.

Usage:

{
  "url": "https://example.com",
  "pageRanges": "1-7"
}

preferCssPageSize

Type: boolean

Required: No

Default Value: false

Details: Specifies whether the PDF generation should prioritize the CSS @page size defined in the content.

Value	Description
`true`	The PDF will use the dimensions specified in the `@page` CSS rule.
`false`	The content will scale automatically to fit the page size set by `width`, `height`, or `format`.

Usage:

{
  "url": "https://example.com",
  "preferCssPageSize": true
}

printBackground

Type: boolean

Required: No

Default Value: false

Details: Specifies whether the PDF should include background graphics like colors and images.

Value	Description
`true`	Background graphics (e.g., colors, images) will be included in the PDF.
`false`	Background graphics will be excluded, producing a simpler, more minimalistic PDF.

Usage:

{
  "url": "https://example.com",
  "printBackground": true
}

scale

Type: number

Required: No

Default Value: 1

Details: Specifies the scaling factor for rendering the content in the generated PDF. The acceptable range for this parameter is between 0.1 and 2.

Usage:

{
  "url": "https://example.com",
  "scale": 1.5
}

displayHeaderFooter

Type: boolean

Required: No

Default Value: false

Details: Specifies whether to include a header and footer in the generated PDF. This parameter is meaningful only when used with the headerTemplate and/or footerTemplate parameters to define the content of the header and footer.

Value	Description
`true`	Header and footer will be displayed on each page of the PDF.
`false`	No header or footer will be included in the PDF.

Usage:

{
  "url": "https://example.com",
  "displayHeaderFooter": true
}

headerTemplate

Type: string

Required: No

Details: Specifies the HTML template for the page header. The template must be a valid Base64-encoded HTML string with specific classes used to dynamically inject values during PDF generation.

The following classes are used to inject values into them:

Placeholder	Description
`date`	Formatted date.
`title`	Document title.
`url`	Document location.
`pageNumber`	Current page number.
`totalPages`	Total number of pages in the document.

Usage:

{
  "url": "https://example.com",
  "displayHeaderFooter": true,
  "headerTemplate": "PGRpdiBzdHlsZT0id2lkdGg6IDEwMCU7IHRleHQtYWxpZ246IGNlbnRlcjsgZm9udC1zaXplOiAxMHB4OyBjb2xvcjogZ3JheTsiPg0KICAgIDxzcGFuIGNsYXNzPSJ0aXRsZSI+PC9zcGFuPiB8IDxzcGFuIGNsYXNzPSJ1cmwiPjwvc3Bhbj4gfCA8c3BhbiBjbGFzcz0iZGF0ZSI+PC9zcGFuPg0KPC9kaXY+DQo=",
  "margin": {
      "top": "30px"
    }
}

This example generates a PDF with the following header:

<div style="width: 100%; text-align: center; font-size: 10px; color: gray;">
    <span class="title"></span> | <span class="url"></span> | <span class="date"></span>
</div>

Header & Footer Templates

Ensure that your HTML templates are valid Base64-encoded strings before using them.
Please note that <script> tags within templates are not executed.

Styling Tips

Apply Inline Styles: Use inline styles directly within your HTML templates, as CSS rules defined in the body do not affect headers or footers.
Adjust Margins: Modify the margin-top for headers and margin-bottom for footers to ensure visibility and avoid clipping.
Check Visibility: Verify font size, color, and background to make headers and footers clearly visible.

footerTemplate

Type: string

Required: No

Details: Specifies the Base64-encoded HTML template for the page footer. Use the same conventions as the headerTemplate.

Usage:

{
  "url": "https://example.com",
  "displayHeaderFooter": true,
  "footerTemplate": "PGRpdiBzdHlsZT0id2lkdGg6IDEwMCU7IHRleHQtYWxpZ246IGNlbnRlcjsgZm9udC1zaXplOiAxMnB4OyI+DQogICAgPHNwYW4gY2xhc3M9InBhZ2VOdW1iZXIiPjwvc3Bhbj4gb2YgPHNwYW4gY2xhc3M9InRvdGFsUGFnZXMiPjwvc3Bhbj4NCjwvZGl2Pg==",
  "margin": {
      "bottom": "40px"
    }
}

This example generates a PDF with the footer:

<div style="width: 100%; text-align: center; font-size: 12px;">
    <span class="pageNumber"></span> of <span class="totalPages"></span>
</div>

Accessibility

tagged

Type: boolean

Required: No

Default Value: false

Details: Determines whether to generate tagged (accessible) PDFs that include structural information for screen readers and assistive technologies. Tagged PDFs comply with accessibility standards and are essential for users with disabilities.

Value	Description
`true`	Generates a tagged PDF with structural markup for accessibility compliance (PDF/UA standard).
`false`	Generates a standard PDF without accessibility tags.

Usage:

{
  "url": "https://example.com",
  "format": "A4",
  "tagged": true
}

Size Considerations

File sizes are typically 5-15% larger due to embedded structural information.

Output Parameters

contentDisposition

Type: string

Required: No

Default Value: inline

Details: Controls the Content-Disposition header behavior for the generated PDF, determining how browsers handle the file.

Allowed Values:

Value	Description
`inline`	The PDF is displayed directly in the browser (default behavior).
`attachment`	The PDF is downloaded as a file, prompting the user with a Save As dialog.

Usage:

{
  "url": "https://example.com",
  "contentDisposition": "attachment"
}

This will generate a PDF with the following header:

Content-Disposition: attachment

Combining with filename

You can use contentDisposition together with the filename parameter to control both the download behavior and the filename:

{
  "url": "https://example.com",
  "contentDisposition": "attachment",
  "filename": "custom_file_name"
}

Result:

Content-Disposition: attachment; filename="custom_file_name.pdf"

filename

Type: string

Required: No

Details: Specifies the filename for the generated PDF. This name will be embedded in the Content-Disposition header so browsers and automation tools (such as n8n, Zapier, and Make) can correctly recognize and use the specified filename when downloading or processing the PDF.

Constraints:

Maximum length: 255 characters.
Allowed characters: alphanumeric (a–z, A–Z, 0–9), dots (.), underscores (_), hyphens (-).
If the .pdf extension is omitted, it will be added automatically.

Usage:

{
  "url": "https://example.com",
  "filename": "custom_file_name"
}

This will generate a PDF with the following header:

Content-Disposition: inline; filename="custom_file_name.pdf"

Integration with Automation Tools

When using PDFBolt with automation platforms like n8n, Zapier, or Make, the filename parameter ensures that downloaded PDFs use your specified name instead of a generic or UUID-based filename.

compression

Type: string

Required: No

Details: Applies post-generation compression to reduce the PDF file size. This is particularly useful for PDFs containing images, where significant size reductions can be achieved. The compression level determines the trade-off between file size and quality.

Allowed Values:

Value	Description
`low`	Highest quality – largest file size.
`medium`	Balanced quality – moderate file size.
`high`	Lowest quality – smallest file size.

Usage:

{
  "url": "https://example.com",
  "compression": "low"
}

When to Use Compression

Compression is most effective on image-heavy PDFs. Text-only PDFs will see minimal size reduction.

Source Parameters​

html​

url​

templateId​

templateData​

Page Parameters​

emulateMediaType​

javaScriptEnabled​

httpCredentials​

viewportSize​

isMobile​

deviceScaleFactor​

extraHTTPHeaders​

applyExtraHTTPHeadersToAllResources​

cookies​

waitUntil​

waitForFunction​

waitForSelector​

timeout​

Pdf Layout​

format​

landscape​

width​

height​

margin​

pageRanges​

preferCssPageSize​

printBackground​

scale​

displayHeaderFooter​

headerTemplate​

footerTemplate​

Accessibility​

tagged​

Output Parameters​

contentDisposition​

filename​

compression​

Source Parameters

html

url

templateId

templateData

Page Parameters

emulateMediaType

javaScriptEnabled

httpCredentials

viewportSize

isMobile

deviceScaleFactor

extraHTTPHeaders

applyExtraHTTPHeadersToAllResources

cookies

waitUntil

waitForFunction

waitForSelector

timeout

Pdf Layout

format

landscape

width

height

margin

pageRanges

preferCssPageSize

printBackground

scale

displayHeaderFooter

headerTemplate

footerTemplate

Accessibility

tagged

Output Parameters

contentDisposition

filename

compression