HTML to PDF / Java Reference

class HtmlToPdfClient

All setter methods return HtmlToPdfClient object unless specified otherwise.

Constructor

public HtmlToPdfClient(String userName, String apiKey)

Constructor for the PDFCrowd API client. Initialize a new instance of the conversion client with your PDFCrowd account credentials.

You must provide both your username and API key. This establishes the authenticated connection for all subsequent conversion operations.

Parameters:
  • userName - Your username at PDFCrowd.
  • apiKey - Your API key.

Conversion Input

public byte[] convertUrl(String url)

Convert a web page from a URL.

Use this as the primary method for converting web content, online documents, or any publicly accessible URL to the desired output format. Returns the conversion result as a byte array for further processing or direct use.

Parameter:
  • url - The address of the web page to convert.
    Constraint:
    • Supported protocols are http:// and https://.
Returns:
byte[] - Byte array containing the conversion output.

public void convertUrlToStream(String url, OutputStream outStream)

Convert a web page from a URL and write the conversion result directly to an output stream.

Use this when you need to handle large conversion results, integrate with streaming pipelines, or build server applications that process conversions continuously.

Parameters:
  • url - The address of the web page to convert.
    Constraint:
    • Supported protocols are http:// and https://.
  • outStream (OutputStream) - The output stream that will contain the conversion output.

public void convertUrlToFile(String url, String filePath) throws IOException

Convert a web page from a URL and save the conversion result directly to a local file.

Use this for simple file-based workflows, batch processing, or when you need to persist conversion output to disk. The most straightforward method for URL-to-file conversions.

Parameters:
  • url - The address of the web page to convert.
    Constraint:
    • Supported protocols are http:// and https://.
  • filePath - The output file path.

public byte[] convertFile(String file)

Convert a local file to the desired output format.

Use this for processing files already on your system, converting uploaded documents, or batch processing local content. Returns the conversion result as a byte array for in-memory processing.

Parameter:
  • file - The path to a local file to convert.
    The file can be either a single file or an archive (.tar.gz, .tar.bz2, or .zip).
    If the HTML document refers to local external assets (images, style sheets, javascript), zip the document together with the assets.
    Constraints:
    • The file must exist and not be empty.
    • The file name must have a valid extension.
Returns:
byte[] - Byte array containing the conversion output.

public void convertFileToStream(String file, OutputStream outStream)

Convert a local file and write the conversion result directly to an output stream.

Use this when working with large conversion results, integrating with streaming frameworks, or building applications that need direct stream-to-stream processing.

Parameters:
  • file - The path to a local file to convert.
    The file can be either a single file or an archive (.tar.gz, .tar.bz2, or .zip).
    If the HTML document refers to local external assets (images, style sheets, javascript), zip the document together with the assets.
    Constraints:
    • The file must exist and not be empty.
    • The file name must have a valid extension.
  • outStream (OutputStream) - The output stream that will contain the conversion output.

public void convertFileToFile(String file, String filePath) throws IOException

Convert a local file and save the conversion result to another local file.

Use this for file-based batch processing, document transformation workflows, or when both input and output are file-based. The simplest method for file-to-file conversions.

Parameters:
  • file - The path to a local file to convert.
    The file can be either a single file or an archive (.tar.gz, .tar.bz2, or .zip).
    If the HTML document refers to local external assets (images, style sheets, javascript), zip the document together with the assets.
    Constraints:
    • The file must exist and not be empty.
    • The file name must have a valid extension.
  • filePath - The output file path.

public byte[] convertString(String text)

Convert a string containing source content to the desired output format.

Use this for converting dynamically generated content, templates, user input, or any text-based data held in memory. Ideal for real-time content generation and API integrations.

Parameter:
  • text - The string content to convert.
Returns:
byte[] - Byte array containing the conversion output.

public void convertStringToStream(String text, OutputStream outStream)

Convert a string containing source content and write the conversion result directly to an output stream.

Use this when processing dynamically generated content with large outputs, integrating with streaming APIs, or building high-throughput web applications.

Parameters:
  • text - The string content to convert.
  • outStream (OutputStream) - The output stream that will contain the conversion output.

public void convertStringToFile(String text, String filePath) throws IOException

Convert a string containing source content and save the conversion result to a local file.

Use this for persisting dynamically generated content, creating documents from templates, or saving user-generated conversions. Combines in-memory source with file-based output.

Parameters:
  • text - The string content to convert.
  • filePath - The output file path.

public byte[] convertStream(InputStream inStream) throws IOException

Convert content from an input stream to the desired output format.

Use this when integrating with I/O pipelines, processing data from network streams or file handles, or when the source data is provided as a stream by your application.

Parameter:
  • inStream (InputStream) - The input stream with source data.
    The stream can contain either HTML code or an archive (.zip, .tar.gz, .tar.bz2).
    The archive can contain HTML code and its external assets (images, style sheets, javascript).
Returns:
byte[] - Byte array containing the conversion output.

public void convertStreamToStream(InputStream inStream, OutputStream outStream) throws IOException

Convert content from an input stream and write the conversion result to an output stream.

Use this when both input and output need to be streams, integrating with streaming frameworks, or building conversion services that process data in stream form throughout.

Parameters:
  • inStream (InputStream) - The input stream with source data.
    The stream can contain either HTML code or an archive (.zip, .tar.gz, .tar.bz2).
    The archive can contain HTML code and its external assets (images, style sheets, javascript).
  • outStream (OutputStream) - The output stream that will contain the conversion output.

public void convertStreamToFile(InputStream inStream, String filePath) throws IOException

Convert content from an input stream and save the conversion result to a local file.

Use this when processing streaming uploads that need to be saved, handling network data sources with file-based output, or building services that accept stream input and produce file output.

Parameters:
  • inStream (InputStream) - The input stream with source data.
    The stream can contain either HTML code or an archive (.zip, .tar.gz, .tar.bz2).
    The archive can contain HTML code and its external assets (images, style sheets, javascript).
  • filePath - The output file path.

public HtmlToPdfClient setZipMainFilename(String filename)

Set the file name of the main HTML document stored in the input archive. Use this when your ZIP/TAR archive contains multiple HTML files and you need to specify which one to convert.

If not specified, the first HTML file found in the archive is automatically used for conversion.

Parameter:
  • filename - The file name.

Page Setup

public HtmlToPdfClient setPageSize(String size)

Set the output page size using standard formats (A4, Letter, A3, etc.). Use A4 for international documents, Letter for US-based content, or larger sizes like A3 for posters and presentations.

Parameter:
  • size
    Allowed Values:
    • A0
    • A1
    • A2
    • A3
    • A4
    • A5
    • A6
    • Letter
    Default:
    A4

public HtmlToPdfClient setPageWidth(String width)

Set custom page dimensions when standard sizes don't fit your needs. Useful for banners, receipts, custom forms, or when matching specific printing equipment.

The safe maximum is 200in - larger sizes may fail to open in some PDF viewers. For standard sizes like A4 or Letter, use the predefined page size option instead.

Parameter:
  • width
    Constraint:
    • The value must be specified in inches 'in', millimeters 'mm', centimeters 'cm', pixels 'px', or points 'pt'.
    Default:
    8.27in
Examples:
  • A4 landscape / A3 portrait width: setPageWidth("297mm")
  • US Letter/Legal standard width: setPageWidth("8.5in")

public HtmlToPdfClient setPageHeight(String height)

Set custom page height for specific formats like receipts, banners, or legal documents. Set to "-1" for a single-page PDF that expands to fit all content vertically - ideal for web pages, infographics, or documents where page breaks are undesirable.

The safe maximum is 200in otherwise some viewers cannot open the PDF. For standard sizes, use the predefined page size option instead.

Parameter:
  • height
    Constraint:
    • The value must be -1 or specified in inches 'in', millimeters 'mm', centimeters 'cm', pixels 'px', or points 'pt'.
    Default:
    11.7in
Examples:
  • A3 standard height for large format: setPageHeight("420mm")
  • Auto-fit entire content in single page: setPageHeight("-1")
  • US Legal for contracts and documents: setPageHeight("14in")

public HtmlToPdfClient setPageDimensions(String width, String height)

Set both page width and height simultaneously for custom page sizes. Use this when you need non-standard dimensions like banners, receipts, or custom forms that don't match A4, Letter, or other predefined sizes.

Provide width and height with units (e.g., "210mm", "8.5in"). Maximum safe value is 200in for each dimension - larger sizes may fail to open in some PDF viewers.

