PDF Generation

PSPDFKit API allows you to create PDF documents from an HTML file. You do this by supplying a Part containing the html key to the POST https://api.pspdfkit.com/build endpoint. Here’s a schema outlining all the available options:

JavaScript
    type Orientation = "landscape" | "portrait";
    type PageSize =
      | "A0"
      | "A1"
      | "A2"
      | "A3"
      | "A4"
      | "A5"
      | "A6"
      | "A7"
      | "A8"
      | "Letter"
      | "Legal";
    
    // Represents one part that was sent in the multipart request. Should be the 
    // `name` that was specified for the part.
    type MultipartReference = string;
    
    type HTMLPart = {
      html: MultipartReference, // The HTML file passed in the multipart request.
      assets?: Array<MultipartReference>, // All assets imported in the HTML. Reference the name passed in the multipart request.
      layout?: {
        orientation?: Orientation,
        size?: {
          width: number,
          height: number
        } | PageSize, // {width, height} in mm or page size preset.
        margin?: {
          // Margin sizes in mm.
          left: number,
          top: number,
          right: number,
          bottom: number
        }
      }
    };

The only mandatory key for an HTML Part is the html key pointing to the main HTML file to use for generating the PDF. All other keys are optional.

Referencing Assets

When designing an HTML page, it’s common to split the design into multiple files, such as an HTML file, a CSS file, fonts, and image files. The PDF Generation command expects a flat directory structure, so any referenced assets have to reside next to the HTML file and not in subdirectories.

The following shows how you’d send a CSS file that’s referenced in the HTML file:

HTML
    <!DOCTYPE html>
    <head>
      <link rel="stylesheet" href="style.css" />
    </head>
    <html>
      <body>
        <h1>PDF Generation Header</h1>
        <img src="my-image.jpg">
      </body>
    </html>

CSS
    @font-face {
      font-family: "Open Sans";
      src: url("OpenSans-Regular.ttf") format("truetype");
    }
    
    h1 {
      font-size: xx-large;
      font-family: "Open Sans", sans-serif;
    }

The request to create a PDF from these assets would look like this:

Shell
    curl -X POST https://api.pspdfkit.com/build \
        -H "Authorization: Bearer your_api_key_here" \
        -o result.pdf \
        -F page.html=@/path/to/page.html \
        -F style.css=@/path/to/style.css \
        -F my-image.jpg=@/path/to/my-image.jpg \
        -F OpenSans-Regular.ttf=@/path/to/OpenSans-Regular.ttf \
        -F instructions='{
            "parts": [
              {
                "html": "page.html",
                "assets": [
                  "style.css",
                  "my-image.jpg",
                  "OpenSans-Regular.ttf"
                ]
              }
            ]
          }'

Please note that JavaScript assets currently aren’t supported.

Assets passed in the multipart request must match the name used to reference the file in HTML. For example, if you have an image block, <img src="my-image.jpg">, the data representing the image in the multipart request should have the name my-image.jpg.

Page Layout

The layout object, which is part of the HTML Part, allows for customization of the PDF page layout and dimensions. All figures in this object are in reference to millimeters, and all pages will take on this configuration.

Fillable Forms

PSPDFKit API can also generate PDFs containing fillable form fields from HTML.

Because not all HTML form fields map directly to PDF forms, a subset of form fields is supported. The following table shows how the HTML input element types map to PDF form types.

input type PDF Form Field
text Text box
password Text box where all characters are replaced with *
radio Radio button
checkbox Checkbox
select Combo box

All other input types aren’t supported and won’t be converted to PDF form fields.

Form Values

All form values and radio buttons/checkboxes that are checked in HTML will be carried over to the form field values in the generated PDF.