Parameters:
  • width - Set custom page dimensions when standard sizes don't fit your needs. Useful for banners, receipts, custom forms, or when matching specific printing equipment. The safe maximum is 200in - larger sizes may fail to open in some PDF viewers. For standard sizes like A4 or Letter, use the predefined page size option instead.
    Constraint:
    • The value must be specified in inches 'in', millimeters 'mm', centimeters 'cm', pixels 'px', or points 'pt'.
    Default:
    8.27in
  • height - Set custom page height for specific formats like receipts, banners, or legal documents. Set to "-1" for a single-page PDF that expands to fit all content vertically - ideal for web pages, infographics, or documents where page breaks are undesirable. The safe maximum is 200in otherwise some viewers cannot open the PDF. For standard sizes, use the predefined page size option instead.
    Constraint:
    • The value must be -1 or specified in inches 'in', millimeters 'mm', centimeters 'cm', pixels 'px', or points 'pt'.
    Default:
    11.7in
Examples:
  • A4 portrait dimensions: setPageDimensions("210mm", "297mm")
  • US Letter dimensions: setPageDimensions("8.5in", "11in")
  • A3 portrait dimensions: setPageDimensions("297mm", "420mm")

public HtmlToPdfClient setOrientation(String orientation)

Set the output page orientation to portrait or landscape. Use landscape for wide content like spreadsheets, charts, or dashboards. Use portrait for standard documents and text-heavy content.

Parameter:
  • orientation
    Allowed Values:
    • landscape
    • portrait
    Default:
    portrait

public HtmlToPdfClient setMarginTop(String top)

Control white space at the top of the page. Increase for header space, formal documents, or annotation room (e.g., 1in or more). Decrease to maximize content area or fit more content (e.g., 5mm to 10mm).

Default 0.4in balances readability with space efficiency. Set to 0 for full-bleed designs. Affects where content starts and where headers appear.

Parameter:
  • top
    Constraint:
    • The value must be specified in inches 'in', millimeters 'mm', centimeters 'cm', pixels 'px', or points 'pt'.
    Default:
    0.4in
Examples:
  • Wide margin for binding: setMarginTop("1in")
  • Narrow professional margin: setMarginTop("10mm")

public HtmlToPdfClient setMarginRight(String right)

Control white space on the right edge of the page. Increase for binding/hole-punch clearance or note-taking space (e.g., 1in or more). Decrease to fit wider content (e.g., 5mm to 10mm).

Default 0.4in balances readability with space efficiency. Set to 0 for full-bleed designs. Affects where content wraps and text line length.

Parameter:
  • right
    Constraint:
    • The value must be specified in inches 'in', millimeters 'mm', centimeters 'cm', pixels 'px', or points 'pt'.
    Default:
    0.4in
Examples:
  • Wide margin for binding: setMarginRight("1in")
  • Narrow professional margin: setMarginRight("10mm")

public HtmlToPdfClient setMarginBottom(String bottom)

Control white space at the bottom of the page. Increase for footer space, page numbers, or formal documents (e.g., 1in or more). Decrease to fit more content per page (e.g., 5mm to 10mm).

Default 0.4in balances readability with space efficiency. Set to 0 for full-bleed designs. Affects where content ends and where footers appear.

Parameter:
  • bottom
    Constraint:
    • The value must be specified in inches 'in', millimeters 'mm', centimeters 'cm', pixels 'px', or points 'pt'.
    Default:
    0.4in
Examples:
  • Wide margin for binding: setMarginBottom("1in")
  • Narrow professional margin: setMarginBottom("10mm")

public HtmlToPdfClient setMarginLeft(String left)

Control white space on the left edge of the page. Increase for binding/hole-punch clearance or note-taking space (e.g., 1in or more). Decrease to fit wider content (e.g., 5mm to 10mm).

Default 0.4in balances readability with space efficiency. Set to 0 for full-bleed designs. Affects where content starts horizontally and text line length.

Parameter:
  • left
    Constraint:
    • The value must be specified in inches 'in', millimeters 'mm', centimeters 'cm', pixels 'px', or points 'pt'.
    Default:
    0.4in
Examples:
  • Wide margin for binding: setMarginLeft("1in")
  • Narrow professional margin: setMarginLeft("10mm")

public HtmlToPdfClient setNoMargins(boolean value)

Disable all page margins to use the entire page area. Use this for full-bleed designs where content should extend to the page edges, such as posters, certificates, or branded materials.

Combine with custom CSS to ensure your content fills the page properly.

Parameter:
  • value (bool) - Set to true to disable margins.
    Default:
    false

public HtmlToPdfClient setPageMargins(String top, String right, String bottom, String left)

Set all four page margins (top, right, bottom, left) simultaneously for consistent spacing. Use this when you need uniform margins for binding, formal documents, or when applying the same spacing to all edges at once.

Provide margin values with units (e.g., "1in", "25mm"). Use larger values (1in+) for binding clearance or annotations, smaller values (5-10mm) to maximize content area. Set to "0" for full-bleed designs.

Parameters:
  • top - Control white space at the top of the page. Increase for header space, formal documents, or annotation room (e.g., 1in or more). Decrease to maximize content area or fit more content (e.g., 5mm to 10mm). Default 0.4in balances readability with space efficiency. Set to 0 for full-bleed designs. Affects where content starts and where headers appear.
    Constraint:
    • The value must be specified in inches 'in', millimeters 'mm', centimeters 'cm', pixels 'px', or points 'pt'.
    Default:
    0.4in
  • right - Control white space on the right edge of the page. Increase for binding/hole-punch clearance or note-taking space (e.g., 1in or more). Decrease to fit wider content (e.g., 5mm to 10mm). Default 0.4in balances readability with space efficiency. Set to 0 for full-bleed designs. Affects where content wraps and text line length.
    Constraint:
    • The value must be specified in inches 'in', millimeters 'mm', centimeters 'cm', pixels 'px', or points 'pt'.
    Default:
    0.4in
  • bottom - Control white space at the bottom of the page. Increase for footer space, page numbers, or formal documents (e.g., 1in or more). Decrease to fit more content per page (e.g., 5mm to 10mm). Default 0.4in balances readability with space efficiency. Set to 0 for full-bleed designs. Affects where content ends and where footers appear.
    Constraint:
    • The value must be specified in inches 'in', millimeters 'mm', centimeters 'cm', pixels 'px', or points 'pt'.
    Default:
    0.4in
  • left - Control white space on the left edge of the page. Increase for binding/hole-punch clearance or note-taking space (e.g., 1in or more). Decrease to fit wider content (e.g., 5mm to 10mm). Default 0.4in balances readability with space efficiency. Set to 0 for full-bleed designs. Affects where content starts horizontally and text line length.
    Constraint:
    • The value must be specified in inches 'in', millimeters 'mm', centimeters 'cm', pixels 'px', or points 'pt'.
    Default:
    0.4in

public HtmlToPdfClient setPrintPageRange(String pages)

Set the page range to print when you only need specific pages from the conversion. Use this to extract individual pages (e.g., "2"), specific ranges (e.g., "3-7"), or combinations (e.g., "1,4-6,last"). Ideal for creating excerpts from long documents or excluding cover pages from batch processing.

Parameter:
  • pages
    Constraint:
    • A comma separated list of page numbers or ranges. Special strings may be used, such as 'odd', 'even' and 'last'.
Examples:
  • Just the second page is printed: setPrintPageRange("2")
  • The first, third, and last pages are printed: setPrintPageRange("1,3,last")
  • Everything except the first page is printed: setPrintPageRange("2-")
  • Just first 3 pages are printed: setPrintPageRange("-3")
  • Pages 3, 6, 7, 8 and 9 are printed: setPrintPageRange("3,6-9")

public HtmlToPdfClient setContentViewportWidth(String width)

Set the viewport width for formatting the HTML content when generating a PDF. Use this to control how responsive designs render - prevent mobile styles from applying when you want desktop layout, or ensure content appears at the right width.

Specify a viewport width to control content rendering, ensuring it mimics the appearance on various devices or matches specific design requirements.

Availability:
API client >= 6.0.0, converter >= 24.04. See versioning.
Parameter:
  • width - The width of the viewport.
    Allowed Values:
    • balanced — The smart option to adjust the viewport width dynamically to fit the print area, ensuring an optimal layout.
    • small — A compact layout where less text fits on each PDF page, ideal for detailed sections or mobile views.
    • medium — A balanced amount of text per page, striking a good compromise between readability and content density.
    • large — A broader layout that accommodates more text per page, perfect for reducing page count and enhancing flow.
    • extra-large — Maximize the text per page, creating a spacious and content-rich PDF, akin to a widescreen experience.
    • A precise viewport width in pixels, such as 1024px, to tailor the PDF's text density to your specific requirements. The value must be in the range 96-65000px.
    Constraint:
    • The value must be 'balanced', 'small', 'medium', 'large', 'extra-large', or a number in the range 96-65000px.
    Default:
    medium
Examples:
  • Use the "large" viewport: setContentViewportWidth("large")
  • Use an 800 pixels wide viewport: setContentViewportWidth("800px")

public HtmlToPdfClient setContentViewportHeight(String height)

Set the viewport height for formatting the HTML content when generating a PDF. Specify a viewport height to enforce loading of lazy-loaded images and affect vertical positioning of absolutely positioned elements within the content.

Availability:
API client >= 6.0.0, converter >= 24.04. See versioning.
Parameter:
  • height - The viewport height.
    Allowed Values:
    • auto — The height of the print area is used. For most pages, this is sufficient. Use "large" or custom values for pages with extensive lazy-loaded content.
    • large — Value suitable for documents with extensive lazy-loaded content.
    • A specific numerical value, such as 10000px, to set as the window height, allowing precise control based on the document's requirements.
    Constraint:
    • The value must be 'auto', 'large', or a number.
    Default:
    auto
Examples:
  • Load all lazy images and content: setContentViewportHeight("large")
  • Force tall viewport for long pages: setContentViewportHeight("5000px")

public HtmlToPdfClient setContentFitMode(String mode)

Specify the mode for fitting the HTML content to the print area by upscaling or downscaling it. Use this to prevent content from being cut off at page edges or to enable smart scaling of oversized content.

Availability:
API client >= 6.0.0, converter >= 24.04. See versioning.
Parameter:
  • mode - The fitting mode.
    Allowed Values:
    • auto — Automatic mode
    • smart-scaling — Smartscaling to fit more content into the print area.
    • no-scaling — No scaling is performed. Content may be cut off if it exceeds page boundaries. Use for pixel-perfect output.
    • viewport-width — The viewport width fits the print area width.
    • content-width — The HTML content width fits the print area width.
    • single-page — The entire HTML content fits the print area of a single page.
    • single-page-ratio — The entire HTML content fits the print area of a single page, maintaining the aspect ratio of the page height and width.
    Default:
    auto

public HtmlToPdfClient setRemoveBlankPages(String pages)

Specify which blank pages to exclude from the output document to create cleaner PDFs. Use "trailing" to remove empty pages at the end caused by page break issues. Use "all" to remove blank pages throughout the document when converting content with formatting quirks. Helps eliminate unwanted white pages from the final output.

Availability:
API client >= 5.13.0, converter >= 20.10. See versioning.
Parameter:
  • pages - The empty page behavior.
    Allowed Values:
    • trailing — Trailing blank pages are removed from the document.
    • all — All empty pages are removed from the document.
    • none — No blank page is removed from the document.
    Default:
    trailing

Watermark & Background

public HtmlToPdfClient setPageWatermark(String watermark)

Apply the first page of a watermark PDF to every page of the output PDF. Use this to add transparent overlays like "DRAFT" stamps, security markings, or branding elements that appear on top of content. Ideal for confidential document marking or adding protective overlays.

Parameter:
  • watermark - The file path to a local file.
    Constraint:
    • The file must exist and not be empty.
Examples:
  • Multi-page PDF for watermarking: setPageWatermark("/home/user/john/watermark.pdf")
  • Transparent PNG overlay: setPageWatermark("/home/user/john/watermark.png")

public HtmlToPdfClient setPageWatermarkUrl(String url)

Load a file from the specified URL and apply the file as a watermark to each page of the output PDF. A watermark can be either a PDF or an image. If a multi-page file (PDF or TIFF) is used, the first page is used as the watermark.

Parameter:
  • url
    Constraint:
    • Supported protocols are http:// and https://.
Examples:
  • Download watermark from server: setPageWatermarkUrl("http://myserver.com/watermark.pdf")
  • Remote logo watermark: setPageWatermarkUrl("http://myserver.com/watermark.png")

public HtmlToPdfClient setMultipageWatermark(String watermark)

Apply each page of a watermark PDF to the corresponding page of the output PDF. Use this for page-specific watermarks where different pages need different overlays - for example, different approval stamps per department.

If the watermark has fewer pages than the output, the last watermark page is repeated for remaining pages.

Parameter:
  • watermark - The file path to a local file.
    Constraint:
    • The file must exist and not be empty.
Examples:
  • Multi-page PDF for watermarking: setMultipageWatermark("/home/user/john/watermark.pdf")
  • Transparent PNG overlay: setMultipageWatermark("/home/user/john/watermark.png")

public HtmlToPdfClient setMultipageWatermarkUrl(String url)

Load a file from the specified URL and apply each page of the file as a watermark to the corresponding page of the output PDF. A watermark can be either a PDF or an image.

Parameter:
  • url
    Constraint:
    • Supported protocols are http:// and https://.
Examples:
  • Download watermark from server: setMultipageWatermarkUrl("http://myserver.com/watermark.pdf")
  • Remote logo watermark: setMultipageWatermarkUrl("http://myserver.com/watermark.png")

public HtmlToPdfClient setPageBackground(String background)

Apply the first page of a background PDF to every page of the output PDF. Use this to add letterheads, branded templates, or decorative backgrounds that appear behind your content. Backgrounds appear beneath content, while watermarks layer on top.

Perfect for adding company letterheads to reports or applying branded templates to dynamically generated content.

Parameter:
  • background - The file path to a local file.
    Constraint:
    • The file must exist and not be empty.
Examples:
  • PDF template background: setPageBackground("/home/user/john/background.pdf")
  • Image texture background: setPageBackground("/home/user/john/background.png")

public HtmlToPdfClient setPageBackgroundUrl(String url)

Load a file from the specified URL and apply the file as a background to each page of the output PDF. A background can be either a PDF or an image. If a multi-page file (PDF or TIFF) is used, the first page is used as the background.

Parameter:
  • url
    Constraint:
    • Supported protocols are http:// and https://.
Examples:
  • Download template background: setPageBackgroundUrl("http://myserver.com/background.pdf")
  • Remote background pattern: setPageBackgroundUrl("http://myserver.com/background.png")

public HtmlToPdfClient setMultipageBackground(String background)

Apply each page of a background PDF to the corresponding page of the output PDF. Use this for page-specific backgrounds where each page needs a different template - for example, different letterheads for front and back pages.

If the background has fewer pages than the output, the last background page is repeated for remaining pages.

Parameter:
  • background - The file path to a local file.
    Constraint:
    • The file must exist and not be empty.
Examples:
  • PDF template background: setMultipageBackground("/home/user/john/background.pdf")
  • Image texture background: setMultipageBackground("/home/user/john/background.png")

public HtmlToPdfClient setMultipageBackgroundUrl(String url)

Load a file from the specified URL and apply each page of the file as a background to the corresponding page of the output PDF. A background can be either a PDF or an image.

Parameter:
  • url
    Constraint:
    • Supported protocols are http:// and https://.
Examples:
  • Download template background: setMultipageBackgroundUrl("http://myserver.com/background.pdf")
  • Remote background pattern: setMultipageBackgroundUrl("http://myserver.com/background.png")

public HtmlToPdfClient setPageBackgroundColor(String color)

Set a solid background color for all pages, filling the entire page area including margins. Useful for creating branded PDFs with corporate colors, highlighting draft documents, or improving readability with off-white backgrounds.

Supports transparency with RGBA format - use semi-transparent colors for subtle effects without obscuring content. Format as RGB (FF0000) or RGBA (FF000080) hexadecimal.

Parameter:
  • color
    Constraint:
    • The value must be in RRGGBB or RRGGBBAA hexadecimal format.
Examples:
  • red color: setPageBackgroundColor("FF0000")
  • green color: setPageBackgroundColor("00ff00")
  • green color with 50% opacity: setPageBackgroundColor("00ff0080")

General Options

public HtmlToPdfClient setUsePrintMedia(boolean value)

Use the print version of the page if available via @media print CSS rules. Enable this when converting websites that have print-optimized styles. Many sites hide navigation, ads, and sidebars in print mode.

Produces cleaner PDFs by using the design the website creator intended for printing.

Parameter:
  • value (bool) - Set to true to use the print version of the page.
    Default:
    false

public HtmlToPdfClient setNoBackground(boolean value)

Do not print the background graphics to create printer-friendly PDFs. Use this when documents will be physically printed to save ink costs and improve readability.

Removes background colors, images, and patterns while preserving text and foreground content. Particularly useful for documents with dark backgrounds or decorative elements.

Parameter:
  • value (bool) - Set to true to disable the background graphics.
    Default:
    false

public HtmlToPdfClient setDisableJavascript(boolean value)

Do not execute JavaScript during conversion. Use this to improve conversion speed when JavaScript is not needed, prevent dynamic content changes, or avoid security risks from untrusted scripts.

Note that disabling JavaScript means lazy-loaded images and AJAX content will not load.

Parameter:
  • value (bool) - Set to true to disable JavaScript in web pages.
    Default:
    false

public HtmlToPdfClient setDisableImageLoading(boolean value)

Do not load images during conversion to create text-only PDFs. Use this to significantly speed up conversion, reduce file size, or create accessible text-focused documents.

Ideal for converting documentation where images are not needed, reducing bandwidth usage, or creating lightweight PDFs for email distribution.

Parameter:
  • value (bool) - Set to true to disable loading of images.
    Default:
    false

public HtmlToPdfClient setDisableRemoteFonts(boolean value)

Disable loading fonts from remote sources. Use this to speed up conversion by avoiding font download delays, ensure consistent rendering with system fonts, or work around font loading failures.

Note that text will fall back to system fonts, which may change the document's appearance.

Parameter:
  • value (bool) - Set to true to disable loading remote fonts.
    Default:
    false

public HtmlToPdfClient setUseMobileUserAgent(boolean value)

Deprecated Replaced with: setConverterUserAgent

Use a mobile user agent when making requests to the source URL.

Availability:
API client >= 5.3.0, converter >= 20.10. See versioning.
Parameter:
  • value (bool) - Set to true to use a mobile user agent.
    Default:
    false

public HtmlToPdfClient setLoadIframes(String iframes)

Specifies how iframes are handled during conversion. Use "all" to include all embedded content (videos, maps, widgets). Use "same-origin" to include only content from the same domain for security purposes. Use "none" to exclude all iframes for faster conversion and to avoid third-party content issues.

Disabling iframes can significantly improve performance and reliability.

Availability:
API client >= 5.0.0, converter >= 20.10. See versioning.
Parameter:
  • iframes
    Allowed Values:
    • all — All iframes are loaded.
    • same-origin — Only iframes with the same origin as the main page are loaded.
    • none — Iframe loading is disabled.
    Default:
    all

public HtmlToPdfClient setBlockAds(boolean value)

Automatically block common advertising networks and tracking scripts during conversion, producing cleaner PDFs with faster conversion times. Filters out third-party ad content, analytics beacons, and ad network resources.

Ideal for converting news sites, blogs, or any ad-heavy content where ads distract from the main message. May occasionally block legitimate third-party content - disable if critical third-party resources are missing.

Parameter:
  • value (bool) - Set to true to block ads in web pages.
    Default:
    false

public HtmlToPdfClient setDefaultEncoding(String encoding)

Specify the character encoding when the HTML lacks proper charset declaration or has incorrect encoding. Prevents garbled text for non-English content, especially legacy pages without UTF-8 encoding.

Set to "utf-8" for modern content, "iso-8859-1" for Western European legacy pages, or other encodings for specific regional content. Only needed when auto-detection fails and you see corrupted characters in the output.

Parameter:
  • encoding - The text encoding of the HTML content.
    Default:
    auto detect
Examples:
  • Set to use Latin-2 encoding: setDefaultEncoding("iso8859-2")
  • Set to use UTF-8 encoding: setDefaultEncoding("utf-8")

public HtmlToPdfClient setLocale(String locale)

Set the locale for the conversion to control regional formatting of dates, times, and numbers. Use this when converting content for specific regions - for example, set to "en-US" for MM/DD/YYYY dates and comma thousand separators, or "de-DE" for DD.MM.YYYY dates and period thousand separators.

Essential for financial reports, invoices, or localized content.

Availability:
API client >= 5.0.0, converter >= 20.10. See versioning.
Parameter:
  • locale - The locale code according to ISO 639.
    Default:
    en-US
Example:
  • Set to use Japanese locale: setLocale("ja-JP")

public HtmlToPdfClient setHttpAuth(String userName, String password)

Set credentials to access HTTP basic authentication protected websites. Use this when converting content behind HTTP authentication, such as development servers, staging environments, or password-protected documentation.

Provide both username and password to authenticate requests. Essential for converting internal resources or protected content.

Parameters:
  • userName - Set the HTTP authentication user name. Required to access protected web pages or staging environments.
  • password - Set the HTTP authentication password. Required to access protected web pages or staging environments.

public HtmlToPdfClient setCookies(String cookies)

Set HTTP cookies to be included in all requests made by the converter to access authenticated or session-based content. Use this when converting pages that require login, maintain user sessions, or personalize content based on cookies.

Essential for converting member-only areas, dashboards, or any content behind cookie-based authentication. Format as semicolon-separated name=value pairs.

Parameter:
  • cookies - The cookie string.
Example:
  • Multiple cookies for authentication: setCookies("session=6d7184b3bf35;token=2710")

public HtmlToPdfClient setVerifySslCertificates(boolean value)

Enforce SSL certificate validation for secure connections, preventing conversions from sites with invalid certificates. Enable when converting from production sites with valid certificates to ensure security.

When disabled, allows conversion from any HTTPS site regardless of certificate validity - including development servers with self-signed certificates, internal corporate sites with expired certificates, or local testing environments.

Parameter:
  • value (bool) - Set to true to enable SSL certificate verification.
    Default:
    false

public HtmlToPdfClient setFailOnMainUrlError(boolean failOnError)

Abort the conversion if the HTTP status code of the main URL is greater than or equal to 400 (client/server errors). Use this in automated workflows to catch broken URLs or authentication failures early rather than producing invalid PDFs. Ensures your system does not silently generate error page PDFs when source content is unavailable.

Parameter:
  • failOnError (bool) - Set to true to abort the conversion.
    Default:
    false

public HtmlToPdfClient setFailOnAnyUrlError(boolean failOnError)

Abort the conversion if any sub-request (images, stylesheets, scripts) fails with HTTP 400+ errors. Use this for strict quality control when all assets must load successfully.

Parameter:
  • failOnError (bool) - Set to true to abort the conversion.
    Default:
    false

public HtmlToPdfClient setNoXpdfcrowdHeader(boolean value)

Do not send the X-Pdfcrowd HTTP header in HTTP requests made by the converter. Use this if your target server blocks or logs requests with this header, or for privacy when you do not want sites to know you are using PDFCrowd. Some security systems may block requests with non-standard headers.

Parameter:
  • value (bool) - Set to true to disable sending X-Pdfcrowd HTTP header.
    Default:
    false

public HtmlToPdfClient setCssPageRuleMode(String mode)

Specifies behavior in the presence of CSS @page rules to control which settings take precedence. Use "default" to prioritize API settings over CSS rules, ensuring consistent output regardless of input HTML. Use "mode2" to respect CSS @page rules for print-optimized HTML.

This solves conflicts when CSS tries to override your API page setup.

Availability:
API client >= 5.0.0, converter >= 20.10. See versioning.
Parameter:
  • mode - The page rule mode.
    Allowed Values:
    • default — The PDFCrowd API page settings are preferred.
    • mode1 — The converter version 18.10 mode. Use for backward compatibility with legacy conversion behavior.
    • mode2 — CSS @page rule is preferred. Use when your HTML has print-optimized @page rules that should override API settings.
    Default:
    default

public HtmlToPdfClient setCustomCss(String css)

Apply custom CSS to the input HTML document to modify the visual appearance and layout of your content dynamically. Use this to override default styles, adjust spacing, change fonts, or fix layout issues without modifying the source HTML.

Use !important in your CSS rules to prioritize and override conflicting styles.

Availability:
API client >= 5.14.0, converter >= 20.10. See versioning.
Parameter:
  • css - A string containing valid CSS.
Examples:
  • Set the page background color to gray: setCustomCss("body { background-color: gray; }")
  • Do not show nav HTML elements and the element with ad-block ID in the output PDF: setCustomCss("nav, #ad-block { display: none !important; }")

public HtmlToPdfClient setCustomJavascript(String javascript)

Run a custom JavaScript after the document is loaded and ready to print. Use this to modify page content before conversion, remove unwanted elements, or trigger specific page states. The script is intended for post-load DOM manipulation (add/remove elements, update CSS, ...).

In addition to the standard browser APIs, the custom JavaScript code can use helper functions from our JavaScript library.

Parameter:
  • javascript - A string containing a JavaScript code.
Example:
  • Set the page background color to gray: setCustomJavascript("document.body.style.setProperty('background-color', 'gray', 'important')")

public HtmlToPdfClient setOnLoadJavascript(String javascript)

Run a custom JavaScript right after the document is loaded. The script is intended for early DOM manipulation (add/remove elements, update CSS, ...). In addition to the standard browser APIs, the custom JavaScript code can use helper functions from our JavaScript library.

Parameter:
  • javascript - A string containing a JavaScript code.
Example:
  • Set the page background color to gray: setOnLoadJavascript("document.body.style.setProperty('background-color', 'gray', 'important')")

public HtmlToPdfClient setCustomHttpHeader(String header)

Set a custom HTTP header to be included in all requests made by the converter. Use this to pass authentication tokens to protected sites, add tracking headers for analytics, or provide API keys for accessing private content.

Essential when converting content from APIs or internal systems that require special headers for access control.

Parameter:
  • header
    Constraint:
    • A string containing the header name and value separated by a colon.
Example:
  • API client tracking header: setCustomHttpHeader("X-My-Client-ID:k2017-12345")

public HtmlToPdfClient setJavascriptDelay(int delay)

Wait the specified number of milliseconds to finish all JavaScript after the document is loaded. Use this to ensure lazy-loaded images, AJAX content, or animations complete before conversion. Your license defines the maximum wait time by "Max Delay" parameter.

Parameter:
  • delay (int) - The number of milliseconds to wait.
    Constraint:
    • Must be a positive integer or 0.
    Default:
    200
Example:
  • Wait for 2 seconds: setJavascriptDelay(2000)

public HtmlToPdfClient setElementToConvert(String selectors)

Convert only the specified element from the main document and its children. Use this to extract specific portions of a page (like article content) while excluding navigation, headers, footers, or sidebars. The element is specified by one or more CSS selectors. If the element is not found, the conversion fails. If multiple elements are found, the first one is used.

Parameter:
Examples:
  • The first element with the id main-content is converted: setElementToConvert("#main-content")
  • The first element with the class name main-content is converted: setElementToConvert(".main-content")
  • The first element with the tag name table is converted: setElementToConvert("table")
  • The first element with the tag name table or with the id main-content is converted: setElementToConvert("table, #main-content")
  • The first element <p class="article"> within <div class="user-panel main"> is converted: setElementToConvert("div.user-panel.main p.article")

public HtmlToPdfClient setElementToConvertMode(String mode)

Control how CSS styles are applied when converting only part of a page. The "cut-out" option extracts the element into a new document root, which may break CSS selectors like "body > div". The "remove-siblings" option keeps the element in its original DOM position but deletes other elements, preserving descendant selectors. The "hide-siblings" option keeps all elements but hides non-selected ones with display:none, preserving all CSS context.

Parameter:
  • mode
    Allowed Values:
    • cut-out — The element and its children are cut out of the document.
    • remove-siblings — All element's siblings are removed from the DOM. Keeps target element in position but may break descendant CSS selectors.
    • hide-siblings — All element's siblings are hidden using display:none. Preserves CSS context while hiding non-target content.
    Default:
    cut-out

public HtmlToPdfClient setWaitForElement(String selectors)

Wait for the specified element in a source document. Use this when specific dynamic content must be ready before conversion, avoiding unnecessary delays from a fixed JavaScript delay. The element is specified by one or more CSS selectors. The element is searched for in the main document and all iframes.

If the element is not found, the conversion fails. Your license defines the maximum wait time by the "Max Delay" parameter.

Parameter:
Examples:
  • Wait until an element with the id main-content is found: setWaitForElement("#main-content")
  • Wait until an element with the class name main-content is found: setWaitForElement(".main-content")
  • Wait until an element with the tag name table is found: setWaitForElement("table")
  • Wait until an element with the tag name table or with the id main-content is found: setWaitForElement("table, #main-content")
  • Wait until <p class="article"> is found within <div class="user-panel main">: setWaitForElement("div.user-panel.main p.article")

public HtmlToPdfClient setAutoDetectElementToConvert(boolean value)

The main HTML element for conversion is detected automatically. Use this when you want to extract article or main content without knowing the exact CSS selector, automatically excluding navigation and sidebars.

Availability:
API client >= 5.5.0, converter >= 20.10. See versioning.
Parameter:
  • value (bool) - Set to true to detect the main element.
    Default:
    false

public HtmlToPdfClient setReadabilityEnhancements(String enhancements)

Automatically enhance the input HTML to improve readability by removing clutter and reformatting content. Use this when converting web pages with excessive navigation, ads, or sidebars that distract from the main content.

Different versions (v1-v4) use progressively aggressive algorithms - start with "v1" and increase if more cleanup is needed. Ideal for converting blog posts, articles, or documentation into clean PDFs.

Availability:
API client >= 5.5.0, converter >= 20.10. See versioning.
Parameter:
  • enhancements
    Allowed Values:
    • none — No enhancements are used.
    • readability-v1 — Version 1 of the enhancements is used. Basic cleanup for simple pages with moderate clutter.
    • readability-v2 — Version 2 of the enhancements is used. More aggressive cleanup for pages with more ads and navigation.
    • readability-v3 — Version 3 of the enhancements is used. Strong cleanup for heavily cluttered pages with multiple sidebars.
    • readability-v4 — Version 4 of the enhancements is used. Maximum cleanup for extremely cluttered pages. May remove some content.
    Default:
    none

PDF Format

Miscellaneous values for PDF output.

public HtmlToPdfClient setEnablePdfForms(boolean value)

Convert HTML forms to fillable PDF forms that users can complete in PDF readers. Use this to create interactive PDFs from HTML forms.

Ideal for creating fillable applications, surveys, or order forms that work offline. Details can be found in the blog post.

Parameter:
  • value (bool) - Set to true to make fillable PDF forms.
    Default:
    false

public HtmlToPdfClient setLinearize(boolean value)

Create linearized PDF. This is also known as Fast Web View. Use this to optimize PDFs for progressive download, allowing users to start viewing the first page while the rest downloads.

Parameter:
  • value (bool) - Set to true to create linearized PDF.
    Default:
    false

public HtmlToPdfClient setEncrypt(boolean value)

Encrypt the PDF to prevent search engines from indexing the contents and add an extra layer of security. Use this for confidential documents, internal reports, or any content you do not want appearing in search results.

Combine with a password to require authentication for viewing, or just use encryption alone to prevent indexing while keeping the PDF publicly readable.

Parameter:
  • value (bool) - Set to true to enable PDF encryption.
    Default:
    false

public HtmlToPdfClient setUserPassword(String password)

Protect the PDF with a user password to restrict who can open and view the document. Recipients must enter this password to view the PDF. Use this for confidential documents, sensitive data, or content distribution where you want to control access.

Combine with permission flags to restrict what users can do after opening.

Parameter:
  • password - The user password.
Example:
  • Simple document password: setUserPassword("123456")

public HtmlToPdfClient setOwnerPassword(String password)

Protect the PDF with an owner password for administrative control. This password allows changing permissions, passwords, and document restrictions - like a master key. Use different user and owner passwords to give recipients restricted access while retaining full control.

The owner password should be kept confidential and different from the user password.

Parameter:
  • password - The owner password.
Example:
  • Admin access password: setOwnerPassword("123456")

public HtmlToPdfClient setNoPrint(boolean value)

Disallow printing of the output PDF to protect sensitive content. Use this for confidential documents, copyrighted materials, or preview versions you want to restrict.

Parameter:
  • value (bool) - Set to true to set the no-print flag in the output PDF.
    Default:
    false

public HtmlToPdfClient setNoModify(boolean value)

Disallow modification of the output PDF to maintain document integrity. Use this for official documents, contracts, or records that should not be altered after creation. Prevents recipients from editing content, adding annotations, or extracting pages.

Parameter:
  • value (bool) - Set to true to set the read-only only flag in the output PDF.
    Default:
    false

public HtmlToPdfClient setNoCopy(boolean value)

Disallow text and graphics extraction from the output PDF to protect copyrighted content. Use this for ebooks, proprietary documents, or materials where you want to prevent easy copying and redistribution.

Parameter:
  • value (bool) - Set to true to set the no-copy flag in the output PDF.
    Default:
    false

public HtmlToPdfClient setTitle(String title)

Set the title of the PDF that appears in PDF reader title bars and document properties. Use descriptive titles for better organization and searchability in document management systems.

This metadata helps users identify documents when multiple PDFs are open and improves accessibility for screen readers.

Parameter:
  • title - The title.
Example:
  • Personal CV title: setTitle("My Resume")

public HtmlToPdfClient setSubject(String subject)

Set the subject of the PDF to categorize or summarize the document content. Use this to add searchable metadata for document management systems, improve organization in large PDF libraries, or provide context about the document's purpose.

Appears in PDF properties dialog.

Parameter:
  • subject - The subject.
Example:
  • Technical position subject: setSubject("CV - Software Developer")

public HtmlToPdfClient setAuthor(String author)

Set the author of the PDF for attribution and document tracking. Use this to identify who created the document, important for official documents, reports, or publications.

This metadata appears in PDF properties and helps with document management and version control.

Parameter:
  • author - The author.
Example:
  • Document author name: setAuthor("John Doe")

public HtmlToPdfClient setKeywords(String keywords)

Associate keywords with the document to improve searchability in document management systems. Use relevant terms that describe the content, making it easier to find documents later.

Separate multiple keywords with commas. Particularly useful for large document repositories or DAM systems.

Parameter:
  • keywords - The string with the keywords.
Example:
  • Technical skills for searchability: setKeywords("software developer, Unix, databases")

public HtmlToPdfClient setExtractMetaTags(boolean value)

Extract meta tags (author, keywords and description) from the input HTML and automatically populate PDF metadata. Use this when converting web pages that already have proper HTML meta tags, saving you from manually setting title, author, and keywords.

Ideal for automated conversion workflows where source HTML is well-structured.

Parameter:
  • value (bool) - Set to true to extract meta tags.
    Default:
    false

Viewer Preferences

These preferences specify how a PDF viewer should present the document. The preferences may be ignored by some PDF viewers.

public HtmlToPdfClient setPageLayout(String layout)

Control how pages appear when the PDF opens in viewers that respect these preferences. "single-page" for focused reading one page at a time. "one-column" for continuous scrolling like a web page. "two-column-left" for book-like layouts with odd pages on left (international standard). "two-column-right" for magazines with odd pages on right.

Parameter:
  • layout
    Allowed Values:
    • single-page — Display one page at a time.
    • one-column — Display the pages in one column.
    • two-column-left — Display the pages in two columns, with odd-numbered pages on the left.
    • two-column-right — Display the pages in two columns, with odd-numbered pages on the right.

public HtmlToPdfClient setPageMode(String mode)

Control the initial display mode when the PDF opens. "full-screen" for presentations and kiosk displays where you want an immersive experience. "thumbnails" for long documents where visual page navigation is helpful. "outlines" for structured documents with bookmarks/table of contents.

Parameter:
  • mode
    Allowed Values:
    • full-screen — Full-screen mode.
    • thumbnails — Thumbnail images are visible.
    • outlines — Document outline is visible.

public HtmlToPdfClient setInitialZoomType(String zoomType)

Control how the PDF is initially zoomed when opened.

Parameter:
  • zoomType
    Allowed Values:
    • fit-width — The page content is magnified just enough to fit the entire width of the page within the window.
    • fit-height — The page content is magnified just enough to fit the entire height of the page within the window.
    • fit-page — The page content is magnified just enough to fit the entire page within the window both horizontally and vertically. If the required horizontal and vertical magnification factors are different, use the smaller of the two, centering the page within the window in the other dimension.

public HtmlToPdfClient setInitialPage(int page)

Display the specified page when the document is opened.

Parameter:
  • page (int)
    Constraint:
    • Must be a positive integer.
Example:
  • Start at second page: setInitialPage(2)

public HtmlToPdfClient setInitialZoom(int zoom)

Specify the initial page zoom in percents when the document is opened.

Parameter:
  • zoom (int)
    Constraint:
    • Must be a positive integer.
Example:
  • Half-size zoom level: setInitialZoom(50)

public HtmlToPdfClient setHideToolbar(boolean value)

Hide the viewer's toolbar when the PDF is opened to provide a cleaner, more focused reading experience. Use this for presentations, kiosk displays, or immersive reading where you want minimal UI distractions.

Parameter:
  • value (bool) - Set to true to hide tool bars.
    Default:
    false

public HtmlToPdfClient setHideMenubar(boolean value)

Hide the viewer's menu bar when the PDF is opened for a cleaner interface. Use this for kiosk mode, presentations, or embedded PDFs where you want to minimize UI elements.

Parameter:
  • value (bool) - Set to true to hide the menu bar.
    Default:
    false

public HtmlToPdfClient setHideWindowUi(boolean value)

Hide user interface elements like scroll bars and navigation controls when the PDF opens. Use this for presentation mode, digital signage, or embedded PDFs where you want the most minimal interface possible.

Combines with other UI hiding options for full-screen immersive viewing.

Parameter:
  • value (bool) - Set to true to hide ui elements.
    Default:
    false

public HtmlToPdfClient setFitWindow(boolean value)

Resize the PDF viewer window to fit the size of the first displayed page when opened. Use this to ensure the PDF opens at an appropriate size rather than filling the entire screen.

Particularly useful for small documents, forms, or certificates that look better at actual size.

Parameter:
  • value (bool) - Set to true to resize the window.
    Default:
    false

public HtmlToPdfClient setCenterWindow(boolean value)

Position the PDF viewer window in the center of the screen when opened. Use this with window resizing to create a professional, centered display for forms, certificates, or small documents.

Improves the initial viewing experience by avoiding corner-positioned windows.

Parameter:
  • value (bool) - Set to true to center the window.
    Default:
    false

public HtmlToPdfClient setDisplayTitle(boolean value)

Display the title of the HTML document in the PDF viewer's title bar instead of the filename. Use this to show more descriptive titles when PDFs are opened - particularly useful when the filename is cryptic or auto-generated.

Improves user experience by showing meaningful document names.

Parameter:
  • value (bool) - Set to true to display the title.
    Default:
    false

public HtmlToPdfClient setRightToLeft(boolean value)

Set the predominant reading order for text to right-to-left. This option has no direct effect on the document's contents or page numbering but can be used to determine the relative positioning of pages when displayed side by side or printed n-up.

Parameter:
  • value (bool) - Set to true to set right-to-left reading order.
    Default:
    false

Data

Methods related to HTML template rendering.

public HtmlToPdfClient setDataString(String dataString)

Set the input data for template rendering. The data format can be JSON, XML, YAML or CSV.

Parameter:
  • dataString - The input data string.
Example:
  • Template variables for mail merge: setDataString("{"recipient": "Anna May", "sender": "John Doe"}")

public HtmlToPdfClient setDataFile(String dataFile)

Load the input data for template rendering from the specified file. The data format can be JSON, XML, YAML or CSV.

Parameter:
  • dataFile - The file path to a local file containing the input data.
Example:
  • External data for template rendering: setDataFile("/home/user/john/data.json")

public HtmlToPdfClient setDataFormat(String dataFormat)

Specify the input data format. Use "auto" for automatic detection or explicitly set to JSON, XML, YAML, or CSV when format is known.

Parameter:
  • dataFormat - The data format.
    Allowed Values:
    • auto — The data format is auto-detected.
    • json
    • xml
    • yaml
    • csv
    Default:
    auto

public HtmlToPdfClient setDataEncoding(String encoding)

Set the encoding of the data file set by setDataFile.

Parameter:
  • encoding - The data file encoding.
    Default:
    utf-8
Example:
  • Set to use Latin-2 encoding: setDataEncoding("iso8859-2")

public HtmlToPdfClient setDataIgnoreUndefined(boolean value)

Ignore undefined variables in the HTML template. The default mode is strict so any undefined variable causes the conversion to fail. You can use {% if variable is defined %} to check if the variable is defined.

Parameter:
  • value (bool) - Set to true to ignore undefined variables.
    Default:
    false

public HtmlToPdfClient setDataAutoEscape(boolean value)

Auto escape HTML symbols in the input data before placing them into the output.

Parameter:
  • value (bool) - Set to true to turn auto escaping on.
    Default:
    false

public HtmlToPdfClient setDataTrimBlocks(boolean value)

Auto trim whitespace around each template command block.

Parameter:
  • value (bool) - Set to true to turn auto trimming on.
    Default:
    false

public HtmlToPdfClient setDataOptions(String options)

Set the advanced data options:
  • csv_delimiter - The CSV data delimiter, the default is ,.
  • xml_remove_root - Remove the root XML element from the input data.
  • data_root - The name of the root element inserted into the input data without a root node (e.g. CSV), the default is data.
Parameter:
  • options - Comma separated list of options.
Examples:
  • Use semicolon to separate CSV data: setDataOptions("csv_delimiter=;")
  • Name the root of data rows and use the name in the template loop {% for row in rows %}...{% endfor %}: setDataOptions("data_root=rows")
  • Remove XML root so the HTML template can be simpler: setDataOptions("xml_remove_root=1")

Miscellaneous

public HtmlToPdfClient setDebugLog(boolean value)

Turn on debug logging to troubleshoot conversion issues. Details about the conversion process, including resource loading, rendering steps, and error messages are stored in the debug log. Use this when conversions fail or produce unexpected results. The URL of the log can be obtained from the getDebugLogUrl method or available in conversion statistics.

Parameter:
  • value (bool) - Set to true to enable debug logging.
    Default:
    false

public String getDebugLogUrl()

Get the URL of the debug log for the last conversion.

Returns:
String - The link to the debug log.

public int getRemainingCreditCount()

Get the number of conversion credits available in your account. Use this to monitor your credit usage and implement alerts before running out of credits.
This method can only be called after a call to one of the convertXtoY methods.
The returned value can differ from the actual count if you run parallel conversions.
The special value 999999 is returned if the information is not available.

Returns:
int - The number of credits.

public int getConsumedCreditCount()

Get the number of credits consumed by the last conversion. Use this to track costs per conversion, especially for complex documents or operations that may consume multiple credits.

Returns:
int - The number of credits.

public String getJobId()

Get the unique job ID for the conversion. Use this to track conversions in your logs, correlate with debug logs, or reference specific conversions when contacting support.

Returns:
String - The unique job identifier.

public int getPageCount()

Get the number of pages in the output document. Use this to validate conversion results, calculate pagination for user interfaces, or track document complexity metrics.

Returns:
int - The page count.

public int getTotalPageCount()

Get the total number of pages in the original output document, including the pages excluded by setPrintPageRange().

Returns:
int - The total page count.

public int getOutputSize()

Get the size of the output document in bytes. Use this to check file sizes before delivery, implement size-based quotas, or optimize storage allocation.

Returns:
int - The count of bytes.

public String getVersion()

Get the version details including API version, converter version, and client library version. Use this for debugging, logging, or ensuring compatibility when reporting issues.

Returns:
String - API version, converter version, and client version.

public HtmlToPdfClient setTag(String tag)

Tag the conversion with a custom value for tracking and analytics. Use this to categorize conversions by customer ID, document type, or business unit. The tag appears in conversion statistics. A value longer than 32 characters is cut off.

Parameter:
  • tag - A string with the custom tag.
Example:
  • Track job in analytics: setTag("client-1234")

public HtmlToPdfClient setHttpProxy(String proxy)

A proxy server used by the conversion process for accessing the source URLs with HTTP scheme. This can help circumvent regional restrictions or provide limited access to your intranet.

Parameter:
  • proxy
    Constraint:
    • The value must have format DOMAIN_OR_IP_ADDRESS:PORT.
Examples:
  • Corporate proxy server: setHttpProxy("myproxy.com:8080")
  • Direct IP proxy connection: setHttpProxy("113.25.84.10:33333")

public HtmlToPdfClient setHttpsProxy(String proxy)

A proxy server used by the conversion process for accessing the source URLs with HTTPS scheme. This can help circumvent regional restrictions or provide limited access to your intranet.

Parameter:
  • proxy
    Constraint:
    • The value must have format DOMAIN_OR_IP_ADDRESS:PORT.
Examples:
  • Secure proxy for HTTPS: setHttpsProxy("myproxy.com:443")
  • Direct secure proxy IP: setHttpsProxy("113.25.84.10:44333")

public HtmlToPdfClient setClientCertificate(String certificate)

A client certificate to authenticate the converter on your web server. The certificate is used for two-way SSL/TLS authentication (mutual TLS) and adds extra security. Use this when converting content from servers that require client certificate authentication for access.

Parameter:
  • certificate - The file must be in PKCS12 format.
    Constraint:
    • The file must exist and not be empty.
Example:
  • Custom CA certificate path: setClientCertificate("/home/user/john/pdfcrowd.crt")

public HtmlToPdfClient setClientCertificatePassword(String password)

A password for the PKCS12 file with a client certificate if the certificate file is password-protected.

Parameter:
  • password
Example:
  • PKCS12 certificate password: setClientCertificatePassword("123456")

Tweaks

Expert options for fine-tuning output.

public HtmlToPdfClient setLayoutDpi(int dpi)

Set the internal DPI resolution used for positioning of PDF contents. It can help in situations where there are small inaccuracies in the PDF. It is recommended to use values that are a multiple of 72, such as 288 or 360.

Availability:
API client >= 5.0.0, converter >= 20.10. See versioning.
Parameter:
  • dpi (int) - The DPI value.
    Constraint:
    • The accepted range is 72-600.
    Default:
    300
Example:
  • Low DPI for faster processing: setLayoutDpi(144)

public HtmlToPdfClient setContentAreaX(String x)

Set the top left X coordinate of the content area. It is relative to the top left X coordinate of the print area.

Parameter:
  • x
    Constraint:
    • The value must be specified in inches 'in', millimeters 'mm', centimeters 'cm', pixels 'px', or points 'pt'. It may contain a negative value.
    Default:
    0in
Examples:
  • Extend content beyond left margin: setContentAreaX("-1in")
  • Slight inset from print edge: setContentAreaX("10mm")

public HtmlToPdfClient setContentAreaY(String y)

Set the top left Y coordinate of the content area. It is relative to the top left Y coordinate of the print area.

Parameter:
  • y
    Constraint:
    • The value must be specified in inches 'in', millimeters 'mm', centimeters 'cm', pixels 'px', or points 'pt'. It may contain a negative value.
    Default:
    0in
Examples:
  • Extend content beyond left margin: setContentAreaY("-1in")
  • Slight inset from print edge: setContentAreaY("10mm")

public HtmlToPdfClient setContentAreaWidth(String width)

Set the width of the content area. It should be at least 1 inch.

Parameter:
  • width
    Constraint:
    • The value must be specified in inches 'in', millimeters 'mm', centimeters 'cm', pixels 'px', or points 'pt'.
    Default:
    The width of the print area.
Examples:
  • Content for letter-width viewport: setContentAreaWidth("8in")
  • Content for A4 portrait layout: setContentAreaWidth("210mm")

public HtmlToPdfClient setContentAreaHeight(String height)

Set the height of the content area. It should be at least 1 inch.

Parameter:
  • height
    Constraint:
    • The value must be specified in inches 'in', millimeters 'mm', centimeters 'cm', pixels 'px', or points 'pt'.
    Default:
    The height of the print area.
Examples:
  • Content for letter-width viewport: setContentAreaHeight("8in")
  • Content for A4 portrait layout: setContentAreaHeight("210mm")

public HtmlToPdfClient setContentArea(String x, String y, String width, String height)

Set the content area position and size. The content area enables you to specify a web page area to be converted.

Parameters:
  • x - Set the top left X coordinate of the content area. It is relative to the top left X coordinate of the print area.
    Constraint:
    • The value must be specified in inches 'in', millimeters 'mm', centimeters 'cm', pixels 'px', or points 'pt'. It may contain a negative value.
    Default:
    0in
  • y - Set the top left Y coordinate of the content area. It is relative to the top left Y coordinate of the print area.
    Constraint:
    • The value must be specified in inches 'in', millimeters 'mm', centimeters 'cm', pixels 'px', or points 'pt'. It may contain a negative value.
    Default:
    0in
  • width - Set the width of the content area. It should be at least 1 inch.
    Constraint:
    • The value must be specified in inches 'in', millimeters 'mm', centimeters 'cm', pixels 'px', or points 'pt'.
    Default:
    The width of the print area.
  • height - Set the height of the content area. It should be at least 1 inch.
    Constraint:
    • The value must be specified in inches 'in', millimeters 'mm', centimeters 'cm', pixels 'px', or points 'pt'.
    Default:
    The height of the print area.

public HtmlToPdfClient setContentsMatrix(String matrix)

A 2D transformation matrix applied to the main contents on each page. The origin [0,0] is located at the top-left corner of the contents. The resolution is 72 dpi.

Availability:
API client >= 5.0.0, converter >= 20.10. See versioning.
Parameter:
  • matrix - A comma separated string of matrix elements: "scaleX,skewX,transX,skewY,scaleY,transY"
    Default:
    1,0,0,0,1,0
Examples:
  • Fine tune the contents height: setContentsMatrix("1,0,0,0,1.001,0")
  • Translate the contents by -10 points in both directions: setContentsMatrix("1,0,-10,0,1,-10")

public HtmlToPdfClient setHeaderMatrix(String matrix)

A 2D transformation matrix applied to the page header contents. The origin [0,0] is located at the top-left corner of the header. The resolution is 72 dpi.

Availability:
API client >= 5.0.0, converter >= 20.10. See versioning.
Parameter:
  • matrix - A comma separated string of matrix elements: "scaleX,skewX,transX,skewY,scaleY,transY"
    Default:
    1,0,0,0,1,0
Examples:
  • Fine tune the header contents height: setHeaderMatrix("1,0,0,0,1.001,0")
  • Translate the header contents by -10 points in both directions: setHeaderMatrix("1,0,-10,0,1,-10")

public HtmlToPdfClient setDisablePageHeightOptimization(boolean value)

Disable automatic height adjustment that compensates for pixel to point rounding errors.

Availability:
API client >= 5.0.0, converter >= 20.10. See versioning.
Parameter:
  • value (bool) - Set to true to disable automatic height scale.
    Default:
    false

public HtmlToPdfClient setMainDocumentCssAnnotation(boolean value)

Add special CSS classes to the main document's body element. This allows applying custom styling based on these classes:
  • pdfcrowd-page-X - where X is the current page number
  • pdfcrowd-page-odd - odd page
  • pdfcrowd-page-even - even page
Availability:
API client >= 5.0.0, converter >= 20.10. See versioning.
Parameter:
  • value (bool) - Set to true to add the special CSS classes.
    Default:
    false
Example:

public HtmlToPdfClient setMaxLoadingTime(int maxTime)

Set the maximum time for loading the page and its resources. After this time, all requests will be considered successful. This can be useful to ensure that the conversion does not timeout. Use this method if there is no other way to fix page loading.

Availability:
API client >= 5.15.0, converter >= 20.10. See versioning.
Parameter:
  • maxTime (int) - The number of seconds to wait.
    Constraint:
    • The accepted range is 10-30.

public HtmlToPdfClient setConversionConfig(String jsonString)

Configure conversion via JSON. The configuration defines various page settings for individual PDF pages or ranges of pages. It provides flexibility in designing each page of the PDF, giving control over each page's size, header, footer, etc. If a page or parameter is not explicitly specified, the system will use the default settings for that page or attribute. If a JSON configuration is provided, the settings in the JSON will take precedence over the global options.

The structure of the JSON must be:

  • pageSetup: An array of objects where each object defines the configuration for a specific page or range of pages. The following properties can be set for each page object:
    • pages: A comma-separated list of page numbers or ranges. Special strings may be used, such as odd, even, and last. For example:
      • 1-: from page 1 to the end of the document
      • 2: only the 2nd page
      • 2,4,6: pages 2, 4, and 6
      • 2-5: pages 2 through 5
      • odd,2: the 2nd page and all odd pages
    • pageSize: The page size (optional). Possible values: A0, A1, A2, A3, A4, A5, A6, Letter.
    • pageWidth: The width of the page (optional).
    • pageHeight: The height of the page (optional).
    • marginLeft: Left margin (optional).
    • marginRight: Right margin (optional).
    • marginTop: Top margin (optional).
    • marginBottom: Bottom margin (optional).
    • displayHeader: Header appearance (optional). Possible values:
      • none: completely excluded
      • space: only the content is excluded, the space is used
      • content: the content is printed (default)
    • displayFooter: Footer appearance (optional). Possible values:
      • none: completely excluded
      • space: only the content is excluded, the space is used
      • content: the content is printed (default)
    • headerHeight: Height of the header (optional).
    • footerHeight: Height of the footer (optional).
    • orientation: Page orientation, such as "portrait" or "landscape" (optional).
    • backgroundColor: Page background color in RRGGBB or RRGGBBAA hexadecimal format (optional).

Dimensions may be empty, 0 or specified in inches "in", millimeters "mm", centimeters "cm", pixels "px", or points "pt".

Availability:
API client >= 6.1.0, converter >= 24.04. See versioning.
Parameter:
  • jsonString - The JSON string.
Examples:
  • Modify the margins and orientation, and hide the header and footer on some pages. 
    {
  "pageSetup": [
    {
      "pages": "1,3",
      "marginLeft": "72pt",
      "marginRight": "72pt",
      "marginTop": "72pt",
      "marginBottom": "72pt",
      "displayHeader": "content",
      "displayFooter": "none"
    },
    {
      "pages": "2-5",
      "orientation": "landscape",
      "marginTop": "0",
      "marginBottom": "0",
      "headerHeight": "1cm",
      "displayHeader": "content",
      "displayFooter": "none"
    },
    {
      "pages": "10",
      "pageWidth": "6in",
      "pageHeight": "10in",
      "displayHeader": "none",
      "displayFooter": "content"
    },
    {
      "pages": "last",
      "backgroundColor": "00ff0080"
    }
  ]
}
  • A header is placed only on the first page, and a footer only on the last page. No space is occupied on other pages. 
    {
  "pageSetup": [
    {
      "pages": "1-",
      "displayHeader": "none",
      "displayFooter": "none"
    },
    {
      "pages": "1",
      "displayHeader": "content"
    },
    {
      "pages": "last",
      "displayFooter": "content"
    }
  ]
}

public HtmlToPdfClient setConversionConfigFile(String filepath)

Configure the conversion process via JSON file. See details of the JSON string.

Availability:
API client >= 6.1.0, converter >= 24.04. See versioning.
Parameter:
  • filepath - The file path to a local file.
    Constraint:
    • The file must exist and not be empty.
Examples:
  • External conversion settings: setConversionConfigFile("/home/user/john/conv_config.json")
  • see example of the JSON string

public HtmlToPdfClient setConverterUserAgent(String agent)

Specify the User-Agent HTTP header that will be used by the converter when a request is made to the converted web page.

Availability:
API client >= 6.4.0 See versioning.
Parameter:
  • agent - The user agent.
    Allowed Values:
    • chrome-desktop — The user-agent for desktop chrome corresponding to the converter used.
    • chrome-mobile — The user-agent for mobile chrome corresponding to the converter used.
    • latest-chrome-desktop — The user-agent of the recently released Chrome browser on desktops.
    • latest-chrome-mobile — The user-agent of the recently released Chrome browser on mobile devices.
    • custom string — A custom string for the user agent.
    Default:
    latest-chrome-desktop
Examples:
  • Mimic the recent chrome on mobiles: setConverterUserAgent("latest-chrome-mobile")
  • Mimic Safari 18.0 browser: setConverterUserAgent("Mozilla/5.0 (Macintosh; Intel Mac OS X 14_7_1) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/18.0 Safari/605.1.15")

API Client Options

public HtmlToPdfClient setConverterVersion(String version)

Set the converter version. Different versions may produce different output. Choose which one provides the best output for your case.

Availability:
API client >= 5.0.0. See versioning.
Parameter:
  • version - The version identifier.
    Allowed Values:
    • 24.04 — Version 24.04.
    • 20.10 — Version 20.10.
    • 18.10 — Version 18.10.
    • latest — Version 20.10 is used.
    Default:
    24.04

public HtmlToPdfClient setUseHttp(boolean value)

Specify whether to use HTTP or HTTPS when connecting to the PDFCrowd API.

Parameter:
  • value (bool) - Set to true to use HTTP.
    Default:
    false

public HtmlToPdfClient setClientUserAgent(String agent)

Specify the User-Agent HTTP header that the client library will use when interacting with the API.

Availability:
API client >= 6.4.0 See versioning.
Parameter:
  • agent - The user agent string.

public HtmlToPdfClient setUserAgent(String agent)

Deprecated Replaced with: setClientUserAgent

Set a custom user agent HTTP header. It can be useful if you are behind a proxy or a firewall.

Parameter:
  • agent - The user agent string.
    Default:
    pdfcrowd_java_client/6.5.4 (https://pdfcrowd.com)

public HtmlToPdfClient setProxy(String host, int port, String userName, String password)

Specify an HTTP proxy that the API client library will use to connect to the internet.

Parameters:
  • host - The proxy hostname.
  • port (int) - The proxy port.
  • userName - The username.
  • password - The password.

public HtmlToPdfClient setRetryCount(int count)

Specify the number of automatic retries when a 502 or 503 HTTP status code is received. The status code indicates a temporary network issue. This feature can be disabled by setting to 0.

Parameter:
  • count (int) - Number of retries.
    Default:
    1
Example:
  • Retry failed requests three times: setRetryCount(3)