# PDFMonkey Documentation

> Generate PDF documents from HTML templates via API



---

# From zero to generating your first Document

Source: https://pdfmonkey.io/docs/getting-started/from-zero-to-first-document.md
## Create an account on PDFMonkey

To create an account, go to [the Register page](https://dashboard.pdfmonkey.io/register) and fill in your email and password.

> [!NOTE]
> We do not ask for a password confirmation but you can toggle password hiding by clicking on _Show my password_.


Once you've filled in your credentials, we will send you an activation email. Click the link in the email to activate your account. **You will not be able to sign in until your account is confirmed.**

## Sign in

Once your account confirmed, fill in your credentials in [the Sign in page](https://dashboard.pdfmonkey.io/login) to get access to your dashboard.

## Create your first Template

To create a template, head to [the Templates page](https://dashboard.pdfmonkey.io/templates) and click on **Create my first Template**.

Give a name to your template, select the **Code** edition mode and select the _Base Template_ named **Blank**.

It will open the Template Editor, where PDFMonkey's magic happens.

> [!NOTE]
> You can change the name of your Template as often as you want, it will have no impact on your client applications.


## Writing your first Template

In the **HTML** tab, insert the following code:

```liquid
<p>Hello {{name}}!</p>
```

In the **CSS** tab, insert the following code:

```css
p {
  color: #6D28D9;
  font-size: 24px;
}
```

And finally in the **Test data** tab, insert this:

```json
{
  "name": "Peter Parker"
}
```

You can now click on the **Save** button, and you should see the preview panel on the right update to reflect your changes.

> [!NOTE]
> **Real PDF preview**
>
> The PDF preview you see is actually a 100% accurate version of what the final result will be as it is a real PDF, generated using the same process we use to generate your Documents.


The last step is to make your Template available for generation. To do so, click on the **Publish** button.

For more on template syntax, see the [Code Templates](https://pdfmonkey.io/docs/code-templates) section. Learn about [using dynamic data](https://pdfmonkey.io/docs/code-templates/defining-dynamic-data.md) to preview your templates.

## Generating your first Document

Now that your Template is complete, let's head to [the Documents page](https://dashboard.pdfmonkey.io/documents).

Once there, click on the **Create my first Document** button. In the next page, select your template from the dropdown list presented to you and click on **Create a draft**.

It will open the Document Editor, letting you specify data and meta-data for your Document.

By default you will be shown an editable copy of the test data you've added to your Template. Let's update it to the following:

```json
{
  "name": "Spider-man"
}
```

Now head to the **Meta data** tab and insert the following to [customise the PDF filename](https://pdfmonkey.io/docs/generating-documents/custom-filename.md):

```json
{
  "_filename": "hello-spider-man.pdf"
}
```

Click on the **Save** button. The preview will refresh, showing you an up-to-date version of the PDF.

Finally click on **Generate**.

That's it! You generated your very first Document with PDFMonkey!

If something goes wrong, check the [Troubleshooting](https://pdfmonkey.io/docs/troubleshooting) section.


---

# Dashboard UI Tour

Source: https://pdfmonkey.io/docs/getting-started/dashboard-ui-tour.md
This page gives you a quick tour of the main areas of the PDFMonkey dashboard. Each section links to more detailed documentation so you can dive deeper when you are ready.

## Templates

![Templates list page showing template cards and workspace selector](https://pdfmonkey.io/docs/img/dashboard-templates-list.webp)

The Templates page is the first thing you see after signing in. It lists every template in your current workspace, displayed as cards showing the template name, its status (draft or published), and when it was last modified.

From this page you can:

- **Create a new template** using the _Create Template_ button at the top of the page.
- **Duplicate or delete** a template from its context menu.

To learn how to build a template from scratch, see [Your First Template (Builder)](https://pdfmonkey.io/docs/builder-templates/your-first-template.md) or the [Code Templates](https://pdfmonkey.io/docs/code-templates) section.

## Template Editor

![Template editor with HTML, CSS, and Test Data tabs alongside the live preview pane](https://pdfmonkey.io/docs/img/dashboard-template-editor.webp)

The template editor is where you design your PDF layout and preview the result in real time. PDFMonkey offers two editing modes:

- **Code editor** -- Write HTML, CSS, and Liquid markup directly. The editor has three tabs: _HTML_, _CSS_, and _Test Data_. Changes are reflected in the preview pane on the right after you save.
- **Builder** -- A drag-and-drop interface that lets you assemble pages from pre-built blocks without writing code.

The preview pane renders a real PDF using the same engine that produces your final documents, so what you see is exactly what your users will receive.

When your template is ready, click **Publish** to make it available for document generation. Only published templates can be used to create documents through the API or integrations.

For a hands-on walkthrough, see [From Zero to First Document](https://pdfmonkey.io/docs/getting-started/from-zero-to-first-document.md).

## Documents

![Documents page listing generated documents with status indicators and filters](https://pdfmonkey.io/docs/img/dashboard-documents.webp)

The Documents page shows every document that has been generated in your workspace. Each entry displays the document name, the template it was created from, its current status, and when it was generated.

Documents go through several statuses during their lifecycle:

- **Draft** -- Created but not yet sent for generation.
- **Pending** -- Queued for generation.
- **Generating** -- Currently being rendered.
- **Success** -- Generation complete; the PDF is ready to download.
- **Failure** -- Something went wrong during generation.

You can filter the list by template or by status to find specific documents quickly. The **Create Document** button lets you generate a document manually by selecting a template and providing JSON data.

For a detailed breakdown of each status, see [Document Statuses](https://pdfmonkey.io/docs/generating-documents/document-statuses.md).

## Settings

![Settings page showing workspace name and workspace ID](https://pdfmonkey.io/docs/img/dashboard-settings.webp)

The Settings page lets you manage your workspace identity.

From this page you can:

- **Rename your workspace** -- Edit the workspace name and click _Save_ to apply the change.
- **Copy your Workspace ID** -- The unique identifier for your workspace, useful when contacting support or working with the API.


## FAQ

**What are the main sections of the PDFMonkey dashboard?**

The dashboard has four main areas: Templates (listing all templates in your workspace), the Template Editor (for designing PDF layouts with code or the visual builder), Documents (showing generated documents and their statuses), and Settings (for managing workspace identity).

**What document statuses exist in PDFMonkey?**

Documents go through five statuses: Draft (created but not queued), Pending (queued for generation), Generating (currently rendering), Success (PDF ready to download), and Failure (something went wrong during generation).

**Does the PDFMonkey template editor show a real preview?**

Yes. The preview pane renders a real PDF using the same engine that produces your final documents, so what you see in the editor is exactly what your users will receive.


---

# PDFMonkey 30-Day Pro Trial: Features, Limits, and What Happens Next

Source: https://pdfmonkey.io/docs/getting-started/the-30-day-trial.md
Every new PDFMonkey account starts with a **30-day Pro trial** so you can explore premium features before choosing a plan. During the trial you have access to the same capabilities as the [Pro plan](https://pdfmonkey.io/docs/pricing-and-billing/our-plans.md#pro), with no credit card required.

## What the trial includes {#what-the-trial-includes}

| Feature | Trial (Pro) | Free plan (after trial) |
|:--------|:-----------:|:-----------------------:|
| Document generations | 300/month | 20/month |
| [External resources](https://pdfmonkey.io/docs/getting-started/external-resources.md) (images, fonts, CSS, JS via URL) | Yes | No |
| Max generation time per document | 2 minutes | 30 seconds |
| [Document retention](https://pdfmonkey.io/docs/generating-documents/retention-and-deletion.md) | 24 hours | 24 hours |

> [!NOTE]
> **No payment required**
>
> The trial activates automatically when you [create your account](https://pdfmonkey.io/docs/getting-started/from-zero-to-first-document.md). You are never charged during the trial, and you do not need to cancel anything.


## What changes when the trial ends? {#what-changes-when-the-trial-ends}

When the 30-day trial expires, your account **downgrades to the Free plan** automatically. You are not charged. The main differences you will notice:

- **External resources stop working.** Images, CSS, JavaScript, and fonts loaded via URL are restricted on the Free plan. Documents that reference them will fail at generation time. See [External Resources](https://pdfmonkey.io/docs/getting-started/external-resources.md) for the full definition of what counts.
- **Your generation quota drops to 20 documents per month** instead of 300.
- **Max generation time drops to 30 seconds** instead of 2 minutes.

> [!TIP]
> **Upgrade before the trial ends**
>
> If the trial features match your needs, [upgrade to a paid plan](https://pdfmonkey.io/docs/pricing-and-billing/changing-my-plan.md) any time during or after the trial. Changes take effect immediately and billing is prorated. See [Our Plans](https://pdfmonkey.io/docs/pricing-and-billing/our-plans.md) for a full comparison.


## What you can use on the Free plan {#what-can-i-use-on-the-free-plan}

After the trial, the following resources continue working on the Free plan because they do not count as external resources:

- **Images** loaded using [data-uri or inline SVG](https://pdfmonkey.io/docs/code-templates/images.md)
- **CSS** written directly in the template's HTML or CSS tab
- **CSS** sent in the document's dynamic data and inlined in the HTML using a variable
- **JavaScript** written directly in the template's HTML tab
- **JavaScript** stored in the document's dynamic data and inlined in the HTML using a variable
- **Hosted Tailwind CSS** versions that PDFMonkey provides (see [Hosted Tailwind CSS Versions](https://pdfmonkey.io/docs/code-templates/custom-css.md#hosted-tailwind-css-versions))

For more detail on what qualifies as an external resource and what does not, see the dedicated [External Resources](https://pdfmonkey.io/docs/getting-started/external-resources.md) page.

## Frequently asked questions {#faq}

**Can I extend the trial?**

The trial is a one-time, 30-day window per account. That said, we understand that sometimes you may have missed the trial entirely or need more time to evaluate the product. If that is your situation, [contact our support team](https://pdfmonkey.io/docs/getting-started/support.md) and we will see what we can do.

**What happens to my documents when the trial ends?**

Your existing documents are not deleted. They remain accessible according to the [retention settings](https://pdfmonkey.io/docs/generating-documents/retention-and-deletion.md) on your templates. Only new generation requests are affected by the Free plan limits.

**Can I upgrade before the trial ends?**

Yes. You can [switch to any paid plan](https://pdfmonkey.io/docs/pricing-and-billing/changing-my-plan.md) at any point during the trial. The change takes effect immediately.

**Do unused trial documents roll over?**

No. Your monthly quota resets at the start of each billing cycle. Unused documents do not carry over. See [Reaching Your Quota](https://pdfmonkey.io/docs/pricing-and-billing/our-plans.md#reaching-your-quota) for details.

## Related pages {#related-pages}

- [From Zero to First Document](https://pdfmonkey.io/docs/getting-started/from-zero-to-first-document.md): get started with your first template and document
- [External Resources](https://pdfmonkey.io/docs/getting-started/external-resources.md): what counts as an external resource and free-plan alternatives
- [Our Plans](https://pdfmonkey.io/docs/pricing-and-billing/our-plans.md): compare all plan tiers side by side
- [Changing My Plan](https://pdfmonkey.io/docs/pricing-and-billing/changing-my-plan.md): how upgrades, downgrades, and proration work
- [Document Retention and Deletion](https://pdfmonkey.io/docs/generating-documents/retention-and-deletion.md): TTL settings and plan-based retention limits


## FAQ

**What does the PDFMonkey 30-day trial include?**

The trial gives you Pro-level access for 30 days: 300 document generations per month, external resources (images, fonts, CSS, and JS via URL), and a 2-minute maximum generation time per document.

**What happens when the PDFMonkey trial ends?**

Your account automatically downgrades to the Free plan at no charge. External resources stop working, your generation quota drops to 20 documents per month, and the maximum generation time drops to 30 seconds.

**Do I need a credit card for the PDFMonkey trial?**

No. The trial activates automatically when you create your account. You are never charged during the trial and you do not need to cancel anything.

**Can I upgrade during the PDFMonkey trial?**

Yes. You can switch to any paid plan at any point during the trial. The change takes effect immediately and billing is prorated.


---

# External Resources in PDFMonkey

Source: https://pdfmonkey.io/docs/getting-started/external-resources.md
# External Resources

PDFMonkey templates can load assets from external URLs -- images, stylesheets, scripts, and fonts. These are called **external resources**, and their availability depends on your plan. This page explains what qualifies, how to tell if your template uses one, and what to do if you are on the Free plan.

## What Counts as an External Resource?

An external resource is any file your template loads via a URL (`http://...` or `https://...`). This includes:

* **Remote images** -- loaded from a server or CDN ([data-uri and inline SVG](https://pdfmonkey.io/docs/code-templates/images.md) still work on all plans)
* **CSS files** -- stylesheets hosted on your servers or a CDN
* **JavaScript files** -- scripts hosted on your servers or a CDN
* **Web fonts** -- like Google Fonts or Bunny Fonts
* **Visual Editor fonts** -- any font selected in the builder's font-family picker

### How to tell if your template uses external resources

Look for URLs in your template code. Anything that starts with `http://` or `https://` is an external resource:

```html
<!-- External resources -- require a paid plan -->
<script src="https://cdn.jsdelivr.net/npm/chart.js"></script>
<link rel="stylesheet" href="https://example.com/styles.css" />
<img src="https://example.com/logo.png" />
```

```css
/* Also external */
@import url("https://fonts.googleapis.com/css2?family=Inter&display=swap");
```

Resources written directly in your template are **not** external resources and work on every plan:

```html
<!-- Inline resources -- work on all plans -->
<script>console.log('inline JS');</script>
<style>h1 { color: red; }</style>
<img src="data:image/png;base64,iVBOR..." />
<svg xmlns="http://www.w3.org/2000/svg">...</svg>
```

## Plan Availability

External resources are available on **all paid plans** and during the **30-day Pro trial**. On the Free plan, documents that reference external resources will **fail at generation time**.

For a full breakdown of what each plan includes, see [Our Plans](https://pdfmonkey.io/docs/pricing-and-billing/our-plans.md). For details on what the trial unlocks, see [30-day Pro trial](https://pdfmonkey.io/docs/getting-started/the-30-day-trial.md).

> [!TIP]
> **Free-plan alternatives**
>
> You can still build full-featured templates on the Free plan using inline CSS, inline JavaScript, data-uri images, and inline SVG. See [What you can use on the Free plan](https://pdfmonkey.io/docs/getting-started/the-30-day-trial.md#what-can-i-use-on-the-free-plan) for the full list.


## PDFMonkey-Hosted Resources

Resources hosted on PDFMonkey's own servers (`pdfmonkey-resources.s3-eu-west-3.amazonaws.com`) are the exception: they work on **all plans**, including Free.

The most common example is the hosted Tailwind CSS builds. See [Hosted Tailwind CSS Versions](https://pdfmonkey.io/docs/code-templates/custom-css.md#hosted-tailwind-css-versions) for the full list of available versions.


## FAQ

**Can I use web fonts in PDFMonkey templates?**

Yes, but only on paid plans (Starter and above). Web fonts loaded via URL (e.g., Google Fonts) count as external resources. On the Free plan, use system fonts or embed fonts as Base64 data URIs instead.

**What counts as an external resource in PDFMonkey?**

Any file your template loads via a URL (http:// or https://) is an external resource. This includes remote images, CSS files, JavaScript files, web fonts, and fonts selected in the Builder's font picker. Inline code and data URIs are not external resources and work on all plans.

**Why are my images or fonts not loading in PDFMonkey?**

If you are on the Free plan, external resources (remote images, web fonts, external CSS/JS) are not available. Upgrade to Starter or higher, or switch to inline alternatives: Base64 data URIs for images, inline SVGs, or system fonts.


---

# Builder vs. Code Templates

Source: https://pdfmonkey.io/docs/getting-started/builder-vs-code-templates.md
PDFMonkey offers two ways to create templates: the visual **[Builder](https://pdfmonkey.io/docs/builder-templates)** and **[Code Templates](https://pdfmonkey.io/docs/code-templates)** written in HTML, CSS, and Liquid. Both produce the same high-quality PDFs. The difference is how you design them, and you'll want to pick the right approach before you start.

## Comparison at a glance {#builder-vs-code-templates}

| | Builder | Code Templates |
|---|---|---|
| **Design method** | Visual drag-and-drop | Write HTML, CSS, and Liquid |
| **Dynamic data** | Logic panel (conditions, repetition) | Liquid tags (`{% if %}`, `{% for %}`) |
| **Styling** | Styles panel + Custom CSS editor | Full CSS control in the template |
| **JavaScript** | Custom JS editor + External Assets | `<script>` tags in template HTML |
| **Learning curve** | Lower, no coding required | Higher, requires HTML/CSS/Liquid knowledge |
| **PDF renderer** | Chromium | Chromium |
| **Output quality** | Identical | Identical |

## When to use the Builder {#when-to-use-the-builder}

The [Builder](https://pdfmonkey.io/docs/builder-templates) is a good fit when:

- You want to create standard business documents (invoices, receipts, certificates, reports) without writing code.
- Non-technical team members need to create or edit templates.
- You want a point-and-click workflow instead of writing markup.
- Your layout needs are straightforward: headers, text content, images, tables, and repeated sections.

## When to use Code Templates {#when-to-use-code-templates}

[Code Templates](https://pdfmonkey.io/docs/code-templates) are a better choice when:

- You're comfortable with HTML and CSS. You'll move faster writing markup directly than dragging blocks around.
- You need pixel-perfect control over complex multi-page layouts with custom page breaks.
- Your documents require advanced Liquid logic: nested loops, custom filters, or complex conditionals.
- You have existing HTML and CSS that you want to reuse.
- You need features not yet available in the Builder.

## The Builder does not use Liquid {#the-builder-does-not-use-liquid}

Builder templates use **Vue** under the hood, not Liquid. This means Liquid syntax like `{% if %}`, `{% for %}`, and Liquid filters (`| upcase`, `| date`) will not work in the Builder. Dynamic data is handled through Vue's template engine and the Logic panel instead.

One practical consequence: **variable names that start with a number** are not valid JavaScript identifiers, so you cannot write `{{123varname}}` in a text binding. Use the bracket notation on the payload object instead:

```
{{$docPayload['123varname']}}
```

If you are coming from Code Templates, keep in mind that any Liquid-specific pattern will need to be rethought for the Builder's Vue-based approach.

## Can I switch between them? {#can-i-switch-between-them}

Short answer: no. Builder templates and Code Templates are separate template types. You cannot convert a Builder template into a Code Template or vice versa. Choose the approach that fits your use case before you start designing.

> [!TIP]
> Not sure which to pick? Start with the Builder. If you hit a limitation, you can always create a new Code Template for that specific document. Many teams use both approaches for different document types.


## How the Builder works under the hood {#how-the-builder-works}

The Builder combines Vue components, Tailwind CSS utility classes, and Chromium rendering to turn your visual design into a PDF. You never need to interact with these technologies directly. Both Builder and Code Templates use the same Chromium engine, so the final PDF quality is identical. For details on engine versions and capabilities, see [Our Engines](https://pdfmonkey.io/docs/code-templates/our-engines.md).

## What PDFMonkey does not support {#what-pdfmonkey-does-not-support}

PDFMonkey does not support importing existing PDF, Word, or other file formats. Templates must be built from scratch, either using the visual Builder or by writing HTML, CSS, and Liquid in Code Templates.


## FAQ

**What is the difference between Builder and Code Templates in PDFMonkey?**

The Builder is a visual drag-and-drop editor that uses Vue under the hood. Code Templates are written in HTML, CSS, and Liquid. Both produce identical high-quality PDFs. The Builder is easier for non-developers; Code Templates offer more layout control and advanced logic.

**Can I convert a PDFMonkey Builder template to a Code Template?**

No. Builder templates and Code Templates are separate types and cannot be converted between each other. Choose your approach before you start designing.

**Does the PDFMonkey Builder use Liquid?**

No. Builder templates use Vue, not Liquid. Liquid syntax like {% if %}, {% for %}, and Liquid filters will not work in the Builder. Dynamic data is handled through Vue's template engine and the Logic panel.



---

# The Liquid Syntax

Source: https://pdfmonkey.io/docs/code-templates/the-liquid-syntax.md
Liquid is an open-source template language created by Shopify. It provides a clean and simple syntax you can use to write PDFMonkey templates and make them highly dynamic.

## How PDFMonkey uses Liquid

> [!NOTE]
> **Liquid v4**
>
> We&#39;re using Liquid v4 at the moment. This means than any method marked `5.0.0` or above in the official Liquid documentation will not be available in PDFMonkey.


When you write a Template using code, the HTML you write is actually using Liquid. This means that you can insert dynamic data, transform this data, condition the content of your template or loop over lists to repeat some content.

## A taste of Liquid

Here's a quick example that shows what a Liquid template looks like in PDFMonkey. It uses most of the key features you'll encounter:

```liquid
<h1>Invoice #{{invoiceNumber}}</h1>
<p>Date: {{"now" | date: "%B %d, %Y"}}</p>
<p>Client: {{client.fullName}}</p>

<table>
  <tr>
    <th>Product</th>
    <th>Qty</th>
    <th>Price</th>
  </tr>

  {% for item in lineItems %}
    <tr>
      <td>{{item.product}}</td>
      <td>{{item.quantity}}</td>
      <td>{{item.price | times: item.quantity | with_delimiter, precision: 2}}</td>
    </tr>
  {% endfor %}
</table>

{% if client.isNewClient %}
  <p>Welcome aboard! Enjoy 10% off your next order.</p>
{% endif %}
```

In this short snippet you can see the three building blocks you'll use everywhere:

- **Output tags** `{{ }}` — insert dynamic values into the HTML. They can access nested properties like `client.fullName`.
- **Logic tags** `{% %}` — control flow with conditions (`if`/`else`), loops (`for`), and more.
- **Filters** `|` — transform values inline. Here `date` formats the current date, `times` multiplies two numbers, and `with_delimiter` formats the result with commas and decimals.

Each of these is covered in depth in the pages below.

## Conditions and loops

Conditions (`if`, `unless`, `case`) and loops (`for`) let you control what appears in your output. You can show content only when certain criteria are met, or repeat a block for every item in a list.

- [Conditions and Loops](https://pdfmonkey.io/docs/code-templates/conditions-and-loops.md)

## Filters

Liquid filters let you transform data inside your templates. You pipe a value through one or more filters using the `|` character to format strings, manipulate numbers, work with arrays, and more.

Liquid provides many built-in filters (data transformation helpers) that will be enough in most cases. That said, authoring many templates ourselves, we've discovered the need for some additional ones that we added along the way.

PDFMonkey supports all standard Liquid filters plus a set of custom filters tailored to document generation:

- [Filters](https://pdfmonkey.io/docs/code-templates/filters.md) — the complete reference including built-in Liquid filters and PDFMonkey-specific filters like `barcode`, `entities`, `in_time_zone`, and more

## Tags and helpers

In the same spirit, we also extend the default set of features Liquid brings to the table to offer features that might only make sense within PDFMonkey.

- [Reusing Code](https://pdfmonkey.io/docs/code-templates/reusing-code.md) (Snippets and Partials)

> [!NOTE]
> **Complete Liquid documentation**
>
> This documentation covers the most useful Liquid features to know when writing Templates. For a complete documentation you can refer to the official one hosted at [https://shopify.github.io/liquid/](https://shopify.github.io/liquid/)



## FAQ

**What templating language does PDFMonkey use?**

PDFMonkey code templates use Liquid v4, an open-source template language created by Shopify. It provides output tags {{ }} for inserting values, logic tags {% %} for conditionals and loops, and filters for transforming data.

**Can I use Liquid v5 features in PDFMonkey?**

No. PDFMonkey runs Liquid v4. Any feature marked as 5.0.0 or above in the official Liquid documentation is not available in PDFMonkey templates.

**Does the PDFMonkey Builder use Liquid?**

No. Liquid is only used in Code Templates. Builder templates use Vue under the hood. If you want Liquid syntax like {% if %} or Liquid filters, use a Code Template instead.


---

# Using Dynamic Data

Source: https://pdfmonkey.io/docs/code-templates/defining-dynamic-data.md
When you generate a Document with PDFMonkey, you send data to use with the Template you selected. A Template's **test data** are fake data that look like the ones you would use when generating a Document. Their purpose is to help you build the Template and test different scenarios.

It's usually more efficient to play with test data than to build your Template and test it by generating actual Documents. You get a shorter feedback loop and don't consume your monthly quota.

As a convenience, your test data is copied as Document payload when generating a Document via the Dashboard. Aside from that, it is never used when generating Documents through the API.

> [!NOTE]
> **The preview is a real PDF**
>
> When building your Template, the preview you see on the right of the editor shows you a real PDF. This means that if it looks nice in the preview, it will look the same when generating a Document.


## Defining test data

Define your test data in the **Test data** tab of the Template editor. This serves two functions:

* It helps you define the structure you want to use for your data
* It provides test data you can play with when building your Template

Data in PDFMonkey, be it test data for a Template or the payload of a Document, is expressed using the **JSON syntax**.

We'll take the example of an e-commerce order. You could imagine something like this:

```json
{
  "orderId": 1234,
  "orderStatus": "pending",
  "invoiceId": null,
  "client": {
    "civility": "Mr",
    "fullName": "Peter Parker",
    "isNewClient": true
  },
  "lineItems": [
    { "product": "Super strong silk",     "quantity": 100, "price": 123.45 },
    { "product": "Electronic components", "quantity": 12,  "price": 12.34 }
  ]
}
```

Let's take a look at what we have.

We got some order-related data with `orderId` and `orderStatus`. They use different type of data, an `integer` and a `string`.

We then get an `invoiceId` that is `null` to indicate an empty value. Given our order is pending it does not have an invoice yet, legit.

Things start to get interesting when we get to `client` as it's a nested structure (usually referred to as "object") containing its own data. You'll notice a new type of data for `isNewClient` which is a boolean, a value that can be `true` or `false`.

And finally we get `lineItems` that is a list (usually referred to as an "array") of, surprise, line items  represented by object with properties for `product`, `quantity` and `price`.

> [!NOTE]
> **Do you need to nest your data?**
>
> You don&#39;t have to use a nested structure if you don&#39;t like or need it. Here the client details could be defined as `clientCivility`, `clientFullName` and `clientIsNewClient`


## Using your test data in the Template

Once you have defined your test data, you call it within your Template using Liquid.

Given the data we defined above, our HTML could start with something like this:

```liquid
<p>Order num. {{orderId}} is currently {{orderStatus}}.</p>
<p>Client: {{client.civility}} {{client.fullName}}.</p>
```

As you can see we can reference our data items directly and use a dot (`.`) to access nested elements. This code would generate the following HTML output:

```html
<p>Order num. 1234 is currently pending.</p>
<p>Client: Mr Peter Parker</p>
```

In the following guides, we'll learn how to display content according to some condition or how to go over our line items list and display it properly.

## Naming your variables

Your payload keys should never contain any dot or space and should never be only a number.

```json5 title="JSON"
{
  // Valid keys
  "someVariable": "Some value",            // {{someVariable}}
  "some_variable": "Some value",           // {{some_variable}}
  "some-variable": "Some value",           // {{some-variable}}
  "SomeVariable": "Some value",            // {{SomeVariable}}
  "somevariable": "Some value",            // {{somevariable}}
  "some": { "variable": "Some value" },    // {{some.variable}}
  "2words": "Hello world",                 // {{2words}}

  // Invalid keys
  "some.variable": "Some value",
  "some variable": "Some value",
  "(someVariable)": "Some value",
  "'someVariable'": "Some value",
  "{{someVariable}}": "Some value",
  "2": "Some value",
  "$someVariable": "Some value"
}
```

Here is how you would call the valid keys in a template:

```html title="HTML"
{{someVariable}}
{{some_variable}}
{{some-variable}}
{{SomeVariable}}
{{somevariable}}
{{some}}
{{2words}}
```

## Creating variables in templates

Variable tags create new Liquid variables. Here are the two most common tags, but you can learn more in [the official documentation](https://shopify.github.io/liquid/tags/variable/).

### assign

[Read the complete assign documentation.](https://shopify.github.io/liquid/tags/variable/#assign)

Creates a new named variable.

```liquid title="Input"
{% assign foo = "bar" %}
{{foo}}
```

``` title="Output"
bar
```

### capture

[Read the complete capture documentation.](https://shopify.github.io/liquid/tags/variable/#capture)

Captures the string inside of the opening and closing tags and assigns it to a variable. Variables created using `capture` are stored as strings.

```liquid title="Input"
{% assign favorite_food = "pizza" %}
{% assign age = 35 %}

{% capture about_me %}
I am {{age}} and my favorite food is {{favorite_food}}.
{% endcapture %}

{{about_me}}
```

``` title="Output"
I am 35 and my favourite food is pizza.
```


## FAQ

**How do I pass dynamic data to a PDFMonkey template?**

Define your data as a JSON object and send it as the document payload via the API or an integration. In the template, access values using Liquid syntax: {{ variableName }} for top-level keys, {{ object.property }} for nested values, and {% for item in array %} for arrays.

**What is test data in PDFMonkey?**

Test data is a JSON object defined in the Test Data tab of the template editor. It simulates the payload you would send via the API, letting you preview the template in real time without consuming your monthly document quota.

**Can I use nested JSON objects and arrays in PDFMonkey templates?**

Yes. PDFMonkey supports deeply nested JSON. Access nested values with dot notation (e.g., {{ client.fullName }}) and iterate over arrays with {% for item in lineItems %}. You can nest objects inside arrays and vice versa.


---

# Formatting and Transforming Data

Source: https://pdfmonkey.io/docs/code-templates/filters.md
Filters are data transformers that you apply to a value using the pipe (`|`) syntax. They take the value on the left, process it, and output the result. You can chain multiple filters together for more complex transformations.

You can find the complete list of built-in filters in [the official Liquid documentation](https://shopify.github.io/liquid/).

## Built-in filters

### append

[Read the complete append documentation.](https://shopify.github.io/liquid/filters/append)

Adds the specified string to the end of another string.

```liquid
{{"/my/fancy/url" | append: ".html"}}
→ /my/fancy/url.html
```

### date

[Read the complete date documentation.](https://shopify.github.io/liquid/filters/date)

Converts a timestamp into another date format. The format for this syntax is the same as [strftime](http://strftime.net/). The input uses the same format as Ruby's [Time.parse](https://ruby-doc.org/stdlib/libdoc/time/rdoc/Time.html#method-c-parse).

```liquid
{{article.published_at | date: "%a, %b %d, %y"}}
→ Fri, Jul 17, 22

{{article.published_at | date: "%Y"}}
→ 2022
```

`date` works on strings if they contain well-formatted dates:

```liquid
{{"March 14, 2022" | date: "%b %d, %y"}}
→ Mar 14, 22
```

To get the current time, pass the special word `"now"` (or `"today"`) to `date`:

```liquid
Last update: {{"now" | date: "%Y-%m-%d %H:%M"}}
→ Last update: 2022-03-14 12:34
```

> [!NOTE]
> **Need a timezone?**
>
> Take a look at the [`in_time_zone`](#in_time_zone) filter provided by PDFMonkey.


### default

[Read the complete default documentation.](https://shopify.github.io/liquid/filters/default)

Sets a default value for any variable with no assigned value. `default` will show its value if the input is `nil`, `false`, or empty.

When `product_price` is **not defined**, the default value is used:

```liquid
{{product_price | default: 2.99}}
→ 2.99
```

When `product_price` **is defined**, the default value is not used:

```liquid
{% assign product_price = 4.99 %}
{{product_price | default: 2.99}}
→ 4.99
```

When `product_price` **is empty**, the default value is used:

```liquid
{% assign product_price = "" %}
{{product_price | default: 2.99}}
→ 2.99
```

> [!TIP]
> **Math filters**
>
> — `plus`, `minus`, `times`, `divided_by`, `round`, `ceil`, and `floor` are covered in the dedicated [How to do Maths](https://pdfmonkey.io/docs/code-templates/how-to-do-maths.md) page.


### newline\_to\_br

[Read the complete newline\_to\_br documentation.](https://shopify.github.io/liquid/filters/newline_to_br/)

Inserts an HTML line break (`<br />`) in front of each newline () in a string.

```liquid
{{"Hello\nWorld" | newline_to_br}}
→ Hello<br />
  World
```

### where

[Read the complete where documentation.](https://shopify.github.io/liquid/filters/where/)

Creates an array including only the objects with a given property value, or any [truthy](https://shopify.github.io/liquid/basics/truthy-and-falsy/#truthy) value by default.

In this example, assume you have a list of products and you want to show your kitchen products separately. Using `where`, you can create an array containing only the products that have a `"type"` of `"kitchen"`.

```liquid
All products:
{% for product in products %}
- {{ product.title }}
{% endfor %}

{% assign kitchen_products = products | where: "type", "kitchen" %}

Kitchen products:
{% for product in kitchen_products %}
- {{ product.title }}
{% endfor %}
```

``` title="Result"
All products:
- Vacuum
- Spatula
- Television
- Garlic press

Kitchen products:
- Spatula
- Garlic press
```

## PDFMonkey filters

> [!NOTE]
> These filters are exclusive to PDFMonkey and are not available in standard Liquid implementations.


### Array filters

#### push

Adds an item to an array.

```liquid
{% assign arr = "earth wind" | split: " " %}
{% assign arr = arr | push: "fire" %}

{{arr | to_sentence}}
→ earth, wind and fire
```

#### slice\_by

Slices an array in groups of N elements.

```liquid
{% assign reindeers = "Dasher Dancer Prancer Vixen Comet Cupid Donner Blitzen Rudolph" | split: " " %}
{% assign reindeerPairs = reindeers | slice_by: 2 %}

{% for reindeerPair in reindeerPairs %}
  Pair:
  {% for reindeer in reindeerPair %}
    - {{reindeer}}
  {% endfor %}
{% endfor %}
```

``` title="Result"
  Pair:
    - Dasher
    - Dancer
  Pair:
    - Prancer
    - Vixen
  Pair:
    - Comet
    - Cupid
  Pair:
    - Donner
    - Blitzen
  Pair:
    - Rudolph
```

#### sum

Returns the sum of a numbers array.

Let's say you have this in your data:

```json title="JSON"
{
  "array": [1, 2, 3, 4, 5]
}
```

```liquid
{{array | sum}}
→ 15
```

#### to\_sentence

Converts the array to a comma-separated sentence where the last element is joined by the connector word.

```liquid
{% assign arr = "earth wind" | split: " " %}
{% assign arr = arr | push: "fire" %}

{{arr | to_sentence}}
→ earth, wind and fire

{{arr | to_sentence: ' - '}}
→ earth - wind and fire

{{arr | to_sentence: ' - ', 'and finally '}}
→ earth - wind and finally fire
```

#### where\_exp

Similar to Liquid's [`where`](#where) but accepts an expression.

Let's start with the data:

```json title="JSON"
{
  "products": [
    { "name": "Product 1", "price": 1.00 },
    { "name": "Product 2", "price": 2.00 },
    { "name": "Product 3", "price": 3.00 },
    { "name": "Product 4", "price": 2.00 },
    { "name": "Product 5", "price": 1.00 }
  ]
}
```

```liquid
{% assign cheapProducts = products | where_exp: "prod", "prod.price < 1" %}

{% for product in cheapProducts %}
- {{product.name}}
{% endfor %}
```

``` title="Result"
- Product 1
- Product 5
```

### Date and time filters

#### in\_time\_zone

Shifts a date to the given timezone before formatting.

```liquid
{{"2050-01-02 12:34:56" | in_time_zone: "Pacific/Galapagos" | date: "%Y-%m-%d %H:%M"}}
→ 2050-01-02 06:34
```

### URL filters

#### ensure\_protocol

You might get asset URLs that don't include any protocol. Sadly our rendering engine doesn't support this type of URL. For this reason we provide `ensure_protocol` that will add a protocol as needed:

```liquid
{{"//example.com/some-picture.jpg" | ensure_protocol}}
→ https://example.com/some-picture.jpg

{{"//example.com/some-picture.jpg" | ensure_protocol: "http"}}
→ http://example.com/some-picture.jpg

{{"http://example.com/some-picture.jpg" | ensure_protocol}}
→ http://example.com/some-picture.jpg
```

### Number filters

See also [How to do Maths](https://pdfmonkey.io/docs/code-templates/how-to-do-maths.md) for arithmetic filters and practical calculation patterns.

#### format

The `format` filter is useful for advanced number formatting. For simpler formatting, prefer [`with_delimiter`](#with_delimiter).

```liquid
{{5 | format: "%05d"}}
→ 00005

{{5 | format: "%08.3f"}}
→ 0005.000

{{5 | format: "%.2f"}}
→ 5.00

{{5.1234 | format: "%.2f"}}
→ 5.12
```

#### with\_delimiter

For basic number formatting like money for instance, the `with_delimiter` filter will help you set a thousand delimiter, a decimal separator and the precision.

**Basic usage** — adds a comma every three digits by default:

```liquid
{{12345678 | with_delimiter}}
→ 12,345,678

{{1234.567 | with_delimiter}}
→ 1,234.567
```

Non-numeric text is left untouched:

```liquid
{{'12345a' | with_delimiter}}
→ 12345a
```

**Custom delimiter** — change the thousands separator:

```liquid
{{12345678 | with_delimiter, delimiter: " "}}
→ 12 345 678
```

**Precision** — control decimal places:

```liquid
{{12345678 | with_delimiter, precision: 2}}
→ 12,345,678.00

{{1234.567 | with_delimiter, precision: 2}}
→ 1,234.57
```

**Stripping trailing zeros:**

```liquid
{{12345678 | with_delimiter, precision: 2, strip_insignificant_zeros: true}}
→ 12,345,678

{{1234.567 | with_delimiter, precision: 2, strip_insignificant_zeros: true}}
→ 1,234.57
```

**Combining options** — for example, European-style formatting:

```liquid
{{1234.567 | with_delimiter,
  delimiter: " ",
  separator: ",",
  precision: 2,
  strip_insignificant_zeros: true
}}
→ 1 234,57

{{1234.003 | with_delimiter,
  delimiter: " ",
  separator: ",",
  precision: 2,
  strip_insignificant_zeros: true
}}
→ 1 234
```

### HTML filters

#### entities

This filter can be very useful if you have to deal with accented or special characters inside the [header or footer](https://pdfmonkey.io/docs/code-templates/header-and-footer.md). It will convert any non-latin character to its [HTML entity](https://dev.w3.org/html5/html-author/charref).

```liquid
{{"Marie Skłodowska Curie" | entities}}
→ Marie Sk&lstrok;odowska Curie
```

### JSON filters

#### json

If you need to insert [dynamic data](https://pdfmonkey.io/docs/code-templates/defining-dynamic-data.md) in its original JSON format (like we do [for charts](https://pdfmonkey.io/docs/code-templates/custom-javascript.md#including-charts) for instance) the `json` filter is what you need. Notice it's returning a string, not the object itself.

```liquid
{{'banana, apple' | split: ', ' | json}}
→ ["banana", "apple"]
```

#### parse\_json

Parses a JSON string into a usable object or array. This is especially handy when an integration (such as [Glide](https://pdfmonkey.io/docs/integrations/glide.md) or a webhook) can only send flat string values — you can pass structured data as a JSON string and parse it in the template.

```liquid
{% assign obj = '{ "key": "value" }' | parse_json %}
{{obj.key}}
→ value
```

You can also parse arrays and loop over them:

```liquid
{% assign items = '[{"name":"Waffle","qty":12},{"name":"Donut","qty":5}]' | parse_json %}
{% for item in items %}
  {{item.name}} x{{item.qty}}
{% endfor %}
→ Waffle x12
  Donut x5
```

If the input is empty or not valid JSON, `parse_json` returns `nil` by default. You can pass a fallback value as an argument:

```liquid
{% assign data = invalidVariable | parse_json: "fallback" %}
{{data}}
→ fallback
```

> [!TIP]
> **Typical use case**
>
> Some integrations only support flat key/value pairs and cannot send arrays. Build a JSON string on the integration side (e.g., a Joined List in Glide) and parse it in your template with `parse_json` to get a proper array you can loop over. See the [Glide line items workaround](https://pdfmonkey.io/docs/integrations/glide.md#workaround-json-string) for a complete example.



## FAQ

**How do I format numbers with thousand separators in PDFMonkey?**

Use the with_delimiter filter. For example, {{ 12345678 | with_delimiter }} outputs 12,345,678. You can customize the delimiter, decimal separator, and precision with named arguments.

**How do I format dates in a PDFMonkey Liquid template?**

Use the date filter with strftime format codes. For example, {{ article.published_at | date: "%b %d, %Y" }}. To convert to a specific timezone first, chain the in_time_zone filter before date.

**How do I parse a JSON string inside a PDFMonkey template?**

Use the parse_json filter to convert a JSON string into an object or array you can loop over. For example: {% assign items = jsonString | parse_json %}. This is especially useful when integrations like Glide can only send flat string values.

**How do I handle accented characters in PDFMonkey headers and footers?**

Use the entities filter to convert non-Latin characters to HTML entities. For example, {{ company.name | entities }} converts “é” to &eacute;, which renders correctly in settings-based headers and footers.


---

# How to do Maths

Source: https://pdfmonkey.io/docs/code-templates/how-to-do-maths.md
Liquid has no math operators like `+`, `-`, `*`, or `/`. Instead, all arithmetic is done through **filters** — you pipe a value through a filter to transform it. This page teaches common calculation patterns you'll need when building templates.

## Basic arithmetic

The four core arithmetic filters are `plus`, `minus`, `times`, and `divided_by`. Each takes a value on the left and a parameter on the right:

```liquid
{{ 10 | plus: 5 }}        -> 15
{{ 10 | minus: 3 }}       -> 7
{{ 10 | times: 4 }}       -> 40
{{ 10 | divided_by: 3 }}  -> 3
```

### Practical examples

Calculating a line item total from your data:

```liquid
{{ item.quantity | times: item.unit_price }}
```

Applying a 10% discount:

```liquid
{% assign discounted = subtotal | times: 0.9 %}
{{ discounted }}
```

Adding 20% VAT to a subtotal:

```liquid
{{ subtotal | times: 1.20 }}
```

## Rounding

Three filters control decimal precision:

```liquid
{{ 4.6 | round }}     -> 5
{{ 4.3 | round }}     -> 4
{{ 4.123 | round: 2 }} -> 4.12

{{ 4.1 | ceil }}      -> 5
{{ 4.1 | floor }}     -> 4
```

> [!WARNING]
> **Integer division truncates**
>
> When `divided_by` receives an integer divisor, it returns a truncated integer — not a rounded result:
&gt; 
&gt; ```liquid
&gt; {{ 5 | divided_by: 3 }}    -&gt; 1  (not 1.67)
&gt; {{ 5 | divided_by: 3.0 }}  -&gt; 1.6666666666666667
&gt; ```
&gt; 
&gt; Use a decimal divisor (like `3.0`) if you need a precise result.


## Chaining calculations

Filters can be chained left to right. Each filter receives the output of the previous one:

```liquid
{{ price | times: quantity | times: 1.20 | round: 2 }}
```

This multiplies `price` by `quantity`, applies 20% VAT, and rounds to 2 decimal places — all in a single expression.

A complete invoice line example:

```liquid
{% for item in lineItems %}
  <tr>
    <td>{{ item.product }}</td>
    <td>{{ item.quantity }}</td>
    <td>${{ item.price | with_delimiter, precision: 2 }}</td>
    <td>${{ item.price | times: item.quantity | with_delimiter, precision: 2 }}</td>
  </tr>
{% endfor %}
```

## Formatting numbers

Liquid arithmetic filters return raw numbers. To display them nicely (thousand separators, fixed decimals, sprintf patterns), use the [`with_delimiter`](https://pdfmonkey.io/docs/code-templates/filters.md#with_delimiter) and [`format`](https://pdfmonkey.io/docs/code-templates/filters.md#format) filters.

## Further reading

- [Filters](https://pdfmonkey.io/docs/code-templates/filters.md) — complete reference for all built-in and PDFMonkey-specific filters


## FAQ

**How do I do math in Liquid templates?**

Liquid has no math operators. Use filters instead: plus, minus, times, and divided_by. For example, {{ 10 | plus: 5 }} returns 15.

**Why does divided_by return a wrong result in Liquid?**

When the divisor is an integer, divided_by truncates the result to an integer. Use a decimal divisor (e.g., 3.0 instead of 3) to get a precise floating-point result.

**How do I round numbers in a PDFMonkey template?**

Use the round filter for standard rounding ({{ 4.6 | round }} returns 5), ceil to round up, or floor to round down. Pass a precision argument to control decimal places: {{ 4.123 | round: 2 }} returns 4.12.


---

# Conditions and Loops for Code Templates

Source: https://pdfmonkey.io/docs/code-templates/conditions-and-loops.md
More often than not, you'll need to display certain portions of content depending on the value of one or more data item, or repeat content for each entry in a list. Let's see how this can be done using Liquid.

## Using a simple "if"

The simplest condition you can use is an `if` statement:

```liquid
{% if client.isNewClient == true %}
  <p>Congrats on your first order!</p>
{% endif %}
```

The content will be displayed only when the condition is true.

### Combining conditions

You can also combine several conditions using `and` and `or`

```liquid
{% if client.isExistingClient == true and client.orderedRecently == true %}
  <p>A fan of our brand, are we? :D</p>
{% endif %}

{% if client.isNewClient == true or client.orderedALongTimeAgo == true %}
  <p>Congrats on your first order this year!</p>
{% endif %}
```

## Inverse condition with "unless"

If you want to inverse the condition `unless` is your friend:

```liquid
{% unless client.isNewClient %}
  <p>Nice to see you again!</p>
{% endunless %}
```

In this case, the code would be equivalent to

```liquid
{% if client.isNewClient != true %}
  <p>Nice to see you again!</p>
{% endif %}
```

## Doing both with "if ... else"

A bit more frequent than `unless` the `if ... else` statement allows specifying both cases:

```liquid
{% if client.isNewClient == true %}
  <p>Congrats on your first order!</p>
{% else %}
  <p>Nice to see you again!</p>
{% endif %}
```

## Multiple conditions with "if ... elsif ... else"

There might be cases where you need to check for multiple conditions to find the right content. For these cases the `if ... elsif ... else` statement is the solution:

```liquid
{% if client.isNewClient == true %}
  <p>Congrats on your first order!</p>
{% elsif client.fullName == "Peter Parker" %}
  <p>Welcome back Spide… hum… Mr Parker.</p>
{% else %}
  <p>Nice to see you again {{client.fullName}}!</p>
{% endif %}
```

## Dispatch according to a single variable

If you want to insert content according to the value of a single variable, you can trade the `if ... elsif ... else` statement with a simple `case ... when ... end` statement:

```liquid
{% case client.fullName %}
  {% when "Peter Parker" %}
    <p>Welcome back Spide… hum… Mr Parker.</p>
  {% when "Dianna Price" %}
    <p>Nice to see you again WonderW… I mean… Miss Price.</p>
  {% else %}
    <p>Hello again {{client.fullName}}!</p>
{% endcase %}
```

## Loops

Looping over lists is a very frequent need. Here are the essential aspects of iteration, but you can learn more in [the official documentation](https://shopify.github.io/liquid/tags/iteration/).

### for

Let's use the data we defined in [an earlier section](https://pdfmonkey.io/docs/code-templates/defining-dynamic-data.md#defining-test-data):

```json
{
  "orderId": 1234,
  "orderStatus": "pending",
  "invoiceId": null,
  "client": {
    "civility": "Mr",
    "fullName": "Peter Parker",
    "isNewClient": true
  },
  "lineItems": [
    { "product": "Super strong silk",     "quantity": 100, "price": 123.45 },
    { "product": "Electronic components", "quantity": 12,  "price": 12.34 }
  ]
}
```

We can loop over the `lineItems` array to list our products using a `for` loop. It will repeat the code for each item in the array:

```liquid
<table>
  <tr>
    <th>Product</th>
    <th>Quantity</th>
    <th>Unit Price</th>
    <th>Total</th>
  </tr>

  {% for item in lineItems %}
    <tr>
      <td>{{item.product}}</td>
      <td>{{item.quantity}}</td>
      <td>${{item.price | with_delimiter, precision: 2}}</td>
      <td>${{item.price | times: item.quantity | with_delimiter, precision: 2}}</td>
    </tr>
  {% endfor %}
</table>
```

The resulting HTML will look like this:

```html
<table>
  <tr>
    <th>Product</th>
    <th>Quantity</th>
    <th>Unit Price</th>
    <th>Total</th>
  </tr>

  <tr>
    <td>Super strong silk<td>
    <td>100</td>
    <td>$123.45</td>
    <td>$12,345.00</td>
  </tr>

  <tr>
    <td>Electronic components</td>
    <td>12</td>
    <td>$12.34</td>
    <td>$148.08</td>
  </tr>
</table>
```

> [!NOTE]
> **Data formatting**
>
> We&#39;re formatting the monetary values using the `with_delimiter` filter here. You can learn more in our documentation about [Filters](https://pdfmonkey.io/docs/code-templates/filters.md).


### The forloop object

Inside a `for` loop, you get access to a special object that stores the current state of the loop. It can be useful to build special cases for the first or last iteration, for instance.

```liquid
{% for item in lineItems %}
  {% if forloop.first == true %}
    <p>{{item.product}} is the first item.</p>
  {% elsif forloop.last == true %}
    <p>{{item.product}} is the last item.</p>
  {% else %}
    <p>{{item.product}} is an item.</p>
  {% endif %}
{% endfor %}
```

> [!NOTE]
> **Learn more**
>
> Discover the complete range of possibilities of `forloop` in [the dedicated documentation](https://shopify.dev/api/liquid/objects/for-loops), including things like `index`, `index0` or `length`.


### Limiting and offsetting

You can control how many items a loop iterates over using `limit` and `offset`:

```liquid
{% for item in lineItems limit: 1 %}
  <p>First item: {{item.product}}</p>
{% endfor %}

{% for item in lineItems offset: 1 %}
  <p>Remaining items: {{item.product}}</p>
{% endfor %}
```

You can also iterate in reverse order:

```liquid
{% for item in lineItems reversed %}
  <p>{{item.product}}</p>
{% endfor %}
```

> [!NOTE]
> **Learn more**
>
> You can learn more about iterating over lists in [the official Liquid documentation](https://shopify.github.io/liquid/tags/iteration/), including all available loop parameters.


### Related filters

When working with loops, these PDFMonkey filters are particularly useful:

- The [slice_by](https://pdfmonkey.io/docs/code-templates/filters.md#slice_by) filter — split an array into groups of N elements
- The [where_exp](https://pdfmonkey.io/docs/code-templates/filters.md#where_exp) filter — filter an array using an expression


## FAQ

**How do I use conditions in PDFMonkey templates?**

Use Liquid conditional tags: {% if condition %}, {% elsif %}, {% else %}, and {% endif %} to show or hide content. You can also use {% unless %} for inverse conditions and {% case %} / {% when %} for multi-branch logic.

**How do I loop over data in PDFMonkey templates?**

Use the {% for item in list %} tag to repeat HTML for each entry in an array from your document payload. Inside the loop, access the forloop object for the current index, length, and first/last flags.

**Can I combine multiple conditions in PDFMonkey Liquid templates?**

Yes. Use 'and' to require all conditions to be true, or 'or' to require at least one. For example: {% if client.isNewClient == true and order.total > 100 %}.


---

# Images and Links for Code Templates

Source: https://pdfmonkey.io/docs/code-templates/images.md
Images and links are fundamental building blocks of most PDFMonkey templates. This page walks you through each way to include visual assets and clickable links in your PDFs.

## Including Images

There are three ways to include images in your templates. Here is a quick comparison to help you pick the right one:

| Method | Works on Free plan | Needs external hosting | Best for |
| --- | --- | --- | --- |
| [URL-based images](#url-based-images) | No (paid only) | Yes | Most use cases: product photos, dynamic content |
| [Embedded images](#embedded-images) | Yes | No | Small static assets like logos or signatures |
| [Inline SVG](#inline-svg) | Yes | No | Icons, simple graphics |

### URL-Based Images

The most common approach is to reference images by URL. If your images are hosted somewhere (a CDN, your own server, a cloud storage bucket), just point to them.

> [!WARNING]
> **Paid account only**
>
> Including images by URL is only available on paid accounts. Documents that reference external images will fail on a free account. See [External Resources](https://pdfmonkey.io/docs/getting-started/external-resources.md) for details. If you are on a free plan, see [Embedded images](#embedded-images) below.


**Static image.** Hard-code the URL in your template:

```html title="HTML"
<img src="https://placekitten.com/200/300" />
```

**Dynamic image.** Pass the URL in your payload and reference it in the template.

Payload:

```json
{
  "imageUrl": "http://placekitten.com/200/300"
}
```

Template:

```html title="HTML"
<img src="{{imageUrl}}" />
```

**Background image.** Define a background image in the CSS tab:

```css title="CSS"
.some-class {
  background-image: url("https://placekitten.com/200/300");
}
```

Then apply it to any element in your HTML tab:

```html title="HTML"
<div class="some-class">
  ...
</div>
```

**Dynamic background image.** You cannot use dynamic data from the CSS tab the way you do in the HTML tab. But you have two options.

You can use inline styling:

```html title="HTML"
<div style="background-image: url('{{imageUrl}}');">
  ...
</div>
```

Or you can use an inlined `<style>` block in your HTML tab:

```html title="HTML"
<style>
  .some-class {
    background-image: url('{{imageUrl}}');
  }
</style>

<div class="some-class">
  ...
</div>
```

You could also use [the CSS custom properties technique](https://pdfmonkey.io/docs/code-templates/custom-css.md#the-css-custom-properties-technique) if you want to keep all your CSS in the CSS tab.

### Embedded Images

If you don't have images hosted online, or if you are on a free plan, you can embed image data directly in your template or API payload. The image is self-contained, so nothing is fetched from the internet at generation time.

**How it works:** you provide the image as a text string that contains the full image data (technically called a "data URI"). It looks like a long `data:image/png;base64,R0lGODlhE...` string. You don't need to understand the format, just produce the string and use it as the image source.

> [!NOTE]
> **How to get an embedded image string**
>
> Search for &#34;image to data-URI converter&#34; online. You&#39;ll find free tools that let you upload an image and get the string back, ready to paste.


**Static image.** For an image that never changes (a company logo, a decorative element), paste it directly in your template:

```html title="HTML"
<img src="data:image/png;base64,R0lGODlhE...UjIQA7" />
```

**Dynamic image.** If the image comes from your application (a user photo, a signature), send it in your payload and reference it in the template.

Payload:

```json
{
  "imageUrl": "data:image/png;base64,R0lGODlhE...UjIQA7"
}
```

Template:

```html
<img src="{{imageUrl}}" />
```

> [!TIP]
> **Keep embedded images small**
>
> Since the image data lives inside your template or payload, large images can make things unwieldy. Embedded images work best for small assets like logos or signatures. For larger or frequently changing images, [URL-based images](#url-based-images) are a better fit.


### Inline SVG

For icons, simple shapes, or graphics you control at the code level, you can insert SVG markup directly in your HTML:

```html title="HTML"
<svg height="100" width="100">
  <circle cx="50" cy="50" r="40" stroke="purple" stroke-width="3" fill="pink" />
</svg>
```

Because inline SVG is part of the template itself, it works on every plan and loads instantly.

## Performance Tips

If you are concerned about generation speed, using smaller images is the single most impactful improvement. Smaller images load faster, which means faster document generation.

Favor modern formats that produce lightweight files. PDFMonkey supports [WebP](https://developers.google.com/speed/webp) and [AVIF](https://en.wikipedia.org/wiki/AVIF). Free online converters can help you shrink images without visible quality loss.

Embedded images and inline SVG skip network requests entirely, which also helps. But even for those, optimizing the image data is beneficial.

If you prefer classic formats like JPEG or PNG, use a tool like [ImageOptim](https://imageoptim.com/) to reduce file sizes.

> [!NOTE]
> **Looking for file size optimization?**
>
> If your generated documents are larger than expected, see [Image Resolution and File Weight](https://pdfmonkey.io/docs/code-templates/image-weight-and-resolution.md) for a detailed guide on why images inflate PDF size and how to fix it.


## Using Links in PDFs

You can use both internal and external links in your documents.

### Internal Links

If you want to link to specific sections of your PDF, it works just like in a regular web page. Start by defining an anchor you want to link to:

```html
<div id="some-section">
  <!-- your content goes here -->
</div>
```

Then link to it from elsewhere in the content:

```html
<a href="#some-section">Go to Some Section</a>
```

### External Links

You can link to any web page on the internet by defining a link:

```html
<a href="https://www.pdfmonkey.io">Visit our website</a>
```

> [!NOTE]
> **You don&#39;t need target=&#34;_blank&#34;**
>
> Since your link is rendered in a PDF, adding `target=&#34;_blank&#34;` is not necessary. It works when viewing the PDF in a web-based viewer (like our preview) but is ignored in most contexts.



## FAQ

**How do I add images to a PDFMonkey template?**

Three ways: URL-based images (reference images hosted on a CDN or server — paid plans only), embedded images as Base64 data URIs (works on all plans, best for small assets like logos), and inline SVG for icons and simple graphics.

**Can I use images on the PDFMonkey free plan?**

Yes, but only embedded Base64 images or inline SVG. URL-based images require a paid plan because they rely on external resources. See the External Resources page for details.

**How do I add a dynamic image from my API payload in PDFMonkey?**

Pass the image URL in your JSON payload (e.g., {"imageUrl": "https://example.com/photo.jpg"}) and reference it in your template with an img tag: <img src="{{imageUrl}}" />.


---

# Image Resolution and File Weight

Source: https://pdfmonkey.io/docs/code-templates/image-weight-and-resolution.md
If your generated documents are larger than you expected, images are almost certainly the cause. This page explains how images end up in your files, why they inflate file size, and what you can do about it.

## How images end up in your document

PDFMonkey uses a Chromium-based engine to generate documents. The process works like this:

1. Your HTML and CSS are loaded into the browser engine.
2. The engine **renders** the page: it downloads images, applies styles, and paints every pixel.
3. Only then does it generate the PDF from the rendered result.

This matters because the PDF is not a simple package of your original files. The engine re-encodes every image as part of the rendering process. The original file format (JPEG, WebP, PNG) is discarded; what goes into the PDF is the rendered pixel data.

## Why images inflate file size

Two things happen during rendering that can dramatically increase file size.

### All source pixels are stored

If your source image is 3000 x 3000 pixels but you display it at 500 x 500 CSS pixels, the engine still embeds all 9 million source pixels in the PDF. The display size in your template has no effect on what gets stored.

This catches people off guard because on the web, the browser decodes the image into memory but never serializes it into a file. In a PDF, the full pixel data is written into the output.

> [!NOTE]
> **Pixel growth is quadratic**
>
> Doubling the width and height of an image means 4x the number of pixels, not 2x. Going from 1000 x 1000 to 3000 x 3000 is 9x more pixels.


### JPEG compression is lost

This is the biggest contributor to unexpected file bloat.

> [!WARNING]
> **JPEG compression does not carry through to the PDF**
>
> Chromium&#39;s PDF engine uses lossless compression (similar to PNG) for all raster images. It does **not** use JPEG compression. When you include a JPEG image, the engine decodes it to raw pixels first, then re-compresses those pixels losslessly. A 100 KB web JPEG can become several megabytes in the final PDF.


This affects every raster image format equally: JPEG, PNG, WebP, and AVIF all get decoded to pixels and re-encoded the same way. The source format has almost no impact on the final PDF size. What matters is the **number of pixels**.

## Sizing images for print quality

When your document will be printed, you want images sharp enough to look good on paper. The key concept is **PPI** (pixels per inch): how many pixels of image data correspond to one inch of printed output.

Our rendering engine operates at 72 DPI, while CSS uses 96 pixels per inch as its reference. To calculate the effective PPI of an image in your document:

> **Effective PPI = (image pixel width x 72) / (CSS display width x 0.75)**

In practice, a simpler way to think about it: multiply your CSS display size by the factor in this table to get the source image size you need.

| Print quality | Target PPI | Source image size | Example |
| --- | --- | --- | --- |
| Screen or digital viewing only | 96 | 1x CSS size | 400 CSS px → 400 px source |
| Good print quality | 150 | 1.5x CSS size | 400 CSS px → 600 px source |
| High print quality | 200 | 2x CSS size | 400 CSS px → 800 px source |
| Maximum (rarely needed) | 300 | 3x CSS size | 400 CSS px → 1200 px source |

For most printed documents (invoices, reports, certificates), **150 PPI is plenty**. Going above 200 PPI yields diminishing returns that most people cannot see, while significantly increasing file size.

> [!TIP]
> If your document is only viewed on screen (email attachments opened in a PDF viewer, for instance), 96 PPI (1x CSS size) is sufficient. There is no benefit to including extra pixels that will never be printed.


## What inflates file size (and what to do)

| Factor | Impact | What to do |
| --- | --- | --- |
| Oversized source images | All pixels are stored in the PDF, even those not displayed | Resize to 1.5-2x the CSS display size |
| Large image dimensions | 2x width = 4x file weight (quadratic growth) | Keep images as small as practical for your quality needs |
| Many images per document | Cumulative effect on total size | Compress and resize each image before uploading |
| CSS filters and blend modes | May force additional rasterization overhead | Avoid `filter`, `mix-blend-mode`, and complex `clip-path` on large images |
| Multiple copies of the same image | Deduplicated automatically by the rendering engine | No action needed |

### CSS for constraining image display size

Use `max-width` and `max-height` to control how images display in your template. Remember that this only changes the **display** size; you still need appropriately sized source images.

```css title="CSS"
.product-image {
  max-width: 400px;
  height: auto;
}
```

```html title="HTML"
<!-- Source image should be ~600-800px wide for good print quality -->
<img class="product-image" src="{{product.imageUrl}}" />
```

## Practical checklist

> [!TIP]
> **Before you generate**
>
> 1. **Resize source images** to 1.5-2x their CSS display size. No more.
&gt; 2. **Check image dimensions** before uploading. A 4000 x 3000 photo displayed at 300 x 225 CSS pixels wastes over 95% of its pixel data.
&gt; 3. **Use SVG for icons, logos, and simple graphics.** SVG stays vector in the PDF and adds almost no file weight.
&gt; 4. **Avoid CSS filters on large images.** `filter: blur()`, `filter: drop-shadow()`, and similar effects can force extra rasterization.
&gt; 5. **Test with realistic data.** Generate a document with the actual images you plan to use, not placeholders, to catch size issues early.


## Frequently asked questions

**What resolution should I use for my images?**

For documents that will be printed, 150 PPI is a solid default. That means your source image should be about 1.5x the CSS display size. For screen-only viewing, 1x (96 PPI) is fine.

**My document is 20 MB. How do I reduce it?**

Check the pixel dimensions of your source images. This is almost always the cause. Resize them to 1.5-2x their display size in the template. A 4000 px wide photo displayed at 500 CSS px is storing 64x more pixel data than you need at 1x.

**Does image format matter (PNG vs JPEG vs WebP)?**

The source format has very little impact on PDF file size because the rendering engine re-encodes everything using lossless compression. A 100 KB JPEG and a 500 KB PNG of the same image will produce nearly identical PDF sizes. Focus on **pixel dimensions**, not file format.

**Will SVG images make my document smaller?**

Yes. SVGs remain vector data in the PDF and take up very little space regardless of display size. Use them for anything that does not need to be a photograph: icons, logos, charts, decorative elements.

**Does using the same image multiple times increase file size?**

No. The rendering engine deduplicates identical image sources. If you reference the same URL or data URI ten times, only one copy is stored. However, different crops or CSS transforms of the same source may not be deduplicated.

**Do CSS `background-image` images behave the same way?**

Yes. Background images follow the same rules as `<img>` elements. The source pixels are embedded in full, and the same sizing recommendations apply.

## Related pages

- [Images and Links](https://pdfmonkey.io/docs/code-templates/images.md): how to include images in your templates (URL-based, embedded, inline SVG)
- [Page Layout](https://pdfmonkey.io/docs/code-templates/page-layout.md): page sizes, margins, and full-page backgrounds
- [Generate Images Instead of PDFs](https://pdfmonkey.io/docs/generating-documents/output-format.md): produce WebP, PNG, or JPG output
- [Our Engines](https://pdfmonkey.io/docs/code-templates/our-engines.md): rendering engine versions and capabilities


## FAQ

**Why is my PDFMonkey PDF file so large?**

Oversized source images are almost always the cause. The rendering engine embeds all source pixels in the PDF regardless of display size. Resize images to 1.5–2× their CSS display size to dramatically reduce file weight.

**What image resolution should I use for PDFMonkey PDFs?**

For printed documents, 150 PPI (about 1.5× the CSS display size) is a solid default. For screen-only viewing, 96 PPI (1× CSS size) is sufficient. Going above 200 PPI yields diminishing returns while significantly increasing file size.

**Does JPEG vs PNG format matter for PDF file size in PDFMonkey?**

No. The source format has very little impact because PDFMonkey’s rendering engine re-encodes all raster images using lossless compression. A 100 KB JPEG and a 500 KB PNG of the same image produce nearly identical PDF sizes. Focus on pixel dimensions instead.


---

# Page Layout

Source: https://pdfmonkey.io/docs/code-templates/page-layout.md
This page covers how to control the structure and layout of your PDF pages: sizing, margins, single-page containers, full-page backgrounds, and page breaks. For styling your content with CSS, see [Custom CSS](https://pdfmonkey.io/docs/code-templates/custom-css.md).

## Page Size and Margins {#default-page-sizes-in-pixels}

You can change the size of your Document's pages in the Template Settings tab. Select one of the predefined sizes, or set a custom one that precisely fits what you need.

Sizes are expressed in millimeters. If you need inches, 1 in = 25.4 mm.

### Default Page Sizes in Pixels

#### For Templates Using Engine v5

| Format        | Pixels         |
| ------------- | -------------- |
| A0            | 3178 x 4495    |
| A1            | 2245 x 3179    |
| A2            | 1588 x 2246    |
| A3            | 1123 x 1588    |
| **A4**        | **795 x 1123** |
| A5            | 560 x 795      |
| A6            | 397 x 560      |
| **US Letter** | **815 x 1056** |

#### For Templates Using Older Engines

| Format        | Pixels         |
| ------------- | -------------- |
| A0            | 3177 x 4492    |
| A1            | 2242 x 3177    |
| A2            | 1586 x 2242    |
| A3            | 1121 x 1586    |
| **A4**        | **793 x 1120** |
| A5            | 560 x 795      |
| A6            | 397 x 560      |
| **US Letter** | **815 x 1055** |

### Adding Margins

You can add margins at the top, left, right, and bottom of your Document in the Settings tab of the template.

**When to use margins:** If you are defining a header and/or footer in the settings, you will need to give them space by adding margin at the top and/or bottom. If you have a very simple document and want nice margins around it, that works too.

**When not to use margins:** If you need a full-page background color or image, margins will reduce the printed content size and prevent the color or image from going border to border. If you are making a presentation-style document and need each content page to fill an entire page using the pixel sizes listed above, do not use margins or it will mess things up.

## Single-Page Layout

If you want to make a container that always takes an entire page — no more, no less — you can define it like so:

```css title="CSS"
.page {
  /* Defining an A4 portrait page */
  height: 1120px;
  width: 793px;

  /* Will prevent any content like large images from messing */
  /* with printed content auto-scaling */
  overflow: hidden;

  /* Will allow any absolutely positioned content to be */
  /* placed relatively to the page by default */
  position: relative;
}
```

You can then use it in your HTML:

```html title="HTML"
<div class="page">
  Content for a single page
</div>
```

### Using a Full-Page Background

If you want to apply a background so it takes the entire page, use the technique above and set the background image on your page:

```css title="CSS"
.page-with-bg {
  background-image: url('some-background-url-or-datauri');
  background-size: cover;
}
```

```html title="HTML"
<div class="page page-with-bg">
  Content for a single page
</div>
```

## Page Breaks

### Forcing a Page Break

The simplest way to force a page break is using CSS. You can use the `page-break-before` property to define a class like this:

```css title="CSS"
.page-break {
  page-break-before: always;
}
```

You can then apply this class to any element you want to insert a page break before.

### Preventing a Page Break

If you want to avoid a section of your document from being broken between pages, you can use the `page-break-inside` CSS property:

```css title="CSS"
.avoid-page-break {
  page-break-inside: avoid;
}
```

If you apply this class to an element, it will have no effect for an element in the middle of the page, but if it risks being broken between two pages, a page break will be inserted before it.


## FAQ

**What is the A4 page size in pixels for PDFMonkey templates?**

On engine v5, an A4 page is 795×1123 pixels. On older engines (v2–v4), it is 793×1120 pixels. US Letter is 815×1056 (v5) or 815×1055 (older engines).

**How do I force a page break in a PDFMonkey PDF?**

Add a CSS class with page-break-before: always and apply it to any element where you want the break. For example: .page-break { page-break-before: always; }.

**How do I make a full-page background in a PDFMonkey template?**

Create a container sized to exactly one page (e.g., 793×1120px for A4), set overflow: hidden and position: relative, then apply a background-image with background-size: cover. Do not use page margins or they will shrink the content area.

**How do I prevent content from splitting across pages?**

Apply the CSS property page-break-inside: avoid to any element you want to keep on a single page. If the element would be split, a page break is inserted before it instead.


---

# Web Fonts

Source: https://pdfmonkey.io/docs/code-templates/web-fonts.md
Custom fonts let you match your brand identity and support non-Latin scripts in your PDFMonkey templates. This page covers importing fonts, using icon fonts, inlining fonts in headers and footers, handling special characters, and enabling emojis.

> [!WARNING]
> **Paid account only**
>
> Loading external fonts via URL (including Google Fonts) is only possible on a paid account. Documents that include external fonts will fail on a free account. See [External Resources](https://pdfmonkey.io/docs/getting-started/external-resources.md) for details.
&gt; 
&gt; As a workaround, free-plan users can embed fonts using data-URI. See the [header and footer font inlining tutorial](#fonts-in-headers-and-footers) for an example of this technique.


## Using Google Fonts

To import a font from Google Fonts, go to [https://fonts.google.com/](https://fonts.google.com/) and search for a font you like. Once found, you can select one or several variants (weight, italic, etc.) that you want to use.

In the right panel it will give you a `<link>` code that you can copy at the top of your HTML.

Let's import Roboto by selecting its regular and bold styles for instance:

```html title="HTML"
<!-- Importing Roboto, regular and bold -->
<link href="https://fonts.googleapis.com/css2?family=Roboto:wght@400;700&display=swap" rel="stylesheet">
```

Once you have added the font, you can use it in your CSS:

```css title="CSS"
body {
  font-family: 'Roboto';
}
```

## Other Font Services

Alternatively you can use any paid font-hosting service you're subscribed to or simply use self-hosted fonts.

For those cases, import the fonts using a `<link>` tag pointing to the CSS of the font. This CSS and the font files need to be publicly accessible otherwise they will not load in PDFMonkey.

## Icon Fonts

PDFMonkey does support icon fonts like [Font Awesome](https://fontawesome.com/) or [Material Icons](https://developers.google.com/fonts/docs/material\_icons#icon\_font\_for\_the\_web). Please refer to the documentation of the font you want to use to learn how to import it.

## Fonts in Headers and Footers

As stated in our [header and footer documentation](https://pdfmonkey.io/docs/code-templates/header-and-footer.md), headers and footers come with some caveats. Since the content of the CSS tab does not apply inside header and footer, fonts won't apply either.

That said, there's a rather technical solution you can use to bring your header and footer on par with the rest of the content.

### Step 1: Get the fonts CSS

Select the fonts you want on Google Fonts, then get the URL they provide and copy its content. Let's take the Dancing Script font and only select its Regular 400 variant. The URL we get is [https://fonts.googleapis.com/css2?family=Dancing+Script\&display=swap](https://fonts.googleapis.com/css2?family=Dancing+Script\&display=swap)

Upon visiting this URL the content we get is as follows:

```css
/* vietnamese */
@font-face {
  font-family: 'Dancing Script';
  font-style: normal;
  font-weight: 400;
  font-display: swap;
  src: url(https://fonts.gstatic.com/s/dancingscript/v22/If2cXTr6YS-zF4S-kcSWSVi_sxjsohD9F50Ruu7BMSo3Rep6hNX6plRPjLo.woff) format('woff');
  unicode-range: U+0102-0103, U+0110-0111, U+0128-0129, U+0168-0169, U+01A0-01A1, U+01AF-01B0, U+1EA0-1EF9, U+20AB;
}
/* latin-ext */
@font-face {
  font-family: 'Dancing Script';
  font-style: normal;
  font-weight: 400;
  font-display: swap;
  src: url(https://fonts.gstatic.com/s/dancingscript/v22/If2cXTr6YS-zF4S-kcSWSVi_sxjsohD9F50Ruu7BMSo3ROp6hNX6plRPjLo.woff) format('woff');
  unicode-range: U+0100-024F, U+0259, U+1E00-1EFF, U+2020, U+20A0-20AB, U+20AD-20CF, U+2113, U+2C60-2C7F, U+A720-A7FF;
}
/* latin */
@font-face {
  font-family: 'Dancing Script';
  font-style: normal;
  font-weight: 400;
  font-display: swap;
  src: url(https://fonts.gstatic.com/s/dancingscript/v22/If2cXTr6YS-zF4S-kcSWSVi_sxjsohD9F50Ruu7BMSo3Sup6hNX6plRP.woff) format('woff');
  unicode-range: U+0000-00FF, U+0131, U+0152-0153, U+02BB-02BC, U+02C6, U+02DA, U+02DC, U+2000-206F, U+2074, U+20AC, U+2122, U+2191, U+2193, U+2212, U+2215, U+FEFF, U+FFFD;
}
```

You can start by copying this content.

> [!NOTE]
> **Keep only what you need**
>
> Unless you care about Vietnamese or extended Latin characters, you can just keep the &#34;latin&#34; section. It will cover the basic alphabet plus most of the western European alphabets and accents.


### Step 2: Replace fonts URL with their data-URI content

Since fonts cannot be loaded from URL in the header and footer, you'll need to replace the Google Fonts URL with a data-URI version.

You can find very good online converters that will do that for you. Some of them simply take a URL as input and will give you the data-URI version in return.

You can now replace the URL with the data-URI text you got.

```css
/* latin */
@font-face {
  font-family: 'Dancing Script';
  font-style: normal;
  font-weight: 400;
  font-display: swap;
  src: url('data:font/woff;base64,d09GRgABAAAAAG6...') format('woff');
  unicode-range: U+0000-00FF, U+0131, U+0152-0153, U+02BB-02BC, U+02C6, U+02DA, U+02DC, U+2000-206F, U+2074, U+20AC, U+2122, U+2191, U+2193, U+2212, U+2215, U+FEFF, U+FFFD;
}
```

> [!NOTE]
> **Mind the quotes**
>
> Notice that when replacing the URL we also surrounded the content with quotes. Don&#39;t forget to do so.


### Step 3: Replace the data-URI scheme

As-is, the font will not work and the generation will fail. To make it work, we'll need to remove what is called the MIME type of the data-URI content. Simply remove anything between `data:` and `;base64`.

```css
/* latin */
@font-face {
  font-family: 'Dancing Script';
  font-style: normal;
  font-weight: 400;
  font-display: swap;
  src: url('data:;base64,d09GRgABAAAAAG6...') format('woff');
  unicode-range: U+0000-00FF, U+0131, U+0152-0153, U+02BB-02BC, U+02C6, U+02DA, U+02DC, U+2000-206F, U+2074, U+20AC, U+2122, U+2191, U+2193, U+2212, U+2215, U+FEFF, U+FFFD;
}
```

### Step 4: Give your header/footer some style

Now that we do have our font CSS working, you can add it to your template. Head to the Settings tab and enable the Advanced header/footer.

You can then paste your font CSS in a `<style>` tag:

```html title="Settings > Header"
<style>
  /* latin */
  @font-face {
    font-family: 'Dancing Script';
    font-style: normal;
    font-weight: 400;
    font-display: swap;
    src: url('data:;base64,d09GRgABAAAAAG6...') format('woff');
    unicode-range: U+0000-00FF, U+0131, U+0152-0153, U+02BB-02BC, U+02C6, U+02DA, U+02DC, U+2000-206F, U+2074, U+20AC, U+2122, U+2191, U+2193, U+2212, U+2215, U+FEFF, U+FFFD;
  }

  #header, #footer {
    font-family: 'Dancing Script';
  }
</style>

<div>This text should be using Dancing Script</div>
```

> [!NOTE]
> **Header and Footer styles are shared**
>
> You don&#39;t need to duplicate the font import in both header and footer as any style defined in one also applies to the other. That&#39;s why we can use the `#header, #footer` selector in the above example.


## Emojis

PDFMonkey can render emojis in generated PDFs. This feature is disabled by default and must be enabled per template.

To enable emoji rendering, open your template and go to the **Settings** tab. Toggle the emoji option on. Once enabled, any emoji characters in your template or dynamic data will render in the generated PDF.

## Special Characters and Non-Latin Text

The default PDFMonkey font is Open Sans. While it's a good enough looking font for most cases, it doesn't cover much when it comes to non-Latin characters.

If you need to display non-Latin characters in your documents, you will need the help of a [different web font](#using-google-fonts).

Here are some frequently requested character sets on Google Fonts:

- [Arabic](https://fonts.google.com/?subset=arabic)
- [Chinese (Hong Kong)](https://fonts.google.com/?subset=chinese-hongkong)
- [Chinese (Simplified)](https://fonts.google.com/?subset=chinese-simplified)
- [Chinese (Traditional)](https://fonts.google.com/?subset=chinese-traditional)
- [Cyrillic](https://fonts.google.com/?subset=cyrillic)
- [Cyrillic Extended](https://fonts.google.com/?subset=cyrillic-ext)
- [Hebrew](https://fonts.google.com/?subset=hebrew)
- [Japanese](https://fonts.google.com/?subset=japanese)

You can find more languages using the dedicated selection field on [Google Fonts](https://fonts.google.com/):

![Google Fonts language support selector](https://pdfmonkey.io/docs/img/google-fonts-language-support.webp)


## FAQ

**How do I use Google Fonts in a PDFMonkey template?**

Copy the <link> tag from Google Fonts and paste it at the top of your HTML tab, then reference the font family in your CSS. Loading fonts by URL requires a paid PDFMonkey plan.

**Can I use custom fonts in PDFMonkey headers and footers?**

Yes, but you must inline the font as a Base64 data URI inside a <style> tag in the header/footer settings. External font URLs do not work in settings-based headers and footers.

**How do I display emojis in a PDFMonkey PDF?**

Emoji rendering is disabled by default. Open your template, go to the Settings tab, and toggle the emoji option on. Once enabled, emoji characters in your template or dynamic data will render in the PDF.

**How do I display non-Latin characters like Chinese or Arabic in PDFMonkey?**

Import a web font that supports the character set you need. Google Fonts offers fonts for Arabic, Chinese, Japanese, Cyrillic, Hebrew, and many other scripts. The default Open Sans font only covers basic Latin characters.


---

# Custom JavaScript

Source: https://pdfmonkey.io/docs/code-templates/custom-javascript.md
The template editor provides an HTML tab and a CSS tab but no dedicated JavaScript tab. You can still use JavaScript by adding `script` tags directly in your HTML.

## Using Script Tags

To use JavaScript in your templates, open a `script` tag in the HTML tab:

```html title="HTML"
<script>
  // Write some JavaScript in here.
</script>
```

You can add as many script tags as needed, anywhere in your HTML.

## Accessing Document Data

To make JavaScript more powerful in your templates, you can access your Document payload as a JavaScript object.

Start by enabling JavaScript injection for your template in its Settings tab:

![](https://pdfmonkey.io/docs/img/template-settings-js-injection.webp)

Once enabled, a `$docPayload` object becomes available in your scripts. For example, given this payload:

```json title="JSON"
{
  "movie": {
    "title": "12 Monkeys",
    "year": 1995
  }
}
```

You can access the data like this:

```html title="HTML"
<script>
  const movieTitle = $docPayload.movie.title;
  const titleDiv = document.getElementById('mt');
  titleDiv.textContent = movieTitle;
</script>

<div id="mt"></div>
```

> [!WARNING]
> **Data access limitation with JavaScript**
>
> When accessing data with JS, **you cannot insert it** using the `{{movieTitle}}` syntax. This syntax is specific to [Liquid](https://pdfmonkey.io/docs/code-templates/the-liquid-syntax.md) and is executed before your JS code runs.
&gt; 
&gt; That said, you can generate JS code using Liquid:
&gt; 
&gt; ```html
&gt; &lt;script&gt;
&gt;   const movieTitle = &#34;{{movieTitle | upcase}}&#34;;
&gt; &lt;/script&gt;
&gt; ```


## External Libraries

> [!WARNING]
> **Paid account only**
>
> Including JavaScript based on their URL is only possible on a paid account. Documents including external JavaScript files will fail on a free account. See [External Resources](https://pdfmonkey.io/docs/getting-started/external-resources.md) for the full list.


If you need a library that transforms text, applies filters to images, or [inserts charts](#including-charts) in your Document, you can import it like you would in a normal HTML page.

For example, to render a Markdown string from your payload using [marked.js](https://marked.js.org/):

```html title="HTML"
<div id="notes"></div>

<script src="https://cdn.jsdelivr.net/npm/marked/marked.min.js"></script>
<script>
  document.getElementById('notes').innerHTML = marked.parse($docPayload.notes);
</script>
```

Any library loadable via CDN can be used in your templates this way.

## Formatting Dates and Times

PDFMonkey's engine runs on AWS servers located in Europe. The timezone of the server might not be the one you want your dates displayed in.

> [!TIP]
> **Use Liquid first**
>
> Most date formatting needs are covered by Liquid filters alone, no JavaScript required. Use the [in\_time\_zone](https://pdfmonkey.io/docs/code-templates/filters.md#in_time_zone) filter to set a timezone and the [date](https://pdfmonkey.io/docs/code-templates/filters.md#date) filter to format a date.


If Liquid filters don't cover your needs, JavaScript offers additional options.

### toLocaleString(locales, options)

The [toLocaleString](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/toLocaleString) method returns a string with a language-sensitive representation of a date.

The `locales` and `options` arguments let you specify the language whose formatting conventions should be used and customize the behavior of the function.

```html title="HTML"
<script>
  // Displaying the current date (PDF generation date) using French conventions.
  //
  new Date().toLocaleString('fr-FR');
  //=> "25/10/2050, 12:34:56"

  // Displaying a date provided in your Document payload using US conventions.
  // Sample payload
  // { "someDate": "2050-10-25 12:34:56" }
  //
  new Date($docPayload.someDate).toLocaleString('en-US');
  //=> "10/25/2050, 12:34:56 PM"

  // Displaying a date using en-US conventions in a custom timezone.
  //
  let date = new Date(Date.UTC(2050, 1, 1, 12, 34, 56));
  new Date(date).toLocaleString('en-GB', { timeZone: 'Pacific/Honolulu' });
  //=> "01/02/2050, 02:34:56"
</script>
```

You can learn more about the toLocaleString method in its [MDN documentation page](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/toLocaleString).

### Using a Library

> [!WARNING]
> **Paid account only**
>
> Using an external JS library will only work on a paid account. On a free account preview and generation will be blocked.


If you need the help of a more powerful library, you can load the one you need. The most frequently used one is MomentJS but we recommend [Luxon](https://moment.github.io/luxon/#/?id=luxon), a more recent iteration of the same idea by the actual author of MomentJS:

```html title="HTML"
<script src="https://cdn.jsdelivr.net/npm/luxon@2.3.1/build/global/luxon.min.js"></script>
<script>
  let { DateTime } = luxon;
  let date = DateTime.fromISO("2050-01-01T12:34:56");
  date.plus({ days: 3 }).setZone('Pacific/Honolulu').toLocaleString(DateTime.DATETIME_HUGE);
  //=> "Tuesday, 4 January 2050, 01:34 Hawaii-Aleutian Standard Time"
</script>
```

## Including Charts

> [!WARNING]
> **Paid account only**
>
> Including JavaScript based on their URL is only possible on a paid account. Documents including external JavaScript files will fail on a free account. See [External Resources](https://pdfmonkey.io/docs/getting-started/external-resources.md) for the full list.


You can use most charting libraries to generate charts in PDFMonkey. From our experience, [Chart.js](https://www.chartjs.org/) is the most reliable option ---it renders consistently across PDF readers and offers a wide variety of chart types.

Two settings are essential for charts in PDFs:

- **`animation: false`** ---Animations don't play in a PDF. If left enabled, the chart may render mid-transition, producing a blank or half-drawn graphic.
- **`responsive: false`** ---Disabling this lets you control the chart size through the `canvas` element's `width` and `height` attributes, avoiding layout surprises.

### Chart.js Example

The example below loads Chart.js from a CDN and renders a bar chart using data from the Document payload. It includes both critical settings mentioned above.

Given this payload:

```json title="Payload"
{
  "chart": {
    "labels": ["Jan", "Feb", "Mar", "Apr", "May"],
    "values": [120, 190, 150, 210, 175]
  }
}
```

Add this to your template's HTML:

```html title="HTML"
<canvas id="myChart" width="500" height="300"></canvas>

<script src="https://cdn.jsdelivr.net/npm/chart.js@4/dist/chart.umd.js"></script>
<script>
  new Chart(document.getElementById('myChart'), {
    type: 'bar',
    data: {
      labels: $docPayload.chart.labels,
      datasets: [{
        label: 'Monthly sales',
        data: $docPayload.chart.values,
        backgroundColor: '#4f8bc6'
      }]
    },
    options: {
      animation: false,
      responsive: false
    }
  });
</script>
```

![Example bar chart rendered with Chart.js](https://pdfmonkey.io/docs/img/chart-example.webp)

You can adapt this example to any [Chart.js chart type](https://www.chartjs.org/docs/latest/charts/) (line, pie, doughnut, radar, etc.) by changing the `type` value and adjusting the `data` structure.

> [!WARNING]
> **ApexCharts compatibility**
>
> [ApexCharts.js](https://apexcharts.com/) is known to produce black borders around charts in certain PDF readers, particularly on Windows and Android. If you use ApexCharts, test your output across multiple devices before going to production.


## Debugging

If your JavaScript is not behaving as expected, use the **Debug** button at the top of the template editor. It opens the HTML version of your template, generated from your test data, directly in your browser.

![](https://pdfmonkey.io/docs/img/template-debug-button.webp)

This gives you a chance to inspect JS errors in the console and should help in understanding what is going wrong.

## Browser Compatibility

Our current PDF engine (v5) is based on **Chrome&nbsp;133**. You can check if a specific JS feature is available using the [caniuse comparison table](https://caniuse.com/?compare=chrome+133&compareCats=JS,JS%20API).

> [!NOTE]
> If your templates use an older engine version, check [Our Engines](https://pdfmonkey.io/docs/code-templates/our-engines.md) to see which Chrome version applies to your engine.



## FAQ

**Can I use JavaScript in PDFMonkey templates?**

Yes. Add script tags directly in the HTML tab of the template editor. Enable JavaScript injection in the template settings to access your document payload via the $docPayload object.

**What JavaScript libraries are available in PDFMonkey?**

Chart.js for charts and graphs, and Day.js for date formatting are built into the rendering engine. On paid plans, you can also load external JavaScript libraries from a CDN.

**How do I access document data from JavaScript in PDFMonkey?**

Enable JavaScript injection in the template settings. A $docPayload object then becomes available in your scripts, containing the full JSON payload you passed when creating the document.


---

# Custom CSS for Code Templates

Source: https://pdfmonkey.io/docs/code-templates/custom-css.md
The template editor provides a dedicated CSS tab where you can write any standard CSS you need. Your styles apply to the HTML elements you insert in the HTML tab during rendering.

If you want to know whether a specific CSS feature is available, you can check [this compatibility list for Chrome&nbsp;133](https://caniuse.com/?compare=chrome+133&compareCats=CSS), the version used by our current engine (v5). Chrome&nbsp;133 supports virtually all modern CSS features, including **Flexbox**, **CSS Grid**, **Custom properties**, **Container queries**, and the **`:has()` pseudo-class**.

> [!NOTE]
> If your templates use an older engine version, check [Our Engines](https://pdfmonkey.io/docs/code-templates/our-engines.md) to see which Chrome version applies to your engine.


> [!TIP]
> **Looking for page layout?**
>
> For page sizing, margins, single-page layouts, full-page backgrounds, and page breaks, see [Page Layout](https://pdfmonkey.io/docs/code-templates/page-layout.md).


## External CSS Libraries

Writing your own CSS is always an option, but a utility-first CSS library can speed up template development significantly. Frameworks like Bootstrap tend to enforce strong opinions about print styles and can interfere with your layout. We recommend lighter-touch tools like [Tailwind CSS](https://tailwindcss.com/) or [Tachyons](https://tachyons.io/) instead.

> [!WARNING]
> **Paid account only (mostly)**
>
> Loading CSS from a URL requires a paid account. See [External Resources](https://pdfmonkey.io/docs/getting-started/external-resources.md) for the full definition and plan availability.
&gt; 
&gt; That said, **an exception is made for CSS hosted on our own servers** — see [Hosted Tailwind CSS Versions](#hosted-tailwind-css-versions) below.


## Hosted Tailwind CSS Versions {#hosted-tailwind-css-versions}

PDFMonkey provides Master Templates, and we made hosted versions of the resources used to build them available to everyone. Because these files are hosted on our servers, they work on **both Free and paid accounts** — no external resource restriction applies.

### Tailwind CSS v4.x and v3.x (JIT)

These versions work just like the one available using the [Tailwind CSS CDN](https://tailwindcss.com/docs/installation/play-cdn). Include the script in your HTML tab, replacing the official CDN link with ours:

```html title="HTML"
<script src="https://pdfmonkey-resources.s3-eu-west-3.amazonaws.com/js/tailwindcss-4.js"></script>
```

Available versions:

* [tailwindcss-4.js](https://pdfmonkey-resources.s3-eu-west-3.amazonaws.com/js/tailwindcss-4.js) (latest, currently 4.1.17)
* [tailwindcss-4.1.17.js](https://pdfmonkey-resources.s3-eu-west-3.amazonaws.com/js/tailwindcss-4.1.17.js)
* [tailwindcss-4.0.1.js](https://pdfmonkey-resources.s3-eu-west-3.amazonaws.com/js/tailwindcss-4.0.1.js)
* [tailwindcss-3.4.3.js](https://pdfmonkey-resources.s3-eu-west-3.amazonaws.com/js/tailwindcss-3.4.3.js)
* [tailwindcss-3.3.3.js](https://pdfmonkey-resources.s3-eu-west-3.amazonaws.com/js/tailwindcss-3.3.3.js)
* [tailwindcss-3.2.6.js](https://pdfmonkey-resources.s3-eu-west-3.amazonaws.com/js/tailwindcss-3.2.6.js)
* [tailwindcss-3.2.0.js](https://pdfmonkey-resources.s3-eu-west-3.amazonaws.com/js/tailwindcss-3.2.0.js)
* [tailwindcss-3.0.23.js](https://pdfmonkey-resources.s3-eu-west-3.amazonaws.com/js/tailwindcss-3.0.23.js)

For v3.x versions, you can customize the configuration just like you would with the official CDN:

```html title="HTML"
<script src="https://pdfmonkey-resources.s3-eu-west-3.amazonaws.com/js/tailwindcss-3.0.23.js"></script>
<script>
  tailwind.config = {
    theme: {
      extend: {
        colors: {
          clifford: '#da373d',
        }
      }
    }
  }
</script>
<style type="text/tailwindcss">
  @layer utilities {
    .content-auto {
      content-visibility: auto;
    }
  }
</style>
```

### Tailwind CSS v2.0.3 (Legacy)

We provide a light version of Tailwind CSS v2.0.3, stripped of any style that does not make sense in a printing context, like animations or responsive utilities. It weighs 165 KB.

You can import it from your CSS tab using:

```css title="CSS"
@import url("https://pdfmonkey-resources.s3.eu-west-3.amazonaws.com/css/tailwind-light.min.css");
```

You can also import it from the HTML tab but know that your styles will be defined before, and it can make it harder to override Tailwind's classes.

## Per-Document Styles {#the-css-custom-properties-technique}

Code you write in the CSS tab cannot call variables provided in the Document payload. That said, you can use CSS custom properties (a.k.a CSS variables) to pass dynamic values to your CSS on a per-document basis.

For example, if you want to pass a color in your data:

```json title="JSON payload"
{
  "color": "#db2777"
}
```

You can create a custom property that takes its value and makes it available to your CSS:

```html title="HTML"
<style>
  :root {
    --color: "{{color}}";
  }
</style>
```

```css title="CSS"
h1 {
  color: var(--color);
}
```

This technique works for any CSS value: colors, font sizes, spacing, or even font families.


## FAQ

**Can I use Tailwind CSS in PDFMonkey templates?**

Yes. PDFMonkey hosts several Tailwind CSS versions (v2 through v4) on its own servers, so they work on both free and paid plans. Include the script tag in your HTML tab pointing to the hosted version.

**How do I pass dynamic CSS values in PDFMonkey?**

Use CSS custom properties. Define a variable in a <style> tag in your HTML using Liquid syntax (e.g., --color: "{{color}}"), then reference it in your CSS tab with var(--color). This lets you change colors, fonts, or spacing per document.

**What CSS features does PDFMonkey support?**

PDFMonkey’s current engine (v5) is based on Chrome 133, which supports virtually all modern CSS features including Flexbox, CSS Grid, custom properties, container queries, and the :has() pseudo-class.


---

# Using QR Codes for Code Templates

Source: https://pdfmonkey.io/docs/code-templates/qr-codes.md
Adding QR codes to PDF documents is a common requirement for invoices, shipping labels, event tickets, and more. PDFMonkey supports several JavaScript libraries that let you generate QR codes directly inside your templates with full control over style and content.

> [!WARNING]
> **Paid account only**
>
> This technique uses JavaScript and is thus only usable on a paid account or during [your 30-day trial](https://pdfmonkey.io/docs/getting-started/the-30-day-trial.md).


## qr-code-styling (recommended) {#qr-code-styling}

[qr-code-styling](https://github.com/kozakdenys/qr-code-styling) is the library we use in the PDFMonkey Builder. It offers the most customization: multiple dot styles (square, dots, rounded, classy...), corner styles, custom colors, error correction levels, and even a centered logo.

```html
<script src="https://cdn.jsdelivr.net/npm/qr-code-styling@^1.6/lib/qr-code-styling.js"></script>

<div id="qrcode"></div>

<script type="text/javascript">
  var qrCode = new QRCodeStyling({
    width: 200,
    height: 200,
    data: "https://pdfmonkey.io/",
    margin: 0,
    dotsOptions: {
      type: "rounded",
      color: "#0ea5e9"
    },
    cornersSquareOptions: {
     type: "extra-rounded"  // square, dot, extra-rounded
    }
  });

  qrCode.append(document.getElementById("qrcode"));
</script>
```

You can also add a logo in the center of the QR code by passing `image` and `imageOptions`:

```html
<script src="https://cdn.jsdelivr.net/npm/qr-code-styling@^1.6/lib/qr-code-styling.js"></script>

<div id="qrcode"></div>

<script type="text/javascript">
  var qrCode = new QRCodeStyling({
    width: 200,
    height: 200,
    data: "https://pdfmonkey.io/",
    margin: 0,
    dotsOptions: {
      type: "rounded",
      color: "#0ea5e9"
    },
    cornersSquareOptions: {
     type: "extra-rounded"  // square, dot, extra-rounded
    },

    image: "https://example.com/logo.png",
    imageOptions: {
      imageSize: 0.4,
      margin: 4,
      crossOrigin: "anonymous"
    },
    qrOptions: {
      errorCorrectionLevel: "Q"  // use Q or H when adding a logo
    }
  });

  qrCode.append(document.getElementById("qrcode"));
</script>
```

![QR code generated with qr-code-styling](https://pdfmonkey.io/docs/img/qr-code-example.webp)

## bitjson/qr-code

[This library](https://qr.bitjson.com/) offers a very simple web-component you can use to insert a QR Code in your document. It has no dependencies so you can simply link to the library using a CDN and insert the component in your code:

```html
<script src="https://cdn.jsdelivr.net/npm/@bitjson/qr-code@^1.0/dist/qr-code.js"></script>

<!--
  contents: the text to transform
  module-color: color of the dots
  position-ring-color: color of the large surrounding squares
  position-center-color: color of the small surrounding squares
-->
<qr-code
  contents="https://pdfmonkey.io/"
  module-color="#0ea5e9"
  position-ring-color="#db7222"
  position-center-color="#27db22"
  style="width: 200px;"
></qr-code>
```

> [!WARNING]
> **Avoid animations**
>
> Animations and PDF rendering usually don&#39;t play nice. Avoid copy/pasting pieces of code that use animation, or removing the animation part, otherwise the QR Code might not finish its animation before &#34;printing&#34;, resulting in an absent or incomplete QR Code.


### Dots-only

The main drawback of this library is that you're stuck with the style of the dots. You can only get circles.

## QRCode.js

For a more "classic" looking QR Code, the [QRCode.js](https://davidshimjs.github.io/qrcodejs/) library is a good option. It doesn't offer much customization but it should be good enough in most cases.

```html
<script src="https://cdn.jsdelivr.net/npm/qrcodejs@^1.0/qrcode.min.js"></script>

<div id="qrcode"></div>

<script type="text/javascript">
  new QRCode(
    document.getElementById("qrcode"),
    {
      text: "http://pdfmonkey.io/",
      width: 200,
      height: 200,
      correctLevel: QRCode.CorrectLevel.L
    }
  );
</script>

```

All three libraries work with PDFMonkey's PDF rendering engine. To learn more about loading and using JavaScript in your templates, see [Custom JavaScript](https://pdfmonkey.io/docs/code-templates/custom-javascript.md).


## FAQ

**How do I add a QR code to a PDFMonkey PDF?**

Include a JavaScript QR code library via a CDN script tag in your HTML. PDFMonkey supports qr-code-styling (recommended), bitjson/qr-code, and QRCode.js. A paid plan or active trial is required because external scripts are needed.

**Which QR code library should I use with PDFMonkey?**

qr-code-styling is recommended. It offers the most customization — dot styles, corner styles, custom colors, error correction levels, and the ability to embed a logo in the center of the QR code.

**Can I add a logo inside a QR code in PDFMonkey?**

Yes. Use the qr-code-styling library and pass the image and imageOptions properties. Set the error correction level to Q or H so the QR code remains scannable with the logo overlay.


---

# Header and Footer

Source: https://pdfmonkey.io/docs/code-templates/header-and-footer.md
Headers and footers let you repeat information on every page of your PDF: a company logo, a document title, page numbers, a date, legal text, etc. PDFMonkey offers three ways to add them, each with different trade-offs. Pick the simplest one that meets your needs.

| Approach | Best for | Supports external images/fonts | Page numbers | Skip cover page |
|---|---|---|---|---|
| [Settings-based](#settings-based) | Flowing content (contracts, reports) | No (inline only) | Yes | No |
| [In-content](#in-content) | Fixed-layout pages (certificates, books) | Yes | Via CSS counter | Yes |
| [Paged.js](#pagedjs) | Flowing content needing rich headers | Yes | Yes | Yes |

## Settings-Based Header and Footer {#settings-based}

The simplest approach. Open your Template's **Settings** tab and fill in the header and/or footer fields. The content is rendered on every page, on top of the document content.

> [!WARNING]
> **Set your margins first**
>
> Header and footer content only appears if the Template has a top and/or bottom margin. If nothing shows up, increase the margins in the Settings tab.


### Basic mode

The default fields give you three slots (left, center, right) per header and footer. You can use two special tags:

- `[page]` — current page number
- `[topage]` — total number of pages

### Advanced mode

Switch to Advanced mode to write custom HTML. You get full control over the layout and can use these HTML equivalents for page numbers:

```html
<span class="pageNumber"></span>  <!-- current page number -->
<span class="totalPages"></span>  <!-- total number of pages -->
```

You can also use dynamic data (Liquid syntax) in advanced mode. For accented characters, apply the [`entities` filter](https://pdfmonkey.io/docs/code-templates/filters.md#entities):

```liquid
{{ company.name | entities }}
```

### Limitations

Settings-based headers and footers are rendered by Chromium's built-in print header/footer mechanism, which comes with hard constraints:

- **No external resources** — images, CSS, and fonts cannot be loaded over HTTP. Use [data URIs](https://css-tricks.com/data-uris/) for images and inline `<style>` tags for CSS. For fonts, see [Fonts in Headers and Footers](https://pdfmonkey.io/docs/code-templates/web-fonts.md#fonts-in-headers-and-footers).
- **No UTF-8 for accented characters** — fixed text needs [HTML entities](https://dev.w3.org/html5/html-author/charref) (e.g. `&eacute;` for `é`). For dynamic data, use the [`entities` filter](https://pdfmonkey.io/docs/code-templates/filters.md#entities).
- **No JavaScript execution** — no workaround.
- **No way to skip the cover page** — no workaround.
- **Limited styling control** — the CSS tab does not apply inside the header/footer area. Styles must be inlined.

## In-Content Header and Footer {#in-content}

For fixed-layout documents where you control each page individually — certificates, children's books, slide-style reports — you can place the header and footer directly in your HTML content. This approach gives you full access to the CSS tab, external images, web fonts, and JavaScript. No encoding workarounds needed.

<span id="exception-powerpoint-like-documents"></span>

A document is "fixed-layout" when each page is a distinct block with a known size, and content does not flow from one page to the next. Every `<div class="page">` is self-contained.

### Page numbers with CSS counters

Since the HTML content does not know which page it is on, you use a CSS counter to track page numbers. Here is a portrait A4 example:

```html title="HTML"
<div class="page">
  <div>Content of Page 1</div>
  <div class="page-number"></div>
</div>

<div class="page">
  <div>Content of Page 2</div>
  <div class="page-number"></div>
</div>

<div class="page">
  <div>Content of Page 3</div>
  <div class="page-number"></div>
</div>
```

```css title="CSS"
/* Initialize a counter named "page" at 0 */
/* Remove default spacing so pages are correctly sized */
body {
  counter-reset: page;
  margin: 0;
  padding: 0;
}

/* A portrait A4 page is 793x1120px */
/* Hide overflow to prevent print zoom artifacts */
.page {
  height: 1120px;
  overflow: hidden;
  position: relative;
  width: 793px;
}

/* Position the page number at the bottom-right of each page */
.page-number {
  bottom: 30px;
  position: absolute;
  right: 30px;
  text-align: right;
}

/* Increment the counter and display it */
.page-number::before {
  counter-increment: page;
  content: counter(page);
}
```

![CSS counter page numbers](https://pdfmonkey.io/docs/img/page-number-css-counter.webp)

CSS counters are more robust than hardcoding numbers in the HTML because they stay accurate when pages are conditionally shown/hidden or generated in a loop.

### Limitations

- **Only works for fixed-layout documents.** If your content flows across pages (like a long contract), you cannot predict where page breaks will fall, so you cannot place a footer at the bottom of each page. Use [Paged.js](#pagedjs) instead.

## Paged.js Header and Footer {#pagedjs}

[Paged.js](https://pagedjs.org/about/) is a JavaScript library that implements the CSS Paged Media specification. It gives you full-featured running headers and footers for flowing content — with full CSS, fonts, images, and JavaScript support.

> [!WARNING]
> **Paid plan required**
>
> Loading external JavaScript by URL requires a paid PDFMonkey plan. Documents that include external scripts will fail on a free plan.


### How it works

Paged.js uses two CSS concepts:

1. **Running elements** — you define HTML elements and declare them as `running()` in CSS. They are removed from the normal flow.
2. **Margin boxes** — in an `@page` rule, you place those running elements into page margin areas (`@top-center`, `@bottom-center`, etc.).

### Step-by-step example

**1. Define header and footer elements in your HTML:**

```html title="HTML"
<div id="pageHeader">
  <div class="header-content">
    <img src="https://placekitten.com/60/60" />
    <div>Header Text</div>
  </div>
</div>

<div id="pageFooter">
  <div class="footer-content">
    <div>Footer Left</div>
    <div>Footer Right</div>
  </div>
</div>

<div class="content">Your document content goes here.</div>

<script src="https://cdn.jsdelivr.net/npm/pagedjs@0.3.5/dist/paged.polyfill.js"></script>
```

**2. Declare them as running elements and style them in your CSS tab:**

> [!WARNING]
> **CSS tab only**
>
> Unless you use the Tailwind CSS 3 JavaScript CDN, the `@page` rule below **must** go in the CSS tab, not in a `&lt;style&gt;` tag inside the HTML tab. Otherwise it will not work.


```css title="CSS"
/* Declare as running elements */
#pageHeader {
  position: running(pageHeader);
}

#pageFooter {
  position: running(pageFooter);
}

/* Style the header and footer content */
.header-content, .footer-content {
  align-items: center;
  background: #1f2937;
  color: #fff;
  display: flex;
  height: 80px; /* Match this with the @page margin below */
  justify-content: space-between;
  padding: 0 30px;
}

.content {
  text-align: center;
}
```

**3. Place them in the page margins:**

```css title="CSS"
@page {
  size: A4;

  /* Use the same height as the header/footer content */
  margin: 80px 0;

  /* Place running elements in page margins */
  @top-center { content: element(pageHeader); }
  @bottom-center { content: element(pageFooter); }
}
```

The result:

![Paged.js header and footer](https://pdfmonkey.io/docs/img/page-number-paged-js.webp)

> [!NOTE]
> **Page size**
>
> This example uses A4. You can use other named sizes like `A3`, `Letter`, etc. or pixel values. See [default page sizes in pixels](https://pdfmonkey.io/docs/code-templates/page-layout.md#default-page-sizes-in-pixels).


> [!NOTE]
> **Names must match**
>
> The name in `running(pageHeader)` must match the name in `element(pageHeader)`. If you used `running(superHeader)`, you would call `element(superHeader)`.


### Known issue: multi-page table headers

Paged.js can break tables that span multiple pages when they have `<thead>` elements. If you run into this, see this [workaround on GitHub](https://gist.github.com/theinvensi/e1aacc43bb5a3d852e2e85b08cf85c8a).

### Learn more

For page counters, dynamic content in margins, first-page exceptions, and other advanced features, see the Paged.js documentation on [Generated Content in Margin Boxes](https://pagedjs.org/documentation/7-generated-content-in-margin-boxes/).


## FAQ

**How do I add headers and footers to a PDFMonkey PDF?**

PDFMonkey offers three approaches: settings-based (fill in the header/footer fields in the Settings tab), in-content (place header and footer HTML directly in your template for fixed-layout documents), and Paged.js (a JavaScript library for flowing content with rich headers and footers).

**Can I add page numbers to my PDFMonkey PDF?**

Yes. In settings-based mode use the [page] and [topage] tags. For in-content layouts use CSS counters. With Paged.js, use the built-in page counter support in CSS margin boxes.

**Why are my header and footer images not showing in PDFMonkey?**

Settings-based headers and footers cannot load external resources over HTTP. Use data URIs for images and inline styles for CSS. Alternatively, switch to in-content or Paged.js headers which support external images and fonts.

**How do I skip the header on the first page of my PDF?**

Settings-based headers cannot skip the cover page. Use the Paged.js approach instead — it supports first-page exceptions through CSS @page :first rules and running elements.


---

# Reusable Template Components with Snippets and Partials

Source: https://pdfmonkey.io/docs/code-templates/reusing-code.md
PDFMonkey gives you two ways to reuse code and avoid duplication:

- **Snippets** are shared across templates — define them once on the Snippets page and include them in any template.
- **Partials** are local to a single template — define a reusable block inline and include it multiple times in the same template.

Both use the `include` tag to render the reusable block with the variables you pass.

## Snippets

If you need to share code between Templates, you can define snippets in the **Snippets** page of your PDFMonkey account. The name you give a Snippet is how you will refer to it later on in your Templates.

Let's define two snippets:

```liquid title="Snippet: user-name"
{%- if userName -%}
  {{userName}}
{%- else -%}
  Someone
{%- endif -%}
```

```liquid title="Snippet: items-list"
{%- for item in list -%}
  <p>{{item}}</p>
{%- endfor -%}
```

You can then load and include them in a Template:

```liquid title="Template"
{%- load_snippets 'user-name', 'items-list' -%}

<p>Hello {% include 'user-name', userName: "Jane Doe" %}</p>

{% include 'items-list', list: user.groceries %}
```

> [!NOTE]
> You must load snippets with `load_snippets` before you can `include` them. List all the snippets you need in a single `load_snippets` call at the top of your template.


## Partials

Partials work like Snippets but are defined directly within a Template. You don't need to load them before including them:

```liquid title="Template"
{%- partial 'line-item' -%}
  <tr>
    <td>{{product.name}}</td>
    <td>{{product.unitPrice}}</td>
    <td>{{product.quantity}}</td>
    <td>{{product.totalPrice}}</td>
  </tr>
{%- endpartial -%}

{% for lineItem in lineItems %}
  {% include 'line-item', product: lineItem %}
{% endfor %}
```

Partials are ideal when you need to repeat a block within a single template — like a table row, a card layout, or any recurring element — without the overhead of creating a shared Snippet.


## FAQ

**How do I reuse code across multiple PDFMonkey templates?**

Use Snippets. Define reusable code blocks on the Snippets page of your PDFMonkey account, then load them in any template with the load_snippets tag and include them with the include tag.

**What is the difference between Snippets and Partials in PDFMonkey?**

Snippets are shared across templates — define them once and include them in any template. Partials are local to a single template — define a reusable block inline and include it multiple times within the same template.

**How do I pass variables to a Snippet or Partial in PDFMonkey?**

Pass variables as key-value pairs in the include tag. For example: {% include ‘user-name’, userName: “Jane Doe” %}. The Snippet or Partial can then use those variables in its Liquid code.


---

# Interactive PDF Forms (AcroForms)

Source: https://pdfmonkey.io/docs/code-templates/pdf-forms.md
PDFMonkey can generate interactive PDF forms (AcroForms) by detecting special markers in your template and converting them into fillable form fields. The generated PDFs can be filled out directly in PDF readers like Adobe Acrobat or Preview.

## Enabling PDF Forms

To enable PDF forms in your template:

1. Go to your template\u2019s **Settings** tab
2. Enable the **PDF Forms** option
3. Add form field markers to your template content

When using the API, set `use_forms: true` in your template\u2019s `settings` or `settings_draft` object.

## Marker Syntax

Markers follow a specific syntax that tells PDFMonkey what type of field to create and how to configure it:

```
[% data_form_field_TYPE_NAME_OPTIONS %]
```

### Required elements

- `[%` and `%]` \u2014 start and end delimiters
- `data_form_field` \u2014 required prefix for detection
- `TYPE` \u2014 field type (text, checkbox, dropdown, etc.)

### Optional elements

- `NAME` \u2014 custom field name (e.g., `firstname`, `email`)
- `OPTIONS` \u2014 dimensions, validation, alignment, etc.

### Basic examples

```html
[% data_form_field_text_w200_h30 %]
[% data_form_field_checkbox_w20_h20 %]
[% data_form_field_dropdown_w250_h30_options[Option1,Option2,Option3] %]
```

## Field Types

### Text fields

#### Single-line text

```html
[% data_form_field_text_w300_h30 %]
[% data_form_field_text_firstname_w250_h30_required %]
```

Use for: names, addresses, phone numbers, short text.

#### Multi-line text (textarea)

```html
[% data_form_field_textarea_w400_h100 %]
[% data_form_field_textarea_comments_w500_h150_max500 %]
```

Use for: comments, descriptions, long messages.

#### Password field

```html
[% data_form_field_text_password_w250_h30_password %]
```

#### Email field (with validation)

```html
[% data_form_field_text_email_w350_h30_email %]
[% data_form_field_text_contact_w400_h30_required_email %]
```

#### Phone field

```html
[% data_form_field_text_phone_w200_h30_phone %]
```

### Selection fields

#### Checkbox

```html
[% data_form_field_checkbox_w20_h20 %]
[% data_form_field_checkbox_accept_terms_w20_h20_required %]
```

Example in a template:

```html
<p>\u2610 I accept the terms [% data_form_field_checkbox_accept_w20_h20 %]</p>
<p>\u2610 Subscribe to newsletter [% data_form_field_checkbox_newsletter_w20_h20 %]</p>
```

#### Dropdown (select)

```html
[% data_form_field_dropdown_w250_h30_options[Option1,Option2,Option3] %]
[% data_form_field_dropdown_country_w300_h30_options[France,Belgium,Switzerland,Canada] %]
```

> [!WARNING]
> You must specify all options in the marker using `options[A,B,C]`. A dropdown without options will not be created.


#### Radio buttons

```html
[% data_form_field_radio_w20_h20_options[Male,Female,Other] %]
[% data_form_field_radio_payment_w20_h20_options[Card,Transfer,Cash] %]
```

Radio buttons with the same name form a group \u2014 only one option can be selected at a time.

### Specialized fields

#### Number field

```html
[% data_form_field_number_w100_h30 %]
[% data_form_field_number_age_w80_h30_min18_max120 %]
[% data_form_field_number_quantity_w60_h30_min1_max99 %]
```

#### Date field

```html
[% data_form_field_date_w150_h30_format_dd_mm_yyyy %]
[% data_form_field_date_birthdate_w150_h30_format_dd_mm_yyyy_required %]
```

Available formats:

- `format_dd_mm_yyyy` \u2014 DD/MM/YYYY (European)
- `format_mm_dd_yyyy` \u2014 MM/DD/YYYY (US)
- `format_yyyy_mm_dd` \u2014 YYYY-MM-DD (ISO)

#### Comb field (for codes)

```html
[% data_form_field_text_zipcode_w150_h30_max5_comb %]
[% data_form_field_text_serial_w200_h30_max10_comb %]
```

Use for: postal codes, serial numbers, verification codes. Each character has its own visual box.

#### Borderless fields

```html
[% data_form_field_text_w300_h30_noborder %]
[% data_form_field_text_user_id_w200_h30_invisible_readonly %]
```

Use for elegant forms without black rectangles, invisible metadata fields, or pre-filled values. The `noborder` option sets the border to 0 and the background to transparent while keeping the field fully functional.

**Dotted guide line technique:** combine white marker text, `noborder`, and manually drawn dotted lines underneath:

```html
<p style="color: white;">[% data_form_field_text_email_w350_h30_noborder_email %]</p>
<p style="border-bottom: 1px dotted #999; width: 350px;"></p>
```

The white marker is invisible in the PDF, the dotted lines guide the user, and the generated field is transparent and functional.

## Field Options

### Dimensions

Required for proper rendering:

| Option | Description |
|:---|:---|
| `w{width}` | Width in pixels |
| `h{height}` | Height in pixels |

**Recommended sizes:**

| Field type | Width | Height |
|:---|:---|:---|
| Short name | 150\u2013250 px | 30 px |
| Email | 300\u2013400 px | 30 px |
| Address | 400\u2013500 px | 30 px |
| Textarea | 400\u2013600 px | 80\u2013150 px |
| Checkbox | 20 px | 20 px |
| Dropdown | 200\u2013300 px | 30 px |
| Date | 120\u2013150 px | 30 px |
| Number | 60\u2013100 px | 30 px |

### Field state

| Option | Description |
|:---|:---|
| `required` | Required field |
| `mandatory` | Alias for required |
| `readonly` | Read-only (not editable) |

### Constraints

| Option | Description |
|:---|:---|
| `max{number}` | Maximum length (text) or maximum value (number) |
| `min{number}` | Minimum value (number only) |

### Alignment and style

| Option | Description |
|:---|:---|
| `left` | Left-aligned text (default) |
| `center` | Centered text |
| `right` | Right-aligned text |
| `font{size}` | Font size (10, 12, 14, etc.) |

### Default values

Pre-fill a field using `default_{value}`. Replace spaces with underscores:

```html
[% data_form_field_text_country_w200_h30_default_France %]
[% data_form_field_text_w300_h30_default_Enter_your_name %]
```

### Custom field names

The first unrecognized element in the marker becomes the field name:

```html
[% data_form_field_text_firstname_w200_h30 %]
```

Here `firstname` is the field name. Use descriptive snake_case names (`user_email` rather than `email1`) to make data processing easier.

## Complete Examples

### Contact form

```html
<h1>Contact Form</h1>

<p>Last name: [% data_form_field_text_lastname_w300_h30_required %]</p>
<p>First name: [% data_form_field_text_firstname_w300_h30_required %]</p>
<p>Email: [% data_form_field_text_email_w350_h30_required_email %]</p>
<p>Phone: [% data_form_field_text_phone_w200_h30_phone %]</p>

<p>Message:</p>
<p>[% data_form_field_textarea_message_w500_h120_required_max1000 %]</p>

<p>\u2610 I agree to be contacted [% data_form_field_checkbox_accept_w20_h20 %]</p>
```

### Registration form

```html
<h1>Registration Form</h1>

<h2>Personal Information</h2>
<p>Title: [% data_form_field_dropdown_civility_w100_h30_options[Mr,Mrs,Ms] %]</p>
<p>Last name: [% data_form_field_text_lastname_w250_h30_required %]</p>
<p>First name: [% data_form_field_text_firstname_w250_h30_required %]</p>
<p>Birth date: [% data_form_field_date_birthdate_w150_h30_format_dd_mm_yyyy %]</p>
<p>Age: [% data_form_field_number_age_w80_h30_min18_max120 %]</p>

<h2>Contact</h2>
<p>Email: [% data_form_field_text_email_w350_h30_required_email %]</p>
<p>Phone: [% data_form_field_text_phone_w200_h30_phone %]</p>

<h2>Address</h2>
<p>Street: [% data_form_field_text_address_w450_h30_required %]</p>
<p>Postal code: [% data_form_field_text_zipcode_w120_h30_max5_comb %]</p>
<p>City: [% data_form_field_text_city_w250_h30_required %]</p>
<p>Country: [% data_form_field_dropdown_country_w250_h30_options[France,Belgium,Switzerland,Canada] %]</p>

<h2>Terms</h2>
<p>\u2610 I accept the terms [% data_form_field_checkbox_accept_terms_w20_h20_required %]</p>
<p>\u2610 Subscribe to newsletter [% data_form_field_checkbox_newsletter_w20_h20 %]</p>
```

## Troubleshooting

### Marker not detected

The marker remains visible in the final PDF. Check:

1. The prefix is exactly `data_form_field` (not `form_field` or `data_field`)
2. The delimiters are `[%` and `%]` (not `{%` `%}` or other brackets)
3. There are no line breaks inside the marker

### Field mispositioned

Adjust the `w` and `h` dimensions and make sure there is enough space in the template around the marker.

### Dropdown or radio without options

Dropdowns and radio buttons require the `options[...]` parameter. Without it, the field is not created.

```
[% data_form_field_dropdown_country_w250_h30_options[France,Belgium,Switzerland] %]
```

## Best Practices

1. **Start simple** \u2014 test with 2\u20133 fields before building a complete form
2. **Name your fields** \u2014 use descriptive names for easier data processing
3. **Test in preview** \u2014 always preview your template before generating documents
4. **Use default values** \u2014 pre-fill common fields to reduce input effort
5. **Hide markers visually** \u2014 set the marker text color to match the background so it doesn\u2019t show through the form field:
   ```html
   <span style="color: white;">[% data_form_field_text_name_w300_h30 %]</span>
   ```
6. **Combine border styles** \u2014 use classic borders for required fields and `noborder` for secondary fields to create visual hierarchy

## Limitations

- Signature fields are not currently supported as interactive form fields
- Complex field validation beyond basic types (email, phone) is limited
- Fields work best with PDF Engine v5

## Related pages

- [Page Layout](https://pdfmonkey.io/docs/code-templates/page-layout.md) \u2014 control page sizing and margins
- [Custom CSS](https://pdfmonkey.io/docs/code-templates/custom-css.md) \u2014 style your forms
- [API Templates reference](https://pdfmonkey.io/docs/api/templates.md) \u2014 API documentation for template settings


## FAQ

**Can PDFMonkey generate fillable PDF forms?**

Yes. Enable the PDF Forms option in your template settings, then add marker syntax in your HTML. PDFMonkey detects the markers and converts them into interactive AcroForm fields in the generated PDF.

**What types of form fields does PDFMonkey support?**

PDFMonkey supports text fields, multi-line text areas, checkboxes, dropdowns, radio buttons, number fields, date fields, and comb fields. Each field type accepts options for dimensions, validation, alignment, and default values.

**Do PDF form fields work with the API?**

Yes. Enable forms via the API by setting use_forms: true in your template settings. The marker syntax in the template HTML is processed during generation, producing interactive fields in the output PDF.


---

# CLI

Source: https://pdfmonkey.io/docs/code-templates/cli.md
This CLI tool is a great solution for developers who want to author [PDFMonkey](https://pdfmonkey.io) templates using their own code editor and local development environment.

## Installation

The PDFMonkey CLI can be installed using npm.

```bash
npm install -g @pdfmonkey/cli
```

Once installed, the `pdfmonkey` command will be available in your terminal.

## Help

To get a list of available commands and general help, run the following command:

```bash
pdfmonkey help
```

## Authentication

There are two ways to authenticate with the PDFMonkey CLI:

1. All commands accept the `-k` or `--api-key` option to specify an API key.
2. You can also set the `PDFMONKEY_API_KEY` environment variable.

> [!WARNING]
> **API Key in this page**
>
> The commands below will **assume the API key is set in the environment variable.**


## Command Structure

PDFMonkey CLI supports two command structures:

### Resource-based Commands (Recommended)

Commands are organized by resource type:

```bash
pdfmonkey <resource> <command> [options]
```

Currently supported resources:

- `template` or `tpl`: Manage PDFMonkey templates
- `snippet` or `snp`: Manage PDFMonkey snippets

For example:

```bash
pdfmonkey template init <template-id>
# or using the shorthand alias
pdfmonkey tpl init <template-id>
```

### Direct Commands (shorthand)

Templates being the most common resource, the CLI also supports direct commands:

```bash
pdfmonkey init <template-id>
# is the same as
pdfmonkey template init <template-id>

pdfmonkey watch <path>
# is the same as
pdfmonkey template watch <path>
```

## Template Management

### Init

To start editing a PDFMonkey template, run the following command:

```bash
pdfmonkey template init
```

The command will help you select a workspace and find the template you want to edit.

Alternatively, you can specify the template ID as a second argument.

```bash
pdfmonkey template init <template-id>
```

You will then be prompted to choose the destination folder for the template files. You can also specify the destination folder as a second argument.

```bash
pdfmonkey template init <template-id> <destination-folder>
```

> [!TIP]
> **Open in Editor**
>
> You can also open the created folder in your default editor using the `-e` or `--edit` option.
&gt; 
&gt; ```bash
&gt; pdfmonkey template init &lt;template-id&gt; -e
&gt; ```


### Watch

To start watching a template folder and sync the changes to PDFMonkey, run the following command:

```bash
pdfmonkey template watch
```

This will start watching files in **the current folder** and sync automatically. The CLI uses the metadata stored in the `.pdfmonkey.json` file to identify the template.

To monitor a different folder, simply pass the path as the first argument:

```bash
pdfmonkey template watch <path>
```

If for some reason the folder doesn't contain metadata or you want to use a different template ID, you can specify it using the `-t` option:

```bash
pdfmonkey template watch [path] -t <template-id>
```

### Preview

The `watch` command will start a local server to preview the template. The preview will automatically refresh when changes are synced.

You can open the preview when the server is running using the `-o` or `--open-browser` option.

```bash
pdfmonkey template watch -o
```

By default, the preview server runs on port 2081 and the live-reload server runs on port 2082. You can specify different ports using the `-p/--port` and `-l/--livereload-port` options.

```bash
pdfmonkey template watch -p 2083 -l 2084
```

Alternatively, you can set the `PORT` and `LIVE_RELOAD_PORT` environment variables to customize the ports.

```bash
PORT=2083 LIVE_RELOAD_PORT=2084 pdfmonkey template watch
```

### Debug Preview

Sometimes, it can be easier to debug the generated HTML instead of the PDF. You can do this by using the `-D` or `--debug` option.

```bash
pdfmonkey template watch -D -o
```

This will open the debug preview in your default browser.

### Dealing with conflicts

When starting the `watch` command, the CLI will check if there are any conflicts between the local files and the template data. If there are, you will be prompted to choose between:

1. Overwrite the local files with the template data.
2. Keep the local files and override the template data on the next sync.
3. To see a diff of the changes.

By default, the diff tool used is `diff -u` and the patch is displayed with the `less` pager. You can specify different diff-tool and pager using the `DIFF` and `PAGER` environment variables, respectively.

```bash
DIFF=delta PAGER=delta pdfmonkey template watch
```

## Snippet Management

### Init

To start editing a PDFMonkey snippet, run the following command:

```bash
pdfmonkey snippet init
```

The command will help you select a workspace and find the snippet you want to edit.

Alternatively, you can specify the snippet ID as a second argument.

```bash
pdfmonkey snippet init <snippet-id>
```

You will then be prompted to choose the destination folder for the snippet. You can also specify the destination folder as a second argument.

```bash
pdfmonkey snippet init <snippet-id> <destination-folder>
```

The snippet will be stored in a folder structure similar to templates, with the code in a file named `code.liquid`.

> [!TIP]
> **Open in Editor**
>
> You can also open the created file in your default editor using the `-e` or `--edit` option.
&gt; 
&gt; ```bash
&gt; pdfmonkey snippet init &lt;snippet-id&gt; -e
&gt; ```


### Watch

To start watching a snippet folder and sync the changes to PDFMonkey, run the following command:

```bash
pdfmonkey snippet watch
```

This will start watching the `code.liquid` file in the **current folder** and sync automatically when changes are detected. The CLI uses the metadata stored in the `.pdfmonkey.json` file to identify the snippet.

To monitor a different folder, simply pass the path as the first argument:

```bash
pdfmonkey snippet watch <path>
```

If for some reason the folder doesn't contain metadata or you want to use a different snippet ID, you can specify it using the `-s` option:

```bash
pdfmonkey snippet watch [path] -s <snippet-id>
```

## Watch Multiple Resources

The CLI allows you to watch multiple resources (one template and multiple snippets) simultaneously with a single command:

```bash
pdfmonkey watch
```

This will prompt you to interactively select the folders you want to watch.

You can also directly specify multiple paths:

```bash
pdfmonkey watch path/to/template path/to/snippet
```

When watching multiple resources, the command will automatically detect if each folder contains a template or a snippet based on the metadata. Note that **only one template can be watched at a time**, but you can watch multiple snippets alongside it.

This combined watch command supports the same options as the `template watch` command:

```bash
pdfmonkey watch -D -o -p 2083 -l 2084
```

## Metadata

The CLI stores metadata in a `.pdfmonkey.json` file within each resource folder. This file contains the resource type and ID, allowing commands to run without explicitly specifying IDs. This metadata is automatically created when initializing resources and used by the watch commands.

The `.pdfmonkey.json` file looks like this:

```json
{
  "type": "template",
  "id": "123e4567-e89b-12d3-a456-426614174000"
}
```

## Configuration

Here is a summary of the environment variables that can be set to customize the behavior of the CLI:

- `PDFMONKEY_API_KEY`: The API key to use for authentication.
- `DIFF`: The diff tool to use.
- `PAGER`: The pager to use when displaying diffs.
- `PORT`: The port to run the preview server on.
- `LIVE_RELOAD_PORT`: The port to run the live-reload server on.


---

# Our Engines

Source: https://pdfmonkey.io/docs/code-templates/our-engines.md
When you generate a Document, PDFMonkey uses a Chrome-based web engine to render your HTML/CSS content and then "prints" it to PDF. The current engine is **v5**, based on **Chrome&nbsp;133** — you can do anything that works in a modern browser (except animations, of course).

## Engine versions

PDFMonkey has shipped several engine versions over the years. Each version brings a newer Chrome release with broader CSS and JavaScript support. Templates stay on the engine version they were created with — you can check and change your engine version in your template's Settings tab.

| Engine | Chrome version | Status | Key capabilities |
| ------ | -------------- | ------ | ---------------- |
| **v5** | Chrome&nbsp;133 | **Current** | Latest CSS/JS features, image generation, improved rendering accuracy |
| **v4** | Chrome&nbsp;123 | Available | `:has()` pseudo-class, container queries, `text-wrap: balance`, import maps, emoji opt-in |
| **v3** | Chromium&nbsp;86 | Legacy | ES2020, Flexbox, Grid, custom properties |
| **v2** | Chromium&nbsp;79 | Legacy | Basic modern CSS and JS support |

> [!TIP]
> **Upgrade to v5**
>
> for the best rendering and the widest feature support. New templates are created on v5 by default.


### v5 — Chrome&nbsp;133 (current)

Engine v5 is the latest and most capable engine. Based on Chrome&nbsp;133, it supports virtually all modern CSS and JavaScript features. It also introduced **image generation** (PNG/JPEG output alongside PDF) and improved rendering accuracy for page sizes and margins.

### v4 — Chrome&nbsp;123

Engine v4 was a major upgrade that brought several highly requested CSS features:

- **`:has()` pseudo-class** — style parent elements based on their children
- **Container queries** — responsive layouts based on container size rather than viewport
- **`text-wrap: balance`** — balanced text wrapping for headings
- **Import maps** — use ES module imports without a bundler
- **Emoji opt-in** — native emoji rendering support

### v3 — Chromium&nbsp;86 (legacy)

Engine v3 provides full support for ES2020 JavaScript, Flexbox, CSS Grid, and custom properties. If it renders in Chrome&nbsp;86, it renders on v3.

### v2 — Chromium&nbsp;79 (legacy)

Engine v2 is the oldest supported engine. It covers basic modern CSS and JavaScript but lacks many features available in newer engines.

## Generation time limits

Starting with engine v4, PDFMonkey introduced **extended generation times** that give your templates more time to render complex documents. The maximum generation time depends on your plan:

| Plan | Max generation time |
| ---- | ------------------- |
| Free | 30 seconds |
| Pro | 2 minutes |
| Pro+ | 3 minutes |
| Premium | 5 minutes |

> [!WARNING]
> Templates on engine v2 or v3 are limited to **30 seconds** regardless of plan. Upgrade to v4 or v5 to benefit from extended generation times.



## FAQ

**What rendering engine does PDFMonkey use?**

PDFMonkey uses a Chrome-based engine to render HTML/CSS to PDF. The current version is v5, based on Chrome 133, which supports virtually all modern CSS and JavaScript features.

**How do I change the engine version on my PDFMonkey template?**

Open your template and go to the Settings tab. The engine version is shown there and can be changed. Templates stay on the engine they were created with unless you manually upgrade.

**What is the maximum PDF generation time in PDFMonkey?**

It depends on your plan and engine version. On engine v4 or v5, limits range from 30 seconds (Free) to 5 minutes (Premium). Templates on engine v2 or v3 are capped at 30 seconds regardless of plan.


---

# Professional PDF Template Creation Service

Source: https://pdfmonkey.io/docs/code-templates/template-authoring-offer.md
Don't have the time or expertise to build your own templates? PDFMonkey offers a **Template Authoring** service: our team designs and codes production-ready PDF templates directly in your account.

## Who is this for?

Template Authoring is a good fit if you:

- Have a finished PDF design but lack the HTML/CSS skills to implement it
- Need a complex layout (multi-page tables, conditional sections, charts) and want it done right the first time
- Are under time pressure and prefer to delegate template work to people who know the platform inside out

## Pricing

| | Cost |
| --- | --- |
| **Base price** per template | From 1,000 EUR |
| **Rush fee** (deadline under 2 months) | +500 EUR |

The base price covers a standard template with typical dynamic elements. Final pricing may be higher for complex designs — charts, heavy conditional logic, or unusually large page counts — and we will always confirm the quote before starting.

All prices are listed excluding taxes. Depending on your location, VAT or other applicable taxes may be added.

> [!NOTE]
> **Why the rush fee?**
>
> PDFMonkey is a two-person team. One person handles all template work on top of platform development, so our bandwidth is genuinely limited. The rush fee reflects the schedule disruption a tight deadline creates.


## How it works

1. **Send us your materials.** Email your PDF design along with all required assets: images, fonts, license keys, and any custom libraries. If you have sample documents showing different data scenarios, include those too — they speed things up considerably.

2. **Describe the dynamic behavior.** Tell us which parts of the document change based on data: conditional paragraphs, repeated rows, calculated fields, etc. The more precise the rules, the fewer back-and-forth rounds we need.

3. **We build the template.** We create the template directly in your PDFMonkey account and keep you updated throughout development.

4. **You review and test.** Once the template is ready, test it by editing its [test data](https://pdfmonkey.io/docs/code-templates/defining-dynamic-data.md#defining-test-data) with your own values. Share any feedback and we will adjust the code until you are satisfied.

## Updates after delivery

Need changes down the road? Contact us with a description of what you need and we will send you a quote based on the scope of the modification.


## FAQ

**How much does PDFMonkey’s template authoring service cost?**

The base price starts at 1,000 EUR per template. A rush fee of 500 EUR applies for deadlines under two months. Final pricing may be higher for complex designs involving charts, heavy conditional logic, or large page counts.

**What do I need to provide for PDFMonkey’s template creation service?**

Send your PDF design along with all required assets: images, fonts, license keys, and any custom libraries. Include sample documents showing different data scenarios and describe which parts of the document are dynamic (conditional paragraphs, repeated rows, calculated fields).

**Can I request changes to my template after delivery?**

Yes. Contact the PDFMonkey team with a description of the changes you need and they will send you a quote based on the scope of the modification.



---

# Your First Template

Source: https://pdfmonkey.io/docs/builder-templates/your-first-template.md
The visual builder lets you create PDF templates by dragging and dropping blocks onto a canvas — no HTML or CSS required. In this tutorial, you will build a simple document template from scratch, add text and images, connect test data, and generate your first PDF.

## Opening the builder

From your PDFMonkey dashboard, click **New Template**. Give your template a name, then select **Builder** as the template mode. Click **Create** to open the visual editor.

## Getting to know the interface

The builder has three main areas:

![The builder interface showing the three-panel layout](https://pdfmonkey.io/docs/img/builder-overview.webp)

- **Left panel** — switches between the **Elements** tree (showing your template structure) and the **Blocks** panel (where you pick new blocks to add).
- **Center canvas** — a live preview of your template. What you see here is what your PDF will look like.
- **Right panel** — switches between **Styles** (visual properties like colors, spacing, and fonts) and **Settings** (block-specific configuration and logic).

The toolbar at the top of the canvas gives you access to test data, custom CSS and JavaScript editors, external assets, and keyboard shortcuts.

## Adding your first blocks

Every new template starts with a **Page** block already in place. The Page block represents a single page of your PDF — it controls paper size, orientation, and margins.

To add content, switch to the **Blocks** panel in the left sidebar. Blocks are organized into three categories: **Layout**, **Content**, and **Extra**.

![The Blocks panel showing the three block categories](https://pdfmonkey.io/docs/img/blocks-panel.webp)

Start by adding a **Container** block inside the Page. A Container groups other blocks together and controls their layout (vertical stack, horizontal row, or grid). Drag it from the Blocks panel onto the canvas, or click it to add it inside the currently selected element.

Next, add a **Heading** block inside the Container. Select the Heading in the canvas, then look at the right panel under **Settings** to pick the heading level (h1 through h6). Click **Edit Heading Content** to type your heading text.

Add a **Text** block below the Heading. Text blocks support rich formatting — bold, italic, lists, and links.

> [!TIP]
> You can reorder blocks by dragging them in the **Elements** tree on the left panel. This is often easier than dragging on the canvas itself.


## Editing text content

Select a Text block and open the **Settings** tab in the right panel. Click **Edit Text Content** to open the rich text editor.

![The rich text editor modal for editing text content](https://pdfmonkey.io/docs/img/text-editor.webp)

The editor gives you a formatting toolbar with options for bold, italic, underline, strikethrough, bullet lists, numbered lists, and links. Type your content, apply formatting as needed, then close the modal. Your changes appear immediately on the canvas.

Heading blocks work the same way — click **Edit Heading Content** in Settings to open the editor.

## Adding an image

Add an **Image** block from the Content category in the Blocks panel. Select it, then open the **Settings** tab to configure the image source.

![Image block settings showing the source URL input](https://pdfmonkey.io/docs/img/image-settings.webp)

You have three options for setting the image source:

- **Static URL** — paste a direct link to an image hosted online.
- **Upload** — click the upload button to select a file from your computer. The image is converted to a data URI and embedded directly in the template.
- **Dynamic binding** — click the variable browser button to bind the source to a field in your test data (for example, `company.logo`). This lets each generated document use a different image.

> [!NOTE]
> For the best PDF rendering performance, use optimized images. Large, high-resolution files increase generation time.


## Using test data

Most templates include dynamic content — data that changes for each generated document. The builder lets you define test data so you can preview how your template looks with real values.

Click the **Edit Test Data** button in the toolbar above the canvas. This opens a JSON editor where you define sample data.

![The test data editor with a sample JSON payload](https://pdfmonkey.io/docs/img/test-data-editor.webp)

Enter a JSON object with the fields your template needs. For example:

```json
{
  "name": "Jane Smith",
  "company": "Acme Corp",
  "items": [
    { "description": "Consulting", "amount": 1500 },
    { "description": "Development", "amount": 3000 }
  ]
}
```

Once you save the test data, the variable browser throughout the builder shows your available fields. You can bind text content, image sources, visibility conditions, and loops to these data paths. Changes to the test data update the canvas preview immediately.

> [!TIP]
> The test data editor supports JSON comments (lines starting with `//`). Use them to document what each field represents — they are stripped during parsing and do not affect your template.


## Saving your template

Press **Ctrl+S** (or **Cmd+S** on Mac) to save your template. The builder sends the save request to the dashboard, where your template is stored.

Remember to **Publish** your template from the dashboard before generating documents. Unpublished templates cannot be used for document generation.

## Generating a document

Once your template is published, you can generate documents in three ways:

- [Using the Dashboard](https://pdfmonkey.io/docs/generating-documents/using-the-dashboard.md) — create documents manually with a form.
- [Using the API](https://pdfmonkey.io/docs/generating-documents/api-pdf-generation.md) — generate documents programmatically from your application.
- [Using an Integration](https://pdfmonkey.io/docs/generating-documents/using-an-integration.md) — connect with Zapier, Make, n8n, and other no-code platforms.

In every case you send a JSON payload matching your test data structure, and PDFMonkey produces a PDF.

## Next steps

Now that you have built your first template, explore the other builder features:

- [Available Blocks](https://pdfmonkey.io/docs/builder-templates/available-blocks.md) — learn about every block type and its configuration options.
- [Images](https://pdfmonkey.io/docs/builder-templates/images.md) — go deeper on static, uploaded, and dynamic images.
- [Conditions and Loops](https://pdfmonkey.io/docs/builder-templates/conditions-and-loops.md) — make content conditional or repeat it for each item in a collection.
- [Test Data](https://pdfmonkey.io/docs/builder-templates/test-data.md) — advanced test data techniques and the variable browser.


---

# Available Blocks

Source: https://pdfmonkey.io/docs/builder-templates/available-blocks.md
The builder provides blocks you drag onto the canvas to construct your template. Blocks are organized into three categories: **Layout** for structural elements, **Content** for text, images, and data, and **Extra** for specialized components.

![The Blocks panel showing Layout, Content, and Extra categories](https://pdfmonkey.io/docs/img/blocks-panel-categories.webp)

## Layout

Layout blocks define the structure of your template. They act as containers that hold other blocks.

### Page

The Page block is the root element of every template — it represents a single PDF page. When you create a new template, a Page block is added automatically.

**Key settings:**
- **Paper format** — A0, A1, A2, A3, A4, A5, A6, Letter, and Custom.
- **Orientation** — Portrait or landscape.
- **Background color** — set a page background via the Styles panel.
- **Padding** — control the inner spacing around the page edges through the Spacing section of the Styles panel.

Most other blocks can be placed inside a Page. You typically have one Page block per template, but you can add more for multi-page layouts.

### Container

A Container is a flexible grouping element — think of it as a `<div>` that holds other blocks together. By default, a Container stacks its children vertically (flex column).

**Key settings:**
- **Display** — block or flex. Flex enables powerful layout capabilities like direction, alignment, and gap control.
- **Layout direction** — vertical (column), horizontal (row), or grid. Configure in the Layout section of the Styles panel.
- **Gap** — spacing between child elements.
- **Alignment** — control how children are positioned within the container (start, center, end, stretch, space-between).

> [!TIP]
> Use Containers to group related content. For example, wrap a heading and a paragraph in a Container, then use the Logic panel to show or hide the entire group based on a condition.


## Content

Content blocks display the actual information in your template — text, headings, images, raw HTML, and tables.

### Text

The Text block holds rich text content. Select it and click **Edit Text Content** in the Settings panel to open the rich text editor.

**Formatting options:**
- Bold, italic, underline, strikethrough
- Bullet lists and numbered lists
- Links
- Font size, color, and alignment (via the Styles panel)

Text blocks do not accept child blocks.

### Heading

The Heading block renders a heading element (h1 through h6). It works like the Text block but is styled as a heading by default.

**Key settings:**
- **Heading level** — select h1, h2, h3, h4, h5, or h6 in the Settings panel.
- **Edit Heading Content** — opens the same rich text editor as the Text block.

Use heading levels to create a visual hierarchy in your document, not just for font size. Screen readers and accessibility tools rely on heading structure.

### Image

The Image block displays a picture in your template. You configure its source in the Settings panel.

**Source options:**
- **Static URL** — paste a direct link to an image.
- **Upload** — select a file from your computer. It is converted to a data URI and embedded in the template.
- **Dynamic binding** — bind the source to a field in your test data (for example, `user.avatar`) so each generated document can show a different image.

For more details, see [Images](https://pdfmonkey.io/docs/builder-templates/images.md).

### HTML

The HTML block lets you insert raw HTML content using a code editor. This is useful when you need markup the visual blocks cannot produce, such as custom SVGs or complex table layouts.

Click **Edit HTML Content** in the Settings panel to open the code editor and write your markup.

> [!CAUTION]
> **Scripts do not run in the editor by default**
>
> `&lt;script&gt;` tags inside HTML blocks only execute during PDF generation, not in the editor preview. If your HTML block relies on JavaScript to render its content, enable the **Run scripts in editor** toggle in the Settings panel, otherwise the block will appear blank in the preview.


#### Styling

HTML blocks bypass the builder's visual styling system. Content inside an HTML block must be styled directly using inline styles, [Custom CSS](https://pdfmonkey.io/docs/builder-templates/custom-css.md), or Tailwind utility classes — Tailwind is loaded globally and available throughout the entire template, including inside HTML blocks.

### Table

The Table block creates a data table with auto-generated structure. When you add one, the builder creates the full hierarchy — `thead`, `tbody`, rows, header cells, and data cells — so you start with a ready-to-use table. Manage rows and columns in the Settings panel, style individual cells in the Styles panel, and use the repetition setting to generate rows dynamically from your data.

For more details, see [Tables](https://pdfmonkey.io/docs/builder-templates/tables.md).

## Extra

The Extra category contains specialized blocks for specific use cases.

### QR Code

The QR Code block generates a QR code image directly in your template.

**Key settings:**
- **Content** — the data encoded in the QR code. Can be a static value (like a URL) or bound to a data variable.
- **Size** — the width and height of the QR code in pixels.
- **Foreground/background colors** — customize the colors of the QR code dots and background.
- **Reliability level** — error correction level (L, M, Q, or H). Higher levels make the QR code more resilient to damage but increase its density.
- **Dot style** — square, dots, rounded, extra-rounded, classy, or classy-rounded.
- **Corner style** — square, dot, or extra-rounded.
- **Logo** — an optional image placed in the center of the QR code. Can be a static URL or a data-bound value.

For more details, see [QR Codes](https://pdfmonkey.io/docs/builder-templates/qr-codes.md).

## Common settings for all blocks

Every block shares a few settings available in the Settings panel:

- **Element info** — shows the block type and the HTML tag it renders as.
- **Logic panel** — configure conditional display or repetition for any block except the root Document element. See [Conditions and Loops](https://pdfmonkey.io/docs/builder-templates/conditions-and-loops.md) for details.

The Styles panel is also available for every block, giving you control over layout, spacing, typography, borders, backgrounds, and positioning. For advanced style techniques, see [Custom CSS](https://pdfmonkey.io/docs/builder-templates/custom-css.md) and [Situational Styling](https://pdfmonkey.io/docs/builder-templates/situational-styling.md).

## Next steps

- Follow the [Your First Template](https://pdfmonkey.io/docs/builder-templates/your-first-template.md) tutorial to build a complete template from scratch.
- Learn about [Conditions and Loops](https://pdfmonkey.io/docs/builder-templates/conditions-and-loops.md) to make your templates dynamic.
- Explore [Custom CSS](https://pdfmonkey.io/docs/builder-templates/custom-css.md) and [Custom JS](https://pdfmonkey.io/docs/builder-templates/custom-js.md) for advanced customization.


## FAQ

**What block types are available in the PDFMonkey visual builder?**

The builder provides blocks in three categories: Layout (Page and Container), Content (Text, Heading, Image, HTML, and Table), and Extra (QR Code). Each block can be dragged onto the canvas and configured via the Settings and Styles panels.

**What is a Container block in PDFMonkey?**

A Container is a flexible grouping element that holds other blocks together. It supports block or flex display, vertical/horizontal/grid layout directions, gap spacing, and alignment controls. Use Containers to group related content and apply logic like conditional visibility or repetition.

**Can I write raw HTML in a PDFMonkey builder template?**

Yes. The HTML block lets you insert raw HTML using a code editor. It’s useful for custom SVGs, complex layouts, or markup the visual blocks can’t produce. Style the content with inline styles, Custom CSS, or Tailwind utility classes.


---

# Images for Builder Templates

Source: https://pdfmonkey.io/docs/builder-templates/images.md
Images are one of the most common elements in PDF templates — logos, product photos, avatars, charts. The builder gives you three ways to set an image source: paste a URL, upload a file, or bind the source to a variable in your document data.

## Adding an image block

Open the **Blocks** panel on the left side of the builder and look under the **Content** category. Drag an **Image** block onto the canvas or click it to add it inside the currently selected container.

![The Image block selected within the blocks list](https://pdfmonkey.io/docs/img/adding-an-image-block.webp)

When you select the Image block, the right panel switches to the **Settings** tab where you'll find the **Image Settings** section with a URL input field.

## Setting the image source

The Image Settings section shows a URL input field with two buttons on the right: a **variable browser** button (curly braces icon) and an **upload** button (upload icon).

![The Image Settings panel showing the URL input with variable browser and upload buttons](https://pdfmonkey.io/docs/img/image-settings-panel.webp)

### Static URL

Type or paste a full URL (starting with `https://`) directly into the input field and press Enter or click away. The image loads immediately in the canvas preview.

```text
https://example.com/logo.png
```

> [!WARNING]
> **Paid accounts only**
>
> Including images based on their URL is only possible on a paid account or during the [trial period](https://pdfmonkey.io/docs/getting-started/the-30-day-trial.md). Documents including external images will fail on a free account. See [External Resources](https://pdfmonkey.io/docs/getting-started/external-resources.md) for the full list.


### Upload a file

Click the **upload button** (upload icon) to open a file picker. Select an image file from your computer. The builder converts it to a data URI and embeds it directly in the template.

> [!WARNING]
> **Watch the file size**
>
> Uploaded images are embedded as data URIs inside the template. Large images:
&gt; 
&gt; - increase the template size,
&gt; - slow down PDF generation,
&gt; - make saving the template noticeably slower since the full content is sent every time.
&gt; 
&gt; Keep uploaded images under 200 KB when possible. For larger images, host them on a server and use a static URL instead.


After uploading, the input is replaced by a thumbnail preview of the image with buttons to replace or remove it.

### Dynamic binding

Click the **variable browser** button (curly braces icon) to open a dropdown listing all available data paths from your test data. Select a path that contains an image URL — for example, `company.logo` or `user.avatar_url`.

![The variable browser dropdown showing available data paths](https://pdfmonkey.io/docs/img/image-variable-browser.webp)

You can also type a variable path directly into the input field. The builder automatically detects that a value like `company.logo` is a data binding (not a URL) and treats it accordingly.

> [!TIP]
> The variable browser only shows paths that exist in your current test data. If you don&#39;t see the path you need, open the test data editor and add the relevant field with a sample image URL.


## Background images

Any element in the builder — not just Image blocks — can have a background image. Select an element, switch to the **Styles** tab in the right panel, and expand the **Background** section.

The Background section includes:

| Setting | What it controls |
|---|---|
| Background Color | Solid color behind the element |
| Background Image | An image URL or data binding for the background |
| Background Repeat | Whether the image tiles (`repeat`, `no-repeat`, etc.) |
| Background Size | How the image scales (`cover`, `contain`, or a specific size) |
| Background Position | Where the image anchors (`center`, `top left`, etc.) |

Use background images when you need an image behind other content — for example, a watermark, a decorative header, or a full-page background pattern.

## Tips for working with images

- **Keep file sizes reasonable.** Large images slow down PDF generation. Resize and compress images before using them.
- **Use URLs for images that change.** If the image differs per document (a customer logo, a product photo), use a dynamic binding so each generated PDF pulls the correct image from your data.
- **Use uploads for images that stay the same.** If the image is always identical across documents (your company logo at a fixed size), uploading keeps things simple and avoids external dependencies.
- **Check CORS for external URLs.** Images loaded from external servers must allow cross-origin requests. If an image fails to render in the generated PDF, check whether the hosting server supports CORS.


## FAQ

**How do I add an image to a PDFMonkey builder template?**

Drag an Image block from the Blocks panel onto the canvas. In the Settings tab, you can paste a static URL, upload a file from your computer, or bind the source to a variable in your document data for dynamic images.

**Can I use dynamic images that change per document in PDFMonkey?**

Yes. Click the variable browser button (curly braces icon) in the Image Settings panel and select a data path like company.logo or user.avatar_url. Each generated document will pull its image from the payload data you provide.

**What is the recommended file size for uploaded images in PDFMonkey?**

Keep uploaded images under 200 KB. Uploaded files are embedded as data URIs inside the template, so large images increase template size and slow down both saving and PDF generation. For larger images, host them on a server and use a URL instead.

**How do I add a background image to an element in the PDFMonkey builder?**

Select any element, switch to the Styles tab, and expand the Background section. Set a Background Image URL or data binding, then configure repeat, size, and position settings to control how the image displays behind the element’s content.


---

# Tables

Source: https://pdfmonkey.io/docs/builder-templates/tables.md
The Table block creates a full semantic HTML table automatically — when you add one, the builder generates the complete structure so you start with a ready-to-use table.

## Table structure

When you add a Table block, the builder creates the entire hierarchy: a `table` element containing `thead` and `tbody`, each with rows (`tr`), header cells (`th`), and data cells (`td`). These sub-elements don't appear in the Blocks panel — they only show up in the Elements tree when you expand the Table block.

![A Table block showing the auto-generated structure in the Elements tree](https://pdfmonkey.io/docs/img/table-block-structure.webp)

## Managing rows and columns

Use the **Settings** panel to add or remove rows (in `thead` or `tbody` separately) and columns (which affects all rows at once).

Select individual `th` or `td` cells in the Elements tree and edit their text content like a regular Text block.

## Border modes

The Table block supports two border rendering modes:

- **Border-collapse** — adjacent cell borders merge into a single shared border.
- **Border-separate** — each cell keeps its own independent border, and you can control the spacing between them.

Toggle between the two in the **Styles** panel.

## Styling cells

Select any cell (`th` or `td`) in the Elements tree, then switch to the **Styles** panel to adjust padding, background color, text alignment, borders, and typography.

> [!TIP]
> Use the copy/paste styles feature (right-click context menu or keyboard shortcuts) to apply the same styling to multiple cells quickly. This saves a lot of time when you need consistent formatting across an entire row or column.


## Dynamic rows

You can generate table rows from your data using the repetition setting. Select the `tr` element inside `tbody`, open the Logic panel, and configure repetition to iterate over a collection from your data.

For example, if your data contains an `items` array, set the repetition to loop over `items`. Each cell in that row can then reference `item.name`, `item.quantity`, `item.price`, and so on.

See [Conditions and Loops](https://pdfmonkey.io/docs/builder-templates/conditions-and-loops.md) for full details on repetition bindings.

## Even/odd row styling

For zebra-striped tables, use situational styling to apply different backgrounds to odd and even rows. This makes large tables easier to scan.

See [Situational Styling](https://pdfmonkey.io/docs/builder-templates/situational-styling.md) for setup instructions.


## FAQ

**How do I add a table to a PDFMonkey builder template?**

Drag a Table block from the Blocks panel onto the canvas. The builder automatically creates the full structure—thead, tbody, rows, header cells, and data cells—so you start with a ready-to-use table.

**How do I generate dynamic table rows from data in PDFMonkey?**

Select the tr element inside tbody, open the Logic panel, and configure Repetition to iterate over a collection from your data. Each cell in that row can then reference item properties like item.name or item.price.

**Can I style individual table cells in the PDFMonkey builder?**

Yes. Select any th or td cell in the Elements tree, then use the Styles panel to adjust padding, background color, text alignment, borders, and typography. You can also copy and paste styles between cells.


---

# Conditions and Loops for Builder Templates

Source: https://pdfmonkey.io/docs/builder-templates/conditions-and-loops.md
The builder's Logic panel lets you control when elements appear and how they repeat. You can make any element conditional — visible only when a data condition is met — or repeat it once for each item in a collection. These two features cover the most common dynamic content patterns: showing or hiding sections based on context, and generating rows from a list of items.

## The Logic panel

Select any element in the canvas (except the document root), then switch to the **Settings** tab in the right panel. The **Logic** section appears below the Element Info section, with two toggles: **Visibility Condition** and **Repetition**.

A small indigo dot appears next to the "Logic" heading when either feature is active on the selected element.

## Visibility conditions

Toggle on **Visibility Condition** to make an element appear only when a condition is true. An input field appears where you enter a JavaScript expression evaluated against your document's test data.

![The Logic panel with a visibility condition active, showing the green "visible" status](https://pdfmonkey.io/docs/img/logic-panel-visibility-condition.webp)

### Writing conditions

The condition is a JavaScript expression that has access to your test data. Some examples:

| Condition | What it does |
|---|---|
| `customer.isPremium` | Shows the element when the customer is premium |
| `items.length > 0` | Shows the element when the items array is not empty |
| `order.status === 'paid'` | Shows the element when the order status is "paid" |
| `total >= 1000` | Shows the element when the total is 1,000 or more |

### Live evaluation

The Logic panel evaluates your condition against the current test data in real time and shows the result:

- **Green ("Element is currently visible")** — the condition evaluates to a truthy value with your current test data, so the element appears in the preview.
- **Red ("Element is currently hidden")** — the condition evaluates to a falsy value, so the element is hidden in the preview.

![The Logic panel showing the red "hidden" status when the condition evaluates to false](https://pdfmonkey.io/docs/img/logic-panel-hidden-status.webp)

If the condition contains a syntax error, a red error banner appears at the bottom of the builder.

A link to **Edit test data** appears below the status indicator, letting you quickly adjust your test data to try different scenarios.

## Repetition

Toggle on **Repetition** to repeat an element once for each item in a collection from your test data. Two input fields appear:

- **Collection** — the path to an array in your test data (for example, `invoice.products` or `users`)
- **Item name** — the variable name for the current item in the loop (auto-suggested by singularizing the collection name)

![The Logic panel with Repetition active, showing the collection and item fields with available variables](https://pdfmonkey.io/docs/img/logic-panel-repetition.webp)

### How it works

When you enter a collection path like `lineItems`, the builder automatically suggests an item name of `lineItem` (the singular form). You can change this to any name you prefer.

The panel then shows a summary of what the loop does and lists the available variables:

| Variable | Description |
|---|---|
| The item variable (e.g., `lineItem`) | The current item from the collection |
| The index variable (e.g., `lineItemIndex`) | The zero-based position of the current item |

The panel also shows helper expressions you can copy for common checks:

- **First item check:** `lineItemIndex === 0`
- **Last item check:** `lineItemIndex === lineItems.length - 1`

### Using loop variables in child elements

Child elements of a repeated element can reference the item and index variables. For example, if you repeat a container over `lineItems` with the item name `lineItem`, a Text block inside that container can display `lineItem.name` or `lineItem.price` using the variable browser.

## Visibility and repetition are mutually exclusive

You cannot enable both Visibility Condition and Repetition on the same element. The builder enforces this — when one toggle is active, the other is disabled. This is because combining both on a single HTML element produces ambiguous behavior.

> [!TIP]
> **Workaround:**
>
> If you need to repeat elements and also conditionally show some of them, nest two elements. Put a Container with **Repetition** enabled, and inside it place a child element with a **Visibility Condition**. The container repeats for each item, and the child inside it appears or hides based on the condition.


## Combining with situational styling

Repeated elements work well with [situational styling](https://pdfmonkey.io/docs/builder-templates/situational-styling.md). Once an element repeats over a collection, you can apply different styles for odd and even items, highlight the first or last item, or show a fallback when the collection is empty. See the [Situational Styling](https://pdfmonkey.io/docs/builder-templates/situational-styling.md) page for details.


## FAQ

**How do I conditionally show or hide an element in PDFMonkey’s builder?**

Select the element, open the Settings tab, and toggle on Visibility Condition in the Logic section. Enter a JavaScript expression evaluated against your document data—for example, “customer.isPremium” or “items.length > 0”. The element only appears when the condition is truthy.

**How do I loop over a list of items in a PDFMonkey builder template?**

Select the element you want to repeat, open the Logic panel, and toggle on Repetition. Enter the path to an array in your data (e.g. “invoice.products”) as the Collection and choose an Item name. The builder repeats the element once for each item in the array.

**Can I use both visibility conditions and repetition on the same element?**

No. The builder only allows one at a time on a given element. To repeat elements and conditionally show some of them, nest a child element with a Visibility Condition inside a parent Container that has Repetition enabled.


---

# Situational Styling

Source: https://pdfmonkey.io/docs/builder-templates/situational-styling.md
Situational styling lets you change how an element looks depending on its position among its siblings. You can set different background colors for odd and even children, highlight the first or last item, or show a fallback message when a collection is empty — all without writing any code.

## The situation selector

Every element has a **Situation** dropdown at the top of the **Styles** panel. By default it's set to "Default", meaning the styles you set apply in all contexts.

![The Situation dropdown in the Styles panel showing all six options](https://pdfmonkey.io/docs/img/situation-selector-dropdown.webp)

Click the dropdown to choose a different situation. Any styles you set while a non-default situation is selected apply only when that condition matches.

## Available situations

The builder provides six situations:

| Situation | When styles apply |
|---|---|
| **Default** | Always — these are the base styles for the element |
| **When odd** | When the element is at an odd position (1st, 3rd, 5th...) among its siblings |
| **When even** | When the element is at an even position (2nd, 4th, 6th...) among its siblings |
| **When first** | Only for the first child element among its siblings |
| **When last** | Only for the last child element among its siblings |
| **When empty** | When the element has no visible children |

## Setting situational styles

1. Select an element in the canvas.
2. Open the **Styles** tab in the right panel.
3. Choose a situation from the **Situation** dropdown (for example, "When even").
4. Set the styles you want for that situation — background color, text color, borders, or any other style property.
5. Switch back to "Default" to continue editing the base styles.

The styles you set under a non-default situation act as overrides. They replace the corresponding default styles only when the condition matches. Properties you don't set in a situational context fall back to their default values.

## The override indicator

When an element has styles set for any non-default situation, a small **indigo dot** appears next to the Situation dropdown. This visual indicator helps you spot which elements have situational overrides without switching through each situation manually.

Hovering over the dot shows a tooltip listing which situations have overrides defined.

![Hovering over the override indicator to reveal which situations have overrides](https://pdfmonkey.io/docs/img/situation-selector-hover.webp)

## Common use cases

### Alternating row colors

The most common use of situational styling is zebra-striping rows in a repeated list:

1. Create a Container and enable [Repetition](https://pdfmonkey.io/docs/builder-templates/conditions-and-loops.md) on it (for example, over `invoice.items`).
2. Set the **Default** background to white.
3. Switch to **When even** and set the background to a light grey.

Each generated row alternates between white and grey automatically.

### Highlighting the last item

To add a bottom border only to the last item in a list:

1. Select the repeated element.
2. Switch to **When last**.
3. Add a bottom border.

### Empty collection fallback

To show a message when a collection has no items:

1. Create a Container with Repetition enabled over the collection.
2. Inside it, add the content that should repeat.
3. Select the repeated Container itself.
4. Switch to **When empty**.
5. Set styles that make the empty-state content visible (for example, set a minimum height and center-align text).

> [!TIP]
> &#34;When empty&#34; is particularly useful combined with a child Text block that says something like &#34;No items to display.&#34; The parent container renders with empty-state styles, and the child text provides the message.


## Combining with conditions and loops

Situational styling works hand-in-hand with the [Conditions and Loops](https://pdfmonkey.io/docs/builder-templates/conditions-and-loops.md) features. A typical pattern is:

1. Set up **Repetition** on a container to loop over a data collection.
2. Apply **situational styles** on the repeated element or its children for visual variation.
3. Optionally add **Visibility Conditions** on child elements inside the loop to show or hide specific content per item.

This combination covers most dynamic layout needs without writing any custom CSS.


## FAQ

**How do I create zebra-striped rows in a PDFMonkey builder template?**

Enable Repetition on a Container, set the Default background to white, then switch the Situation dropdown to “When even” and set that background to a light grey. Each repeated row automatically alternates colors.

**What situational styles are available in the PDFMonkey builder?**

The builder provides six situations: Default (always), When odd, When even, When first, When last, and When empty. Each lets you override styles based on the element’s position among its siblings or whether it has visible children.

**How do I show a fallback message when a repeated collection is empty?**

Select the Container with Repetition enabled, switch the Situation dropdown to “When empty,” and set styles that make the empty-state content visible. Add a child Text block inside with your fallback message such as “No items to display.”


---

# QR Codes for Builder Templates

Source: https://pdfmonkey.io/docs/builder-templates/qr-codes.md
The builder includes a dedicated QR Code block for embedding QR codes directly in your templates. You can encode static text or URLs, bind the content to a dynamic data variable, customize colors and dot styles, and even add a centered logo.

## Adding a QR Code block

QR Code is in the **Extra** category of the Blocks panel. Drag it onto the canvas or click it to add it inside the currently selected container.

![A QR Code block displayed on the canvas](https://pdfmonkey.io/docs/img/qr-code-block-canvas.webp)

Once added, the QR code renders immediately in the canvas using its default settings. Select the block to configure it in the right panel.

## QR Code settings

Select a QR Code block and open the **Settings** tab in the right panel to access all configuration options.

### Content

The **Content** field defines the text or URL encoded in the QR code. You can type a static value (such as `https://example.com`) or bind it to a data variable from your payload.

To use dynamic content, click the variable browser button next to the field and select a property from your test data — for example, `invoice.paymentUrl`. The QR code updates in real time as you change the test data.

### Size

The **Size** setting controls the width and height of the QR code in pixels. Both dimensions are always equal since QR codes are square.

### Colors

- **Foreground color** — the color of the QR code dots (default: black).
- **Background color** — the color behind the dots (default: white).

You can use any valid color value. High contrast between foreground and background is important for scannability.

> [!WARNING]
> Avoid low-contrast color combinations. Most QR readers expect dark dots on a light background. Inverting the colors (light on dark) may cause scanning failures on some devices.


### Reliability level

The reliability level sets the **error correction** capacity of the QR code:

| Level | Name | Recovery capacity |
|-------|------|-------------------|
| **L** | Low | ~7% |
| **M** | Medium | ~15% |
| **Q** | Quartile | ~25% |
| **H** | High | ~30% |

Higher levels make the code more resilient to damage or partial obstruction, but produce denser (more complex) patterns. If you plan to add a logo in the center of the QR code, use **Q** or **H** so the code remains scannable even though the logo covers part of it.

### Dot style

The dot style changes the shape of individual modules in the QR code:

- **Square** — standard rectangular modules (default)
- **Dots** — circular dots
- **Rounded** — rounded rectangles
- **Extra-rounded** — more pronounced rounding
- **Classy** — stylized square variant
- **Classy-rounded** — stylized with rounded corners

### Corner style

The corner style affects the three large positioning squares at the corners of the QR code:

- **Square** — standard square corners (default)
- **Dot** — circular corners
- **Extra-rounded** — rounded corners

Mixing dot and corner styles lets you match the QR code to your brand aesthetic while keeping it scannable.

### Logo URL

The **Logo URL** field lets you place an image in the center of the QR code. Enter a direct URL to a PNG or SVG image, or bind the field to a data variable for dynamic logos.

> [!TIP]
> When using a logo, set the reliability level to **Q** or **H**. The logo physically covers QR modules, and higher error correction ensures the code remains readable despite the obstruction.


## Dynamic QR codes

For documents generated with different data, bind both the **Content** and **Logo URL** fields to variables from your payload. Each generated document will produce a unique QR code based on its data.

For example, if your payload includes:

```json
{
  "ticket": {
    "checkInUrl": "https://example.com/checkin/abc123",
    "eventLogo": "https://example.com/logos/event.png"
  }
}
```

Bind the Content field to `ticket.checkInUrl` and the Logo URL to `ticket.eventLogo`. Every document gets a scannable QR code pointing to its own check-in URL, branded with the event logo.

![A QR Code block with dynamic values bound to payload variables](https://pdfmonkey.io/docs/img/qr-code-dynamic-values.webp)


## FAQ

**How do I add a QR code to a PDFMonkey template?**

Drag a QR Code block from the Extra category of the Blocks panel onto the canvas. Configure the Content field with a static URL or bind it to a data variable. You can also customize size, colors, dot style, corner style, and add a centered logo.

**Can I generate dynamic QR codes in PDFMonkey?**

Yes. Bind the Content and Logo URL fields to variables from your document payload. Each generated document will produce a unique QR code based on its data—for example, a unique check-in URL per event ticket.

**What error correction level should I use for QR codes with a logo?**

Use Quartile (Q) or High (H) error correction when adding a logo. The logo physically covers QR code modules, and higher error correction ensures the code remains scannable despite the obstruction.


---

# Custom CSS for Builder Templates

Source: https://pdfmonkey.io/docs/builder-templates/custom-css.md
The builder's Styles panel covers common styling needs — colors, spacing, typography, and layout. When you need something the visual controls don't offer, the CSS editor and external assets let you go further.

## The CSS editor

Click the **Custom CSS** button in the toolbar at the top of the canvas to open the global CSS editor. Write your CSS rules and press **Ctrl+Enter** (or **Cmd+Enter** on Mac) to save.

![The CSS editor with example styles](https://pdfmonkey.io/docs/img/css-editor-monaco.webp)

CSS written here applies globally to the entire template. This is especially useful for styling HTML blocks — which don't have visual style controls — and for adding effects the Styles panel doesn't support.

```css
/* Style an HTML block's content */
.product-card {
  border: 1px solid #e5e7eb;
  border-radius: 8px;
  padding: 16px;
  box-shadow: 0 1px 3px rgba(0, 0, 0, 0.1);
}

/* Add a decorative underline to headings */
h2 {
  border-bottom: 2px solid #db2777;
  padding-bottom: 8px;
}
```

> [!TIP]
> The builder generates Tailwind CSS utility classes for its visual styles. Your custom CSS rules take effect alongside Tailwind utilities. If you need to override a Tailwind-generated style, increase your selector specificity or use `!important` as a last resort.


## Arbitrary styles

The Styles panel has a **Custom** section at the bottom. This lets you apply arbitrary CSS to individual elements without writing global rules.

![The Custom section at the bottom of the Styles panel](https://pdfmonkey.io/docs/img/custom-style-panel.webp)

Arbitrary styles use Tailwind's bracket syntax: `[property:value]`. For example, adding `[outline:2px_solid_purple]` and `[outline-offset:10px]` draws a purple outline around that specific element.

This is useful for one-off adjustments — a specific `mix-blend-mode`, a `filter`, or any CSS property the visual controls don't expose.

## Custom webfonts

The **Text** section of the Styles panel includes a font-family selector with access to Google Fonts. For fonts from other providers, use `@font-face` or `@import` in the CSS editor:

```css
/* Self-hosted or third-party font */
@font-face {
  font-family: 'Brand Sans';
  src: url('https://your-cdn.example.com/fonts/brand-sans.woff2') format('woff2');
  font-weight: 400;
  font-style: normal;
}

.brand-heading {
  font-family: 'Brand Sans', sans-serif;
}
```

> [!NOTE]
> Webfont loading adds a small amount of time to document generation. Stick to one or two font families when possible to keep rendering fast.


## External stylesheets

For CSS libraries or frameworks, use the **External Assets** manager. Click the **External Assets** button in the toolbar, then add the CDN URL of the stylesheet you want to include.

![The External Assets editor with a CSS CDN URL](https://pdfmonkey.io/docs/img/external-assets-css.webp)

External stylesheets load before the template renders, so all their classes and styles are available immediately. Common uses include:

- **Icon libraries** — Font Awesome, Material Icons, Bootstrap Icons
- **Specialized tools** — print-specific stylesheets, CSS-based chart libraries

> [!WARNING]
> External assets require an active internet connection during document generation. Make sure your CDN URLs are reliable and publicly accessible. If a URL is unreachable, the styles will not apply.


## Difference from Code Templates

In [Code Templates](https://pdfmonkey.io/docs/code-templates/custom-css.md), you write CSS in a dedicated CSS tab. The builder separates concerns differently: global styles go in the CSS editor, arbitrary per-element styles go through the Styles panel's Custom section, and external libraries go through the External Assets manager.

## Related pages

- [Custom JS](https://pdfmonkey.io/docs/builder-templates/custom-js.md) — global JavaScript, inline scripts in HTML blocks, and external JS libraries


## FAQ

**How do I add custom CSS to a PDFMonkey builder template?**

Click the Custom CSS button in the builder toolbar to open the global CSS editor. Write your rules and press Ctrl+Enter (Cmd+Enter on Mac) to save. The CSS applies globally to the entire template, including inside HTML blocks.

**Can I use custom webfonts in PDFMonkey builder templates?**

Yes. The Styles panel includes a Google Fonts selector. For fonts from other providers, use @font-face or @import rules in the CSS editor with a URL to your hosted font files.

**How do I add external CSS libraries to a PDFMonkey template?**

Use the External Assets manager in the builder toolbar and add the CDN URL of the stylesheet. External stylesheets load before the template renders, so all their classes are immediately available. Common uses include icon libraries like Font Awesome.

**How do I apply arbitrary CSS to a single element in the PDFMonkey builder?**

Select the element, open the Styles tab, and scroll to the Custom section at the bottom. Enter values using Tailwind’s bracket syntax, such as [outline:2px_solid_purple], to apply one-off CSS properties the visual controls don’t expose.


---

# Custom JS

Source: https://pdfmonkey.io/docs/builder-templates/custom-js.md
The builder lets you add global JavaScript to your template for custom logic, calculations, or third-party library integration. You can also run inline scripts in individual HTML blocks and load external JS libraries from CDN URLs.

## The JavaScript editor

Click the **Custom JS** button in the toolbar at the top of the canvas to open the global JavaScript editor. Write your code and press **Ctrl+Enter** (or **Cmd+Enter** on Mac) to save.

![The JavaScript editor with example code](https://pdfmonkey.io/docs/img/js-editor-monaco.webp)

Code in the Custom JS editor runs in the template context when the document renders. This is where you define helper functions, format values, or set up any logic your template needs.

## Making functions available to the template

To make a function or variable usable in property bindings or HTML blocks, assign it to `window`:

```javascript
window.formatCurrency = function (amount, currency) {
  return new Intl.NumberFormat('en-US', {
    style: 'currency',
    currency: currency || 'USD',
  }).format(amount);
};

window.formatDate = function (dateString) {
  return new Date(dateString).toLocaleDateString('en-US', {
    year: 'numeric',
    month: 'long',
    day: 'numeric',
  });
};
```

Once defined on `window`, these functions can be called from bindings elsewhere in the template — for example, binding a Text block's content to `formatCurrency(invoice.total)`.

> [!TIP]
> Keep your Custom JS focused on utility functions and data formatting. Heavy computation or DOM manipulation can slow down document generation.


## Scripts in HTML blocks

The HTML block has a dedicated toggle for running inline scripts. Select an HTML block, open the **Settings** tab, and enable **Run scripts in editor**.

![An HTML block's Settings panel showing the Run scripts in editor toggle](https://pdfmonkey.io/docs/img/html-block-run-scripts.webp)

When enabled, any `<script>` tags inside the HTML block's content will execute during rendering. This is useful for block-specific logic that doesn't belong in the global Custom JS editor.

```html
<div id="chart-container"></div>
<script>
  // This runs only if "Run scripts in editor" is enabled
  const ctx = document.getElementById('chart-container');
  // ... render a chart or perform block-specific logic
</script>
```

> [!WARNING]
> Scripts in HTML blocks run independently of the global Custom JS editor. If an HTML block script depends on a function from the global editor, make sure the global script assigns it to `window` so it is accessible.


## External JavaScript libraries

For third-party libraries, use the **External Assets** manager. Click the **External Assets** button in the toolbar, then add the CDN URL of the JavaScript library you want to include.

![The External Assets editor with a JavaScript CDN URL](https://pdfmonkey.io/docs/img/external-assets-js.webp)

External scripts are loaded before the template renders, so their global variables and functions are available to both the Custom JS editor and HTML block scripts.

Common examples:

| Library | CDN URL | Use case |
|---------|---------|----------|
| Chart.js | `https://cdn.jsdelivr.net/npm/chart.js` | Charts and graphs |
| Day.js | `https://cdn.jsdelivr.net/npm/dayjs` | Date formatting |

> [!NOTE]
> External assets require an internet connection during document generation. Verify that your CDN URLs are publicly accessible and return the expected library version.


## Difference from Code Templates

In [Code Templates](https://pdfmonkey.io/docs/code-templates/custom-javascript.md), JavaScript is embedded directly in `<script>` tags within the HTML. The builder separates JavaScript into three distinct locations:

- **Global scripts** go in the Custom JS editor (toolbar button) — runs for the entire template
- **Block-specific scripts** go inside HTML blocks with the "Run scripts in editor" toggle enabled
- **External libraries** are loaded through the External Assets manager

This separation keeps global logic, per-block behavior, and third-party dependencies organized. For global formatting functions, use the Custom JS editor. For block-specific rendering (like charts), use an HTML block with scripts enabled. For libraries, use External Assets instead of manual `<script src="...">` tags.

## Related pages

- [Custom CSS](https://pdfmonkey.io/docs/builder-templates/custom-css.md) — global styling, per-element custom properties, and external CSS libraries


## FAQ

**How do I add custom JavaScript to a PDFMonkey builder template?**

Click the Custom JS button in the builder toolbar to open the global JavaScript editor. Write your code and press Ctrl+Enter (Cmd+Enter on Mac) to save. Functions assigned to window are available in bindings and HTML blocks throughout the template.

**Can I use external JavaScript libraries in PDFMonkey templates?**

Yes. Click the External Assets button in the toolbar and add the CDN URL of the library you want to include. External scripts load before the template renders, so their functions are available to both the Custom JS editor and HTML block scripts.

**How do I run inline scripts in an HTML block in the PDFMonkey builder?**

Select the HTML block, open the Settings tab, and enable the “Run scripts in editor” toggle. Any script tags inside that block will then execute during rendering. Without this toggle, scripts only run during PDF generation, not in the editor preview.


---

# Test Data

Source: https://pdfmonkey.io/docs/builder-templates/test-data.md
Test data lets you preview how your template renders with real values before generating any documents. You enter sample JSON in the payload editor, and the builder immediately reflects that data in the canvas — text blocks show your content, images load from your URLs, and loops repeat over your arrays.

## Opening the payload editor

Click the **Edit Test Data** button in the toolbar at the top of the canvas. This opens a modal containing a full JSON editor powered by Monaco (the same editor used in VS Code).

## JSON format

Enter your test data as a JSON object. The top-level keys become the variables available throughout your template. See [naming rules](#naming-your-variables) for which key formats are valid.

```json
{
  "name": "Jane Smith",
  "company": "Acme Corp",
  "date": "2025-03-15",
  "items": [
    { "description": "Widget A", "quantity": 2, "price": 19.99 },
    { "description": "Widget B", "quantity": 1, "price": 49.99 }
  ],
  "logo_url": "https://example.com/logo.png"
}
```

> [!TIP]
> The payload editor supports JSON comments — both `//` single-line and `/* */` block comments. Comments are stripped during parsing, so they never affect your template. Use them to note which fields are required or what format a value should take:
&gt; 
&gt; ```json
&gt; {
&gt;   // Customer details
&gt;   &#34;name&#34;: &#34;Jane Smith&#34;,
&gt;   &#34;email&#34;: &#34;jane@example.com&#34;,
&gt; 
&gt;   /* Items array - each item needs description, quantity, and price */
&gt;   &#34;items&#34;: []
&gt; }
&gt; ```


### Default test data

Templates created from a Master Template come with a default payload containing common fields like `name`, `company`, `items`, `date`, and `url`. Replace these with data that matches your actual document payloads — the default values are just a starting point. Templates created from scratch start with an empty payload.

## How test data connects to your template

Test data is the bridge between your template design and the dynamic values that will appear in the final PDF. Three builder features read directly from your test data:

### Variable browser

When you configure a property binding — for example, setting the source of an Image block — a variable browser dropdown appears. It lists every path available in your test data. If your test data has `logo_url` at the top level and `items[0].description` nested in an array, both paths show up as selectable options.

### Visibility conditions

The Logic panel's conditional display setting evaluates JavaScript expressions against your test data. When you enter a condition like `items.length > 0`, the panel immediately shows whether the element is currently visible or hidden based on the test data values.

### Repetition

When you set up repetition on an element and point it at a collection like `items`, the builder iterates over that array in your test data. The canvas renders one copy of the element for each item, so you can see exactly how your repeated layout looks with real data.

## Live preview

Changes to test data update the canvas immediately. Edit a name, add an item to an array, or change a URL, and the template re-renders in real time. This makes the payload editor the primary tool for debugging dynamic content — if something looks wrong, check your test data first.

## Connection to document generation

The JSON structure you use as test data is the same structure you pass as the `payload` when generating documents through the API or the Dashboard. Keeping your test data realistic ensures what you see in the builder is what you get in the final PDF.

> [!NOTE]
> Test data is saved with the template. You can close the editor and come back later without losing your sample payload.


## Naming your variables

Your payload keys become JavaScript identifiers that you reference in conditions, bindings, and expressions throughout the builder. Not every string that works as a JSON key works as a variable name.

### Valid keys

```json5
{
  "someVariable": "Some value",
  "some_variable": "Some value",
  "SomeVariable": "Some value",
  "somevariable": "Some value",
  "$someVariable": "Some value",
  "some": { "variable": "Some value" }
}
```

These keys are all accessible in the builder. Top-level keys show up directly in the variable browser, and nested keys are accessed with dot notation — `some.variable` reaches into the `some` object to read its `variable` property.

### Invalid keys

```json5
{
  "some.variable": "Some value",       // Dot conflicts with property access
  "some variable": "Some value",       // Spaces break expressions
  "(someVariable)": "Some value",      // Parentheses are operators in JS
  "'someVariable'": "Some value",      // Quotes aren't valid in identifiers
  "{{someVariable}}": "Some value",    // Braces are syntax characters
  "some-variable": "Some value",      // Hyphen is the minus operator in JS
  "2": "Some value",                   // Bare numbers aren't identifiers
  "2words": "Some value"               // Starts with a digit
}
```

The most common mistake is using dots in key names. A key like `"some.variable"` looks like it should work, but the builder interprets `some.variable` as "the `variable` property of the `some` object" — it never finds a key literally named `some.variable`. If you need nesting, use an actual nested object instead:

```json5
{
  // Don't do this
  "customer.name": "Jane Smith",

  // Do this instead
  "customer": { "name": "Jane Smith" }
}
```

> [!WARNING]
> These naming rules apply equally to the payload you send through the API when generating documents. If a key is invalid as test data, it won&#39;t work in production either.


## Tips for effective test data

- **Cover all branches**: If your template has visibility conditions, include test data that triggers both the visible and hidden states. Switch values between test runs to verify both paths.
- **Use realistic array lengths**: If your template repeats over a list of items, test with one item, a handful, and enough items to trigger a page break. Edge cases in repetition are easier to catch early.
- **Match your production payload**: The closer your test data resembles real API payloads, the fewer surprises you get when generating actual documents.


## FAQ

**What is test data in PDFMonkey’s builder?**

Test data is sample JSON you enter in the payload editor to preview how your template renders with realistic content. The builder uses it to populate text, images, and loops in real time before you generate actual documents.

**What JSON key formats are valid for PDFMonkey test data?**

Keys must be valid JavaScript identifiers: camelCase, snake_case, or dollar-prefixed names work. Keys with dots, spaces, hyphens, or starting with a digit are invalid because the builder treats them as JavaScript expressions.

**Is test data saved with my PDFMonkey template?**

Yes. Test data is saved with the template, so you can close the editor and return later without losing your sample payload.

**Does the test data JSON structure match the API payload?**

Yes. The JSON structure you use as test data is the same structure you pass as the payload when generating documents through the API, so keeping test data realistic ensures the builder preview matches the final PDF.



---

# Generate Documents from the Dashboard

Source: https://pdfmonkey.io/docs/generating-documents/using-the-dashboard.md
You can generate documents directly from the PDFMonkey dashboard without writing any code. This is useful for one-off documents, testing a template before integrating the API, or when non-technical team members need to produce PDFs. For a detailed walkthrough, see [From Zero to Your First Document](https://pdfmonkey.io/docs/getting-started/from-zero-to-first-document.md).

## Prerequisites

Before generating a document, you need:

- A PDFMonkey account ([register here](https://dashboard.pdfmonkey.io/register))
- A published template -- if you have not created one yet, follow the [getting started tutorial](https://pdfmonkey.io/docs/getting-started/from-zero-to-first-document.md)

## Create and generate a document

1. Navigate to [the Documents page](https://dashboard.pdfmonkey.io/documents).
2. Click **Create my first Document** (or **New Document** if you already have documents).
3. Select a template from the dropdown and click **Create a draft**. This opens the Document Editor.
4. In the **Data** tab, provide the JSON payload your template expects -- this follows the same structure as the test data you defined in your template.
5. Optionally, switch to the **Meta data** tab to set a [custom filename](https://pdfmonkey.io/docs/generating-documents/custom-filename.md) or other metadata.
6. Click **Save** to refresh the preview panel on the right, then click **Generate**.

## What happens next

Once you click **Generate**, the document enters the [document lifecycle](https://pdfmonkey.io/docs/generating-documents/document-statuses.md). When its status reaches **success**, a temporary [download URL](https://pdfmonkey.io/docs/generating-documents/download-url.md) appears on the document page. You can also find all your generated documents on the [Documents page](https://dashboard.pdfmonkey.io/documents).

If something goes wrong, check the [Troubleshooting](https://pdfmonkey.io/docs/troubleshooting/_index.md) section.


---

# Generate PDFs with the API

Source: https://pdfmonkey.io/docs/generating-documents/api-pdf-generation.md
The PDFMonkey REST API lets you generate PDF documents from your templates by sending HTTP requests with JSON data. Use it to create invoices, receipts, reports, certificates, and any PDF from dynamic data -- this is the best approach for automated workflows in your own application.

> [!NOTE]
> **Prerequisites**
>
> You&#39;ll need a [PDFMonkey account](https://dashboard.pdfmonkey.io/users/sign_up) and at least one template. If you haven&#39;t created a template yet, see [From Zero to First Document](https://pdfmonkey.io/docs/getting-started/from-zero-to-first-document.md).


## Generate a PDF

### 1. Get your API key

Grab your secret key from the [API Key page](https://dashboard.pdfmonkey.io/api_key) in your dashboard. See [Authentication](https://pdfmonkey.io/docs/api/authentication.md) for details.

### 2. Create a document

Send a POST request to `/api/v1/documents` with your template ID and dynamic data. Setting `"status": "pending"` queues generation immediately.

Examples are available in curl, Ruby, Node.js, Python, and PHP:








**curl**

```bash
curl https://api.pdfmonkey.io/api/v1/documents \
  -X POST \
  -H &#39;Authorization: Bearer YOUR_SECRET_KEY&#39; \
  -H &#39;Content-Type: application/json&#39; \
  -d &#39;{
    &#34;document&#34;: {
      &#34;document_template_id&#34;: &#34;YOUR-TEMPLATE-ID&#34;,
      &#34;status&#34;: &#34;pending&#34;,
      &#34;payload&#34;: {
        &#34;name&#34;: &#34;Jane Doe&#34;
      }
    }
  }&#39;
```

**Ruby**

```ruby
# generate! waits for the PDF to be ready before returning
document = Pdfmonkey::Document.generate!(
  document_template_id: &#39;YOUR-TEMPLATE-ID&#39;,
  payload: { name: &#39;Jane Doe&#39; }
)

document.status       # =&gt; &#39;success&#39;
document.download_url # =&gt; &#39;https://…&#39;
```

**Node.js**

```javascript
const response = await fetch(&#39;https://api.pdfmonkey.io/api/v1/documents&#39;, {
  method: &#39;POST&#39;,
  headers: {
    &#39;Authorization&#39;: &#39;Bearer YOUR_SECRET_KEY&#39;,
    &#39;Content-Type&#39;: &#39;application/json&#39;,
  },
  body: JSON.stringify({
    document: {
      document_template_id: &#39;YOUR-TEMPLATE-ID&#39;,
      status: &#39;pending&#39;,
      payload: { name: &#39;Jane Doe&#39; },
    },
  }),
});

const data = await response.json();
console.log(data.document);
```

**Python**

```python
import requests

response = requests.post(
    &#39;https://api.pdfmonkey.io/api/v1/documents&#39;,
    headers={
        &#39;Authorization&#39;: &#39;Bearer YOUR_SECRET_KEY&#39;,
    },
    json={
        &#39;document&#39;: {
            &#39;document_template_id&#39;: &#39;YOUR-TEMPLATE-ID&#39;,
            &#39;status&#39;: &#39;pending&#39;,
            &#39;payload&#39;: {&#39;name&#39;: &#39;Jane Doe&#39;},
        },
    },
)

print(response.json())
```

**PHP**

```php
&lt;?php
$ch = curl_init(&#39;https://api.pdfmonkey.io/api/v1/documents&#39;);

curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER =&gt; true,
    CURLOPT_POST =&gt; true,
    CURLOPT_HTTPHEADER =&gt; [
        &#39;Authorization: Bearer YOUR_SECRET_KEY&#39;,
        &#39;Content-Type: application/json&#39;,
    ],
    CURLOPT_POSTFIELDS =&gt; json_encode([
        &#39;document&#39; =&gt; [
            &#39;document_template_id&#39; =&gt; &#39;YOUR-TEMPLATE-ID&#39;,
            &#39;status&#39; =&gt; &#39;pending&#39;,
            &#39;payload&#39; =&gt; [&#39;name&#39; =&gt; &#39;Jane Doe&#39;],
        ],
    ]),
]);

$response = curl_exec($ch);
curl_close($ch);

print_r(json_decode($response, true));
```



The API returns the document with its current status. Note the `id` -- you'll need it to check on the generation.

```json title="201 Created (trimmed)"
{
  "document": {
    "id": "a5e86d72-f5b7-43d4-a04e-8b7e08e6741c",
    "status": "pending",
    "download_url": null,
    ...
  }
}
```

### 3. Check generation status

The PDF isn't ready yet -- poll the `document_cards` endpoint until the status reaches `success`, then read the `download_url`.








**curl**

```bash
curl -H &#39;Authorization: Bearer YOUR_SECRET_KEY&#39; \
  https://api.pdfmonkey.io/api/v1/document_cards/DOCUMENT_ID
# Once status is &#34;success&#34;, the download_url field contains a signed link to the PDF
```

**Ruby**

```ruby
# Not needed if you used generate! above — the document is already ready
card = Pdfmonkey::Document.fetch_card(&#39;DOCUMENT_ID&#39;)

card.status       # =&gt; &#39;success&#39;
card.download_url # =&gt; &#39;https://…&#39;
```

**Node.js**

```javascript
const response = await fetch(
  &#39;https://api.pdfmonkey.io/api/v1/document_cards/DOCUMENT_ID&#39;,
  {
    headers: {
      &#39;Authorization&#39;: &#39;Bearer YOUR_SECRET_KEY&#39;,
    },
  }
);

const data = await response.json();
console.log(data.document_card.status);       // =&gt; &#39;success&#39;
console.log(data.document_card.download_url); // =&gt; &#39;https://…&#39;
```

**Python**

```python
import requests

response = requests.get(
    &#39;https://api.pdfmonkey.io/api/v1/document_cards/DOCUMENT_ID&#39;,
    headers={
        &#39;Authorization&#39;: &#39;Bearer YOUR_SECRET_KEY&#39;,
    },
)

card = response.json()[&#39;document_card&#39;]
print(card[&#39;status&#39;])       # =&gt; &#39;success&#39;
print(card[&#39;download_url&#39;]) # =&gt; &#39;https://…&#39;
```

**PHP**

```php
&lt;?php
$ch = curl_init(&#39;https://api.pdfmonkey.io/api/v1/document_cards/DOCUMENT_ID&#39;);

curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER =&gt; true,
    CURLOPT_HTTPHEADER =&gt; [
        &#39;Authorization: Bearer YOUR_SECRET_KEY&#39;,
    ],
]);

$response = curl_exec($ch);
curl_close($ch);

$card = json_decode($response, true)[&#39;document_card&#39;];
echo $card[&#39;status&#39;];       // =&gt; &#39;success&#39;
echo $card[&#39;download_url&#39;]; // =&gt; &#39;https://…&#39;
```



> [!TIP]
> Instead of polling, you can set up a [webhook](https://pdfmonkey.io/docs/generating-documents/webhooks.md) to be notified when the document is ready. This is recommended for production workloads.


## Asynchronous vs synchronous generation

By default, document generation is **asynchronous**: you create the document, then either poll the API or set up a [webhook](https://pdfmonkey.io/docs/generating-documents/webhooks.md) to know when it is ready. This is the best approach for production workloads, especially at high volume.

If you prefer to wait for the result in a single request, use the **synchronous** endpoint at `/api/v1/documents/sync`. This is convenient for prototyping or low-volume, interactive use cases. See [Synchronous Generation](https://pdfmonkey.io/docs/api/documents.md#synchronous-generation) for details and caveats.

## Frequently asked questions

**What format should the payload use?**

The `payload` field accepts any valid JSON object. Its structure must match the variables used in your template -- see [Defining Dynamic Data](https://pdfmonkey.io/docs/code-templates/defining-dynamic-data.md).

**How long does PDF generation take?**

Most documents are ready within a few seconds. Complex templates with many pages or large images may take longer. Use a [webhook](https://pdfmonkey.io/docs/generating-documents/webhooks.md) to be notified as soon as the PDF is available.

**Is there a rate limit?**

There is no hard rate limit on the API, but your plan's monthly document quota applies. See [Our Plans](https://pdfmonkey.io/docs/pricing-and-billing/our-plans.md) for quota details.

**Can I generate multiple PDFs in one request?**

Not directly -- each API call generates one document. To generate PDFs in bulk, send multiple requests in parallel or use an automation platform like [Zapier](https://pdfmonkey.io/docs/integrations/zapier.md) or [Make](https://pdfmonkey.io/docs/integrations/make.md).

---

- [API Documents reference](https://pdfmonkey.io/docs/api/documents.md) -- full endpoint documentation
- [Document Statuses and Lifecycle](https://pdfmonkey.io/docs/generating-documents/document-statuses.md) -- understand document statuses
- [The Download URL](https://pdfmonkey.io/docs/generating-documents/download-url.md) -- how to retrieve the generated PDF


---

# Convert HTML to PDF with the PDFMonkey API

Source: https://pdfmonkey.io/docs/generating-documents/html-to-pdf.md
**PDFMonkey can work as an HTML-to-PDF API.** Send your complete HTML — including `<head>`, styles, and `<body>` — as a string in the document payload, and PDFMonkey renders it to PDF exactly as-is. No templating required on the PDFMonkey side.

This is useful when the HTML already lives in your own pipeline: a transactional email renderer reused for receipts, a dashboard export, or an existing HTML invoice template.

> [!NOTE]
> **When to use this approach**
>
> Use this pattern only when the HTML is owned and maintained outside of PDFMonkey. If the document layout will always be generated by PDFMonkey, a regular [Code Template](https://pdfmonkey.io/docs/code-templates/defining-dynamic-data.md) with dynamic data and Liquid logic will serve you better.


## How PDFMonkey converts your HTML to PDF

PDFMonkey does not expose a raw HTML endpoint. Every PDF is generated from a Template. The workaround is a minimal Code Template that acts as a transparent pass-through:

1. The template contains a single Liquid output tag: `{{htmlContent}}`
2. You send your full HTML as the `htmlContent` value in the document payload
3. Liquid renders the tag without escaping, so your HTML is injected verbatim
4. The PDF engine converts the resulting page to PDF

## Step 1 — Create the pass-through template

Create a new **Code Template** (this does not work with Builder Templates — see below). In the HTML tab, write nothing more than:

```liquid
{{htmlContent}}
```

Open **Settings** and configure the page size, margins, and engine version you want. Those settings apply at the template level regardless of what HTML you send.

Click **Publish** to make the template available to the API.

> [!WARNING]
> **Send a complete HTML document**
>
> The template renders only what is in `htmlContent`. Your HTML must include everything: a `&lt;!DOCTYPE html&gt;` declaration, a `&lt;head&gt;` with `&lt;style&gt;` or `&lt;link&gt;` tags, and a `&lt;body&gt;`. PDFMonkey adds nothing around it.


## Step 2 — POST your HTML in the document payload

Send your HTML as the `htmlContent` string field inside the `payload` object:

```bash
curl https://api.pdfmonkey.io/api/v1/documents \
  -X POST \
  -H 'Authorization: Bearer YOUR_SECRET_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "document": {
      "document_template_id": "YOUR-TEMPLATE-ID",
      "status": "pending",
      "payload": {
        "htmlContent": "<!DOCTYPE html><html><head><style>p { color: #333 }</style></head><body><p>Hello\nWorld!</p></body></html>"
      }
    }
  }'
```

Most HTTP libraries (Node.js `fetch`, Python `requests`, Ruby `net/http`) serialize strings automatically — you pass the HTML as a normal string and the library handles escaping. If you build JSON by hand, escape:

- double quotes → `\"`
- line breaks → `\n`
- backslashes → `\\`

See [Generate PDFs with the API](https://pdfmonkey.io/docs/generating-documents/api-pdf-generation.md) for the full generation flow, including how to poll for status and retrieve the download URL.

## Mixing your HTML with Liquid

The template still runs through Liquid, so you can layer PDFMonkey logic on top of your HTML. For example, this template appends a watermark without touching your HTML:

```liquid
{{htmlContent}}

{% if watermark %}
  <div class="watermark">{{watermark}}</div>
{% endif %}
```

Send both `htmlContent` and `watermark` in the payload. The `{% raw %}` tag is available if any field in your payload contains literal `{{` characters that should not be evaluated.

## Assets, fonts, and encoding

A few things to get right before your HTML renders as expected.

**Images and external stylesheets must use absolute URLs.** The PDF engine has no concept of your file system or server. A relative path like `./img/logo.png` or `/assets/style.css` will not resolve and the asset will be silently skipped. Use full `https://` URLs instead.

**External fonts load fine if accessible.** A `<link>` to Google Fonts or any public CDN works as expected — the engine fetches it during rendering. Fonts hosted behind authentication or on localhost will not load.

**Declare your character encoding.** Always include `<meta charset="utf-8">` in the `<head>`. Without it, non-ASCII characters (accented letters, CJK, symbols) may render as garbled text depending on the engine version.

## Trade-offs and limitations

| Trade-off | Details |
|-----------|---------|
| No reusable layout | Headers, footers, and shared styles must live in your own HTML pipeline |
| Larger payloads | Each document carries the full HTML string; large payloads count against [storage limits](https://pdfmonkey.io/docs/account-and-security/data-storage-and-retention.md) |
| No live preview | The Test Data tab can hold a sample, but changes don't preview like a normal template |
| No built-in Liquid logic | Conditions, loops, and filters must be in your renderer, not PDFMonkey's |

If you find yourself needing any of these features, switch to a [Code Template](https://pdfmonkey.io/docs/code-templates/defining-dynamic-data.md) and let PDFMonkey own the rendering.

## Builder Templates do not support this pattern

Builder Templates render bindings through Vue, which **escapes HTML by default** in `{{ ... }}` expressions. Sending raw HTML through a Builder binding prints the markup as visible text.

To inject pre-built HTML in a Builder Template, drop an [HTML block](https://pdfmonkey.io/docs/builder-templates/available-blocks.md#html) on the canvas and paste your markup directly into its code editor. Note that HTML blocks are static — they are part of the template itself, not driven by payload data.

## Related pages

- [Generate PDFs with the API](https://pdfmonkey.io/docs/generating-documents/api-pdf-generation.md) — the complete generation flow with status polling and download
- [Using Dynamic Data](https://pdfmonkey.io/docs/code-templates/defining-dynamic-data.md) — the standard way to pass structured data to a template
- [The Liquid Syntax](https://pdfmonkey.io/docs/code-templates/the-liquid-syntax.md) — output tags, logic, and filters in Code Templates
- [Available Blocks in the Builder](https://pdfmonkey.io/docs/builder-templates/available-blocks.md#html) — the HTML block for Builder Templates


## FAQ

**Can I use PDFMonkey as an HTML-to-PDF API?**

Yes. Create a Code Template containing only {{htmlContent}}, then POST your full HTML as the htmlContent value inside the document payload. PDFMonkey's Liquid engine does not escape HTML, so the markup renders as-is and returns a generated file.

**How do I send pre-built HTML to PDFMonkey and get a PDF back?**

1. Create a Code Template with a single line: {{htmlContent}}. 2. Publish the template. 3. POST to /api/v1/documents with your HTML as a string in the payload field htmlContent. PDFMonkey renders the HTML and returns the document with a download URL once generation is complete.

**Does this HTML-to-PDF approach work in a Builder Template?**

No. Builder Templates use Vue, which escapes interpolated content by default. Raw HTML sent through a Builder binding renders as visible text, not markup. Use a Code Template instead, or drop an HTML block on the Builder canvas.

**Why do I still need a template if I send the full HTML myself?**

PDFMonkey always generates documents from a template. The template carries the page size, margins, engine version, and access controls for the generation — even when it contains nothing but a Liquid placeholder for your HTML.

**What HTML escaping is needed when sending HTML in a JSON payload?**

Double quotes must be escaped as \", line breaks as \n, and backslashes as \\. Most HTTP client libraries and JSON serializers handle this automatically — you only need to escape manually when building raw JSON strings by hand.


---

# Generate PDFs with No-Code Integrations

Source: https://pdfmonkey.io/docs/generating-documents/using-an-integration.md
PDFMonkey integrates with popular automation platforms so you can generate documents without writing a single line of code. Connect your CRM, form builder, database, or any other app to PDFMonkey and produce PDFs automatically.

## When to use an integration

No-code integrations are the right choice when:

- You want to **automate PDF generation** in response to events in other apps (new form submission, new CRM deal, updated spreadsheet row, etc.)
- You prefer a **visual, drag-and-drop workflow** over writing code
- You need to connect PDFMonkey to **apps that don't have a backend** you control (Google Sheets, Airtable, Typeform, etc.)

If you need full programmatic control or are building a custom application, use the [REST API](https://pdfmonkey.io/docs/generating-documents/api-pdf-generation.md) instead.

## How it works

Regardless of which platform you choose, the general workflow is the same:

1. **Design a template** in PDFMonkey -- either with the [visual Builder](https://pdfmonkey.io/docs/builder-templates/_index.md) or with [HTML/CSS code](https://pdfmonkey.io/docs/code-templates/_index.md).
2. **Connect your PDFMonkey account** in the automation platform using your API Secret Key (found on the [My Account](https://dashboard.pdfmonkey.io/account) page).
3. **Set up a trigger** -- the event that starts PDF generation (e.g., a new row in a spreadsheet, a form submission, a new record in a CRM).
4. **Map your data** to the template variables. The automation platform passes values from the trigger into your template's dynamic fields.
5. **Generate and deliver** -- PDFMonkey creates the PDF and returns a download URL. You can then email it, upload it to cloud storage, or pass it to another step in your workflow.

> [!TIP]
> Most integrations return a **download URL** after generation. This URL is temporary (expires after 1 hour). If you need a permanent link, use a [share link](https://pdfmonkey.io/docs/generating-documents/share-links.md) or upload the PDF to your own storage as part of the workflow.


## Supported integrations

| Platform | Best for | Details |
| -------- | -------- | ------- |
| [Zapier](https://pdfmonkey.io/docs/integrations/zapier.md) | Connecting to 6,000+ apps with a simple trigger-action model | Triggers, actions, and field mapping |
| [Make](https://pdfmonkey.io/docs/integrations/make.md) | Building multi-step visual scenarios with branching logic | Full module with generate, retrieve, and download |
| [n8n](https://pdfmonkey.io/docs/integrations/n8n.md) | Self-hosted or cloud workflows with an open-source tool | Dedicated node with all CRUD operations |
| [Workato](https://pdfmonkey.io/docs/integrations/workato.md) | Enterprise-grade automation with advanced orchestration | Recipes for generating, deleting, and reacting to documents |
| [Bubble](https://pdfmonkey.io/docs/integrations/bubble.md) | Adding PDF generation to a Bubble no-code app | Plugin for direct integration |
| [Glide](https://pdfmonkey.io/docs/integrations/glide.md) | Generating documents from a Glide app | Lightweight integration |

Browse all integrations -- including the [Ruby SDK](https://pdfmonkey.io/docs/integrations/ruby-sdk.md) -- in the [Integrations](https://pdfmonkey.io/docs/integrations/_index.md) section.

## Custom integrations

For platforms not listed above, you have two options:

- **Webhooks** -- Configure a [webhook endpoint](https://pdfmonkey.io/docs/generating-documents/webhooks.md) in PDFMonkey to receive a notification (with the document data and download URL) whenever a document finishes generating. Your system can then process the PDF however you need.
- **Direct HTTP requests** -- Any platform that supports HTTP requests can call the [PDFMonkey REST API](https://pdfmonkey.io/docs/generating-documents/api-pdf-generation.md) directly. Send a POST request with your template ID and dynamic data to create a document.

## Next steps

- Pick a platform and follow its dedicated guide in the [Integrations](https://pdfmonkey.io/docs/integrations/_index.md) section
- New to PDFMonkey? Start with [From Zero to Your First Document](https://pdfmonkey.io/docs/getting-started/from-zero-to-first-document.md) to create a template first
- Need to react to generated documents? Learn about [webhooks](https://pdfmonkey.io/docs/generating-documents/webhooks.md)


## FAQ

**Can I generate PDFs without code using PDFMonkey?**

Yes. PDFMonkey integrates with Zapier, Make, n8n, Workato, Bubble, and Glide. You design a template in PDFMonkey, then connect it to your automation platform to generate documents automatically when events occur in other apps — no coding required.

**Which no-code platforms does PDFMonkey integrate with?**

PDFMonkey has official integrations with Zapier (6,000+ app connectors), Make (multi-step visual scenarios), n8n (open-source workflows), Workato (enterprise automation), Bubble (no-code web apps), and Glide (no-code mobile apps).

**How do no-code integrations work with PDFMonkey?**

The workflow is: 1) Design a template in PDFMonkey, 2) Connect your PDFMonkey account in the automation platform using your API key, 3) Set up a trigger event (form submission, new CRM deal, etc.), 4) Map data fields to template variables, 5) PDFMonkey generates the document and returns a download URL.


---

# Document Statuses and Lifecycle

Source: https://pdfmonkey.io/docs/generating-documents/document-statuses.md
Every document in PDFMonkey moves through a series of statuses on its way from creation to final PDF. Understanding this lifecycle helps you build reliable integrations and troubleshoot generation issues.

## Status overview

| Status | Meaning | What you can do |
|:---|:---|:---|
| `draft` | Created but not yet queued for generation | Edit payload, preview, delete |
| `pending` | Queued and waiting for a worker | Wait -- processing starts automatically |
| `generating` | Actively being rendered into a PDF | Wait -- the worker is processing |
| `success` | PDF is ready | Download, share, embed a preview |
| `failure` | An error occurred during generation | Inspect the error, fix the issue, retry |

```mermaid
stateDiagram-v2
    [*] --> draft: Created via API or Dashboard
    draft --> pending: Generation requested
    pending --> generating: Picked up by worker
    generating --> success: PDF ready
    generating --> failure: Error occurred
    failure --> pending: Retry requested
```

## Draft {#draft}

A document starts in the **draft** status when you create it, whether through the API or the Dashboard. This is the default status -- if you don't set `"status": "pending"` in your API call, the document stays here.

**What you can do:**

- Edit the document's dynamic data (payload)
- Preview the document using the `preview_url` field (see [Embedding a Document Preview](https://pdfmonkey.io/docs/generating-documents/embedding-a-preview.md))
- Delete the document

**Transition out:** Request generation by calling the API with `"status": "pending"` or by clicking **Generate** in the Dashboard. The document moves to **pending**.

> [!TIP]
> You can skip the draft step entirely. Set `&#34;status&#34;: &#34;pending&#34;` when creating the document to queue generation immediately -- this is the most common pattern for API integrations.


## Pending {#pending}

A document in the **pending** status is queued and waiting to be picked up by a generation worker.

**What it means:** The generation request has been accepted but processing has not started yet. Under normal conditions, documents leave this status within seconds.

**Transition out:** A worker picks up the document and moves it to **generating**. This happens automatically -- no action is required on your end.

> [!NOTE]
> Setting `&#34;status&#34;: &#34;pending&#34;` triggers a quota check. If your account has exceeded its monthly document quota, the API rejects the request with a validation error. See [Our Plans](https://pdfmonkey.io/docs/pricing-and-billing/our-plans.md) for quota details.


## Generating {#generating}

A document in the **generating** status is actively being processed. The template is rendered with the document's payload and converted to a PDF (or image, depending on the template's [output format](https://pdfmonkey.io/docs/generating-documents/output-format.md)).

**What it means:** The worker is building the document. This typically takes a few seconds, but complex templates with many pages or heavy assets can take longer.

**Transition out:** The document moves to either **success** or **failure** depending on the outcome.

## Success {#success}

A document in the **success** status has been generated and its PDF is available for download.

**What you can do:**

- Download the PDF via the `download_url` field -- this is a temporary signed URL valid for 1 hour, refreshed on each API fetch (see [The Download URL](https://pdfmonkey.io/docs/generating-documents/download-url.md))
- Share the document via its `public_share_link` if enabled (see [Share Links](https://pdfmonkey.io/docs/generating-documents/share-links.md))
- Receive a [webhook](https://pdfmonkey.io/docs/generating-documents/webhooks.md) notification when generation completes

> [!WARNING]
> The `download_url` expires after 1 hour. Fetch the document again from the API to get a fresh URL. See [The Download URL](https://pdfmonkey.io/docs/generating-documents/download-url.md) for details.


## Failure {#failure}

A document in the **failure** status encountered an error during generation. The `failure_cause` field in the API response contains a human-readable description of what went wrong. The `generation_logs` field provides additional detail for debugging.

**Common causes:**

- Syntax errors in the template (Liquid, HTML, or CSS)
- Invalid or missing dynamic data
- Asset loading failures (broken image URLs, unreachable external resources)
- Timeout due to excessive template complexity

**What you can do:**

- Inspect `failure_cause` and `generation_logs` to understand the error
- Fix the underlying issue in the template or payload
- Retry generation by setting the document status back to `"pending"` via the API

**Transition out:** When you request a retry, the document returns to **pending** and goes through the generation cycle again.

## Reacting to status changes

You don't need to poll the API in a loop to know when a document is ready. Set up a [webhook endpoint](https://pdfmonkey.io/docs/generating-documents/webhooks.md) to receive a notification when generation succeeds or fails. This is the recommended approach for production integrations.

If you prefer a synchronous workflow, use the `/api/v1/documents/sync` endpoint to wait for the result in a single request. See [Synchronous Generation](https://pdfmonkey.io/docs/api/documents.md#synchronous-generation) for details and caveats.

## Related pages

- [The Download URL](https://pdfmonkey.io/docs/generating-documents/download-url.md) -- how temporary download links work
- [Webhooks](https://pdfmonkey.io/docs/generating-documents/webhooks.md) -- receive notifications on status changes
- [API Documents reference](https://pdfmonkey.io/docs/api/documents.md) -- full endpoint and field documentation
- [Troubleshooting: The Download URL is Empty](https://pdfmonkey.io/docs/troubleshooting/download-url-is-empty.md) -- common reasons why `download_url` is `null`
- [Troubleshooting: The Download URL Gives a 403 Error](https://pdfmonkey.io/docs/troubleshooting/download-url-gives-403.md) -- how to handle expired URLs


## FAQ

**What statuses can a PDFMonkey document have?**

Documents move through five statuses: draft (created but not queued), pending (queued for processing), generating (actively being rendered), success (PDF is ready to download), and failure (an error occurred during generation).

**Can I skip the draft status when generating a PDFMonkey document?**

Yes. Set the status to pending when creating the document via the API to queue generation immediately. This is the most common pattern for API integrations.

**What happens when a PDFMonkey document fails to generate?**

The document moves to failure status with a failure_cause field describing the error. You can inspect the error, fix the template or payload issue, and retry by setting the status back to pending.


---

# Download URL

Source: https://pdfmonkey.io/docs/generating-documents/download-url.md
When a document reaches the **success** [status](https://pdfmonkey.io/docs/generating-documents/document-statuses.md), the API response includes a `download_url` field. This is a temporary signed URL pointing to the generated PDF or image stored on S3. It triggers a file download (not inline display) and expires after 1 hour.

```json title="Successful document response (trimmed)"
{
  "document": {
    "id": "a5e86d72-f5b7-43d4-a04e-8b7e08e6741c",
    "status": "success",
    "download_url": "https://pdfmonkey-production.s3.eu-west-1.amazonaws.com/...",
    "preview_url": "https://preview.pdfmonkey.io/...",
    "public_share_link": null
  }
}
```

## When the download URL appears

The `download_url` is only populated when the document status is `success`. For all other statuses (`draft`, `pending`, `generating`, `failure`), the field returns `null`.

If you just created a document and the URL is null, the most likely reason is that generation has not finished yet. See [The Download URL is Empty](https://pdfmonkey.io/docs/troubleshooting/download-url-is-empty.md) for a full diagnosis.

## URL expiration (1 hour)

> [!WARNING]
> **Download URLs expire after 1 hour**
>
> Each download URL is valid for **1 hour**. After that, the link returns a **403 Forbidden** error. This is expected behavior -- the URL is designed to be short-lived for security. See [The Download URL Gives a 403 Error](https://pdfmonkey.io/docs/troubleshooting/download-url-gives-403.md) if you encounter this.


Every time you fetch the document details (via the API or an integration), you receive a **fresh URL** with a new 1-hour window. You never need to regenerate the document itself to get a working link.

If you need a permanent URL that never expires, consider using [Share Links](https://pdfmonkey.io/docs/generating-documents/share-links.md) instead.

## Refreshing an expired download URL

If a download URL has expired, fetch the document again to get a new one:

- **Via the API:** `GET /api/v1/document_cards/:id` -- see [API Documents reference](https://pdfmonkey.io/docs/api/documents.md)
- **Via an integration:** Use a "Get Document" or "Find Document" action in [Zapier](https://pdfmonkey.io/docs/integrations/zapier.md), [Make](https://pdfmonkey.io/docs/integrations/make.md), or another platform
- **Via the Dashboard:** Open the document detail page -- the download link is always current

You do **not** need to regenerate the document. The file remains on S3 until it is [deleted](https://pdfmonkey.io/docs/generating-documents/retention-and-deletion.md) -- only the signed URL expires.

## Download URL vs. other URL fields

| Field | Purpose | Expiration |
|:------|:--------|:-----------|
| `download_url` | Temporary signed URL that downloads the generated file. Only populated on `success` status. | 1 hour |
| `preview_url` | Renders a preview of the document in the browser. Works even for drafts. **Not a download link** -- do not use it to retrieve the final file. See [Embedding a Preview](https://pdfmonkey.io/docs/generating-documents/embedding-a-preview.md). | Does not expire |
| `public_share_link` | Permanent public URL to view and download the file. Available on Pro+ and Premium plans only. See [Share Links](https://pdfmonkey.io/docs/generating-documents/share-links.md). | Does not expire |

## Best practices

- **Download promptly.** When you receive a [webhook](https://pdfmonkey.io/docs/generating-documents/webhooks.md) notification or poll for completion, download the file right away.
- **Store the file, not the URL.** If you need the file later, save it to your own storage (S3, Google Drive, etc.) rather than relying on the temporary download URL.
- **Re-fetch when needed.** If you do need the URL later, call the API again to get a fresh one -- it takes a single GET request.
- **Use share links for distribution.** If you need a stable URL to embed in emails or web pages, use `public_share_link` instead (requires Pro+ or Premium plan). See [Share Links](https://pdfmonkey.io/docs/generating-documents/share-links.md).

## Troubleshooting

- [The Download URL is Empty](https://pdfmonkey.io/docs/troubleshooting/download-url-is-empty.md) -- common reasons why the URL is `null`
- [The Download URL Gives a 403 Error](https://pdfmonkey.io/docs/troubleshooting/download-url-gives-403.md) -- how to handle expired URLs

## Related pages

- [Document Statuses and Lifecycle](https://pdfmonkey.io/docs/generating-documents/document-statuses.md) -- understand when `download_url` becomes available
- [Generate PDFs with the API](https://pdfmonkey.io/docs/generating-documents/api-pdf-generation.md) -- end-to-end generation workflow
- [Webhooks](https://pdfmonkey.io/docs/generating-documents/webhooks.md) -- get notified when a document is ready to download
- [Automatic Deletion (TTL)](https://pdfmonkey.io/docs/generating-documents/retention-and-deletion.md) -- how long files are stored before cleanup
- [API Documents reference](https://pdfmonkey.io/docs/api/documents.md) -- full field documentation


## FAQ

**How long is a PDFMonkey download URL valid?**

Each download URL is a temporary signed link valid for 1 hour. After that, it returns a 403 Forbidden error. Fetch the document again via the API to get a fresh URL — no need to regenerate the document.

**Why is the download_url field null?**

The download_url is only populated when the document status is "success". If the document is in draft, pending, generating, or failure status, the field returns null. Make sure you set status to "pending" when creating the document and wait for generation to complete.

**How do I get a new download URL after it expires?**

Fetch the document again via the API (GET /api/v1/documents/:id) or through an integration. Each fetch returns a fresh URL with a new 1-hour window. You never need to regenerate the document itself.


---

# Set a Custom Filename for Generated Documents

Source: https://pdfmonkey.io/docs/generating-documents/custom-filename.md
By default, PDFMonkey names generated files using an internal identifier. You can override this by passing a `_filename` key in the document's **metadata** -- this works for both PDFs and images.

## Setting the filename via the API

Include the `_filename` key inside the `meta` object when you [create](https://pdfmonkey.io/docs/api/documents.md#create-a-document) or [update](https://pdfmonkey.io/docs/api/documents.md#update-a-document) a document:

```bash
curl https://api.pdfmonkey.io/api/v1/documents \
  -X POST \
  -H 'Authorization: Bearer YOUR_SECRET_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "document": {
      "document_template_id": "YOUR_TEMPLATE_ID",
      "status": "pending",
      "payload": { "name": "Jane Doe" },
      "meta": {
        "_filename": "invoice-2050-03.pdf"
      }
    }
  }'
```

The `meta` field accepts a JSON object. You can include other metadata keys alongside `_filename` -- see [API Documents reference](https://pdfmonkey.io/docs/api/documents.md#create-a-document) for full details.

## Setting the filename from the Dashboard

1. Open a document in the Document Editor.
2. Switch to the **Meta data** tab.
3. Enter the `_filename` key and your desired name:

```json
{
  "_filename": "invoice-2050-03.pdf"
}
```

4. Click **Save**, then **Generate**.

For a full walkthrough, see [Generate Documents from the Dashboard](https://pdfmonkey.io/docs/generating-documents/using-the-dashboard.md).

## File extension handling

PDFMonkey manages the file extension automatically based on the output format (PDF, PNG, WebP, or JPG):

- **If you include the matching extension** (e.g. `invoice.pdf` for a PDF template), PDFMonkey strips it and re-appends it to keep the filename clean.
- **If you omit the extension**, PDFMonkey appends the correct one for you.
- **If you include a mismatched extension** (e.g. `.png` on a PDF document), it is treated as part of the name and the correct extension is still appended.

> [!TIP]
> You don&#39;t need to worry about the extension. Just provide the name you want and let PDFMonkey handle the rest.


## Filename sanitization

PDFMonkey sanitizes the `_filename` value to ensure it is safe for all file systems:

| Rule | Example |
|:-----|:--------|
| Accented characters are transliterated to ASCII | `cafe-resume` becomes `cafe-resume` |
| Characters other than letters, digits, dashes, underscores, and spaces are replaced with a dash | `report@2050/03` becomes `report-2050-03` |
| Consecutive dashes are collapsed | `report---final` becomes `report-final` |
| Leading and trailing dashes are removed | `-my-file-` becomes `my-file` |
| Whitespace is trimmed from both ends | `" invoice "` becomes `"invoice"` |

For example, an input of `"Facture n 2050/03"` for a PDF template produces the filename `Facture n-2050-03.pdf`.

## Works with images too

The `_filename` key works the same way for [image output formats](https://pdfmonkey.io/docs/generating-documents/output-format.md). The extension is adjusted to match the image type (`.webp`, `.png`, or `.jpg`):

```json
{
  "meta": {
    "_filename": "social-card-march",
    "_type": "png"
  }
}
```

This produces a file named `social-card-march.png`.

## Frequently asked questions

**What happens if I don't set a custom filename?**

PDFMonkey uses an internal default name. If you need predictable filenames for archival or downstream systems, always set `_filename`.

**Can I use dynamic data in the filename?**

Not directly inside the `_filename` value. However, in most integration platforms (Zapier, Make, n8n) you can use dynamic fields or expressions to build the filename string before passing it to PDFMonkey.

**Is there a maximum filename length?**

There is no explicit limit enforced by PDFMonkey, but keep filenames reasonable (under 200 characters) to avoid issues with file systems and browsers.

## Related pages

- [API Documents reference](https://pdfmonkey.io/docs/api/documents.md) -- full parameter documentation for `meta` and other fields
- [Generate PDFs with the API](https://pdfmonkey.io/docs/generating-documents/api-pdf-generation.md) -- end-to-end generation workflow
- [Generate Documents from the Dashboard](https://pdfmonkey.io/docs/generating-documents/using-the-dashboard.md) -- using the Meta data tab
- [Output Formats](https://pdfmonkey.io/docs/generating-documents/output-format.md) -- image generation and meta keys like `_type`
- [Download URL](https://pdfmonkey.io/docs/generating-documents/download-url.md) -- how to retrieve the generated file


## FAQ

**How do I set a custom filename for a PDFMonkey document?**

Pass a "_filename" key in the document's meta field. Via the API, include it in the meta object when creating or updating a document: "meta": { "_filename": "invoice-2050.pdf" }. In the Dashboard, enter it in the Meta data tab of the Document Editor.

**Does PDFMonkey add the file extension automatically?**

Yes. If you include the correct extension (.pdf, .png, .webp, .jpg), PDFMonkey strips it and re-adds it to keep the filename clean. If you omit the extension, PDFMonkey appends it automatically based on the output format.

**What characters are allowed in the custom filename?**

PDFMonkey sanitizes the filename: accented characters are transliterated to ASCII, any character that is not a letter, digit, dash, underscore, or space is replaced with a dash, and consecutive or leading/trailing dashes are removed.


---

# Password-Protect Generated PDFs

Source: https://pdfmonkey.io/docs/generating-documents/pdf-password-protection.md
You can generate password-protected PDFs by passing a `_password` key in the document's **metadata**. The generated file is encrypted with AES-256 and requires the password to open. If you omit `_password`, documents generate without encryption as usual.

## Setting the password via the API

Include the `_password` key inside the `meta` object when you [create](https://pdfmonkey.io/docs/api/documents.md#create-a-document) a document:

```bash
curl https://api.pdfmonkey.io/api/v1/documents \
  -X POST \
  -H 'Authorization: Bearer YOUR_SECRET_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "document": {
      "document_template_id": "YOUR_TEMPLATE_ID",
      "status": "pending",
      "payload": { "name": "Jane Doe" },
      "meta": {
        "_password": "s3cur3-p@ss!"
      }
    }
  }'
```

You can combine `_password` with other meta keys like [`_filename`](https://pdfmonkey.io/docs/generating-documents/custom-filename.md):

```json
{
  "meta": {
    "_filename": "contract-jane-doe.pdf",
    "_password": "s3cur3-p@ss!"
  }
}
```

## Setting the password from the Dashboard

1. Open a document in the Document Editor.
2. Switch to the **Meta data** tab.
3. Enter the `_password` key and your desired password:

```json
{
  "_password": "s3cur3-p@ss!"
}
```

4. Click **Save**, then **Generate**.

For a full walkthrough, see [Generate Documents from the Dashboard](https://pdfmonkey.io/docs/generating-documents/using-the-dashboard.md).

## How it works

When `_password` is present in the meta, PDFMonkey encrypts the generated PDF with **AES-256** after rendering. The recipient needs the exact password to open the document. Without it, the content stays locked.

- **Any template works.** Code editor, Builder, existing templates -- password protection works with all of them.
- **No configuration needed.** You don't need to enable anything on the template or your account.
- **Works with all integrations.** Zapier, Make, Workato, n8n, Bubble, Glide, direct API -- anywhere you can set the `meta` field.
- **Per-document control.** One document can be password-protected while the next one isn't.
- **Available on all plans.** Free plan included.

## Frequently asked questions

**What happens if I don't set a password?**

Documents generate without encryption, exactly as before. Password protection is opt-in.

**Can I use dynamic data in the password?**

Not directly inside the `_password` value. However, in most integration platforms (Zapier, Make, n8n) you can use dynamic fields or expressions to build the password string before passing it to PDFMonkey.

**Does password protection work with image output formats?**

No. Password protection only applies to PDF output. Image formats (PNG, WebP, JPG) do not support encryption.

## Related pages

- [Custom Filename](https://pdfmonkey.io/docs/generating-documents/custom-filename.md) -- another meta key that controls generation behavior
- [API Documents reference](https://pdfmonkey.io/docs/api/documents.md) -- full parameter documentation for `meta` and other fields
- [Generate PDFs with the API](https://pdfmonkey.io/docs/generating-documents/api-pdf-generation.md) -- end-to-end generation workflow
- [Generate Documents from the Dashboard](https://pdfmonkey.io/docs/generating-documents/using-the-dashboard.md) -- using the Meta data tab


## FAQ

**How do I password protect a PDF with PDFMonkey?**

Pass a "_password" key in the document's meta field. Via the API, include it in the meta object when creating a document: "meta": { "_password": "your-password" }. The generated PDF will be encrypted with AES-256 and require the password to open.

**What encryption does PDFMonkey use for password-protected PDFs?**

PDFMonkey uses AES-256 encryption. The PDF is encrypted after generation, and the recipient needs the exact password you specified to open the document.

**Can I generate PDFs without a password?**

Yes. If you don't include the _password field in your meta, PDFs generate exactly as before: no encryption, no password. Password protection is entirely opt-in, per document.


---

# Generate Images Instead of PDFs

Source: https://pdfmonkey.io/docs/generating-documents/output-format.md
PDFMonkey generates PDFs by default, but templates with the **Image** output type produce **WebP, PNG, or JPG images** instead. The API workflow is identical; only the template type and a few meta options differ.

## Creating an image template

To generate images, you need a template configured for image output. Select **Image** as the output type when creating your template:

> [!TIP]
> **Pro tip**
>
> You can also duplicate an existing template and change its output type to **Image**.


> [!NOTE]
> **Why separate template types?**
>
> PDFs and images have fundamentally different capabilities. PDF documents support headers, footers, and various paper sizes. Image templates support transparent backgrounds and pixel-based dimensions instead.


Once the template is created, open its settings to configure:

- **Width and height**: in pixels (defaults to 500 x 500)
- **Transparent background**: supported by WebP and PNG

## Generating an image via the API

Generate an image the same way you generate a PDF: send a `POST` request to `/api/v1/documents` (or `/api/v1/documents/sync` for [synchronous generation](https://pdfmonkey.io/docs/api/documents.md#synchronous-generation)). As long as the `document_template_id` points to an image template, PDFMonkey produces an image instead of a PDF.

```bash
curl https://api.pdfmonkey.io/api/v1/documents \
  -X POST \
  -H 'Authorization: Bearer YOUR_SECRET_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "document": {
      "document_template_id": "YOUR_IMAGE_TEMPLATE_ID",
      "status": "pending",
      "payload": { "title": "Hello World" }
    }
  }'
```

By default, a **WebP** image is created. WebP offers good quality at a reasonable file size and supports transparent backgrounds.

## Generation-time meta options

You can override the template defaults at generation time by passing special keys in the document's `meta` field. These options only apply to image templates; they are ignored for PDF templates.

| Key | Type | Description | Default |
|:---|:---|:---|:---|
| `_type` | string | Image format: `webp`, `png`, or `jpg` | `webp` |
| `_width` | integer | Image width in pixels | Template setting (500) |
| `_height` | integer | Image height in pixels | Template setting (500) |
| `_quality` | integer | Compression quality from 1 to 100 (WebP only) | `100` |

```json5 title="Request body with meta overrides"
{
  "document": {
    "document_template_id": "YOUR_IMAGE_TEMPLATE_ID",
    "payload": { "title": "Hello World" },
    "status": "pending",
    "meta": {
      "_type": "png",
      "_width": 1200,
      "_height": 630
    }
  }
}
```

> [!WARNING]
> The `_quality` option only applies to WebP images. PNG is always lossless, and JPG uses a fixed quality setting.


> [!TIP]
> For social media cards and Open Graph images, `1200x630` is the most widely recommended size. Pass `&#34;_type&#34;: &#34;png&#34;` for maximum compatibility.


## Transparent backgrounds

Transparency is controlled in the **template settings**, not at generation time. Enable it when you need images without a background (useful for logos, watermarks, and overlay graphics).

Transparent backgrounds are supported by **WebP** and **PNG**. JPG does not support transparency: any transparent areas render as white.

## Custom filenames for images

The `_filename` [meta key](https://pdfmonkey.io/docs/generating-documents/custom-filename.md) works the same way for images as it does for PDFs. PDFMonkey appends the correct extension (`.webp`, `.png`, or `.jpg`) automatically:

```json
{
  "meta": {
    "_filename": "social-card-march",
    "_type": "png"
  }
}
```

This produces a file named `social-card-march.png`.

## Frequently asked questions

**What happens if I use image meta options on a PDF template?**

They are ignored. The `_type`, `_width`, `_height`, and `_quality` meta keys only affect image templates.

**Can I change the output format of an existing template?**

Yes. Open the template settings in the Dashboard and change the output type. Existing documents generated from the template are not affected; only new documents use the updated setting.

**Is there a maximum image size?**

There is no hard pixel limit, but very large images (above 4000 x 4000 px) increase generation time and memory usage. Keep dimensions reasonable for your use case.

**Do webhooks work with image generation?**

Yes. [Webhooks](https://pdfmonkey.io/docs/generating-documents/webhooks.md) fire on `documents.generation.success` and `documents.generation.failure` regardless of output type.

## Related pages

- [Generate PDFs with the API](https://pdfmonkey.io/docs/generating-documents/api-pdf-generation.md): end-to-end generation workflow
- [Set a Custom Filename](https://pdfmonkey.io/docs/generating-documents/custom-filename.md): control the filename of generated files
- [API Documents reference](https://pdfmonkey.io/docs/api/documents.md): full parameter documentation for `meta` and other fields
- [Document Statuses and Lifecycle](https://pdfmonkey.io/docs/generating-documents/document-statuses.md): understand the generation lifecycle
- [The Download URL](https://pdfmonkey.io/docs/generating-documents/download-url.md): how to retrieve the generated file


## FAQ

**Can PDFMonkey generate images instead of PDFs?**

Yes. PDFMonkey supports WebP, PNG, and JPG image generation alongside PDFs. Create a template with the "Image" output type, then use the same API endpoints to generate images.

**What is the default image format in PDFMonkey?**

WebP is the default format for image templates. It provides good quality at a smaller file size and supports transparent backgrounds. You can override this by passing "_type": "png" or "_type": "jpg" in the document metadata.

**How do I set the dimensions of a generated image?**

Set the default dimensions in the template settings (width and height in pixels, defaulting to 500x500). You can override these at generation time by passing "_width" and "_height" in the document metadata.


---

# Permanent Share Links for Generated Documents

Source: https://pdfmonkey.io/docs/generating-documents/share-links.md
Every successfully generated document on a **Pro+** or **Premium** plan includes a `public_share_link` field: a permanent public URL that never expires and requires no authentication. Use it to share generated files in emails, embed them in web pages, or distribute them to external recipients.

```json title="Successful document response (trimmed)"
{
  "document": {
    "id": "a5e86d72-f5b7-43d4-a04e-8b7e08e6741c",
    "status": "success",
    "download_url": "https://pdfmonkey-production.s3.eu-west-1.amazonaws.com/...",
    "public_share_link": "https://files.pdfmonkey.io/share/72BE2293-D130-4C19-9E11-C82B5CEA8C37/invoice-2050-03.pdf"
  }
}
```

> [!WARNING]
> **Pro&#43; and Premium plans only**
>
> The share links feature is only available on Pro&#43; and Premium plans. On other plans, `public_share_link` returns `null`. See [Our Plans](https://pdfmonkey.io/docs/pricing-and-billing/our-plans.md) for a feature comparison.


## When the share link appears

The `public_share_link` is populated when **both** conditions are met:

1. The document [status](https://pdfmonkey.io/docs/generating-documents/document-statuses.md) is `success`.
2. The account is on a **Pro+** or **Premium** plan.

For any other status (`draft`, `pending`, `generating`, `failure`) or on lower-tier plans, the field returns `null`.

## URL format

Share links follow this pattern:

```
https://files.pdfmonkey.io/share/{share_token}/{filename}
```

- **`share_token`** is a UUID assigned to each document at creation. It does not change.
- **`filename`** is the document's filename, including the extension (`.pdf`, `.png`, `.webp`, or `.jpg`). If you set a [custom filename](https://pdfmonkey.io/docs/generating-documents/custom-filename.md), it appears here.

## Inline display vs. download

By default, opening a share link triggers a **file download**. To display the file inline in the browser instead, append a `disposition` query parameter:

```
https://files.pdfmonkey.io/share/{share_token}/{filename}?disposition=inline
```

| Value | Behavior |
|:------|:---------|
| `attachment` (default) | Browser downloads the file |
| `inline` | Browser displays the file (PDFs render in the built-in viewer; images display directly) |

> [!TIP]
> Use `?disposition=inline` when embedding share links in web pages where you want the user to view the document before downloading.


## Share links vs. download URLs

| | `public_share_link` | `download_url` |
|:---|:---|:---|
| **Expiration** | Never expires | Expires after 1 hour |
| **Authentication** | None required | None required |
| **Availability** | Pro+ and Premium plans only | All plans |
| **Inline display** | Supported via `?disposition=inline` | No (always downloads) |
| **When populated** | `success` status on qualifying plan | `success` status |

If you need a URL that stays valid indefinitely, use `public_share_link`. If you only need a short-lived download link (for example, to save the file to your own storage immediately after generation), `download_url` is sufficient. See [The Download URL](https://pdfmonkey.io/docs/generating-documents/download-url.md) for more details.

## Plan changes and share links

Share links are tied to your account plan, not to individual documents:

- **Upgrading to Pro+ or Premium:** All past documents that were generated successfully gain a working share link retroactively. You do not need to regenerate them.
- **Downgrading from Pro+ or Premium:** Existing share links stop working immediately. The `public_share_link` field returns `null` in API responses. Additionally, documents that fall outside the [retention window](https://pdfmonkey.io/docs/generating-documents/retention-and-deletion.md) of your new plan are permanently deleted.
- **Re-upgrading later:** Share links reactivate automatically for documents that still exist. However, any documents deleted during the downgrade due to shorter retention are gone permanently and cannot be recovered.

See [Changing My Plan](https://pdfmonkey.io/docs/pricing-and-billing/changing-my-plan.md) for more details on how plan changes affect features.

## Works with images too

Share links work for all [output formats](https://pdfmonkey.io/docs/generating-documents/output-format.md), not just PDFs. If your template produces a WebP, PNG, or JPG image, the share link points to the image file with the correct extension.

## Frequently asked questions

**Why is `public_share_link` null even though my document is successful?**

Your account is likely on a plan that does not include share links (Free, Starter, or Pro). Upgrade to Pro+ or Premium to enable the feature. See [Our Plans](https://pdfmonkey.io/docs/pricing-and-billing/our-plans.md).

**Can I revoke a share link for a specific document?**

Deleting the document removes the share link permanently. There is no way to disable a share link without deleting the document itself.

**Do share links survive document deletion?**

No. Once a document is [deleted](https://pdfmonkey.io/docs/generating-documents/retention-and-deletion.md) (manually or via TTL), the share link returns a 404 error.

**Is the share link included in webhook payloads?**

Yes. The `public_share_link` field is part of the document payload sent to your [webhook endpoint](https://pdfmonkey.io/docs/generating-documents/webhooks.md) when generation succeeds.

## Related pages

- [The Download URL](https://pdfmonkey.io/docs/generating-documents/download-url.md) -- temporary signed links and how they differ from share links
- [Document Statuses and Lifecycle](https://pdfmonkey.io/docs/generating-documents/document-statuses.md) -- understand when `public_share_link` becomes available
- [Set a Custom Filename](https://pdfmonkey.io/docs/generating-documents/custom-filename.md) -- control the filename that appears in the share link
- [Automatic Deletion (TTL)](https://pdfmonkey.io/docs/generating-documents/retention-and-deletion.md) -- how document deletion affects share links
- [Our Plans](https://pdfmonkey.io/docs/pricing-and-billing/our-plans.md) -- which plans include share links
- [Changing My Plan](https://pdfmonkey.io/docs/pricing-and-billing/changing-my-plan.md) -- what happens to share links when you change plans
- [API Documents reference](https://pdfmonkey.io/docs/api/documents.md) -- full field documentation including `public_share_link`


## FAQ

**What is a PDFMonkey share link?**

A share link is a permanent public URL for a generated document. It never expires, requires no authentication, and can be embedded in emails, web pages, or shared directly with recipients. Available on Pro+ and Premium plans.

**How is a share link different from a download URL?**

Download URLs are temporary signed links that expire after 1 hour and always trigger a file download. Share links are permanent public URLs that never expire. By default, share links trigger a download, but you can append ?disposition=inline to display the file in the browser instead.

**Do share links still work if I downgrade my plan?**

No. Share links stop working when you downgrade from a Pro+ or Premium plan. Documents outside the retention window of your new plan are permanently deleted. If you upgrade back, share links reactivate for the documents that still exist.


---

# Document Retention and Automatic Deletion (TTL)

Source: https://pdfmonkey.io/docs/generating-documents/retention-and-deletion.md
Every generated document is stored on PDFMonkey's servers until it expires or you delete it. You control how long documents live by setting a **TTL (Time To Live)** on each template. When a document's TTL expires, PDFMonkey automatically deletes it along with its generated file.

## How TTL works

TTL is a per-template setting expressed in seconds. When a document finishes generating successfully, PDFMonkey calculates its expiration time by adding the TTL to the generation timestamp. A background job runs every minute, deleting all documents whose expiration has passed.

The countdown starts when the document reaches the `success` [status](https://pdfmonkey.io/docs/generating-documents/document-statuses.md), not when it is created or queued.

> [!NOTE]
> **Deletion may take up to one minute**
>
> The auto-deletion job runs every minute. In practice, a document may persist up to one minute past its expiration time.


## Configuring TTL in the dashboard

Open a template's **Settings** tab and locate the **Deletion** dropdown. Select the retention period that fits your needs:

![The Deletion dropdown in template settings, showing options from 5 minutes to 1 week, plus Never](https://pdfmonkey.io/docs/img/auto-deletion-settings.webp)

The available options depend on your [plan](https://pdfmonkey.io/docs/pricing-and-billing/our-plans.md). If you select a value your plan does not support, PDFMonkey caps it to your plan's maximum.

## Available TTL values by plan

| TTL option | Seconds | Free | Starter | Pro | Pro+ | Premium |
|:-----------|--------:|:----:|:-------:|:---:|:----:|:-------:|
| 5 minutes | 300 | Yes | Yes | Yes | Yes | Yes |
| 20 minutes | 1,200 | Yes | Yes | Yes | Yes | Yes |
| 1 hour | 3,600 | Yes | Yes | Yes | Yes | Yes |
| 1 day | 86,400 | Yes | Yes | Yes | Yes | Yes |
| 1 week | 604,800 | No | No | Yes | Yes | Yes |
| 1 month | 2,592,000 | No | No | No | Yes | Yes |
| 1 year | 31,536,000 | No | No | No | Yes | Yes |
| Never (unlimited) | 0 | No | No | No | Yes | Yes |

> [!WARNING]
> **Plan-based limits**
>
> Each plan has a maximum TTL. If you set a TTL higher than your plan allows (for example, selecting &#34;1 week&#34; on a Starter plan), PDFMonkey automatically uses the highest value your plan supports.


## Setting TTL via the API

When creating or updating a template through the [Templates API](https://pdfmonkey.io/docs/api/templates.md), include the `ttl` field with a value in seconds:

```json title="Setting TTL when creating a template"
{
  "document_template": {
    "identifier": "invoice-template",
    "ttl": 3600
  }
}
```

The same plan-based capping applies: if you request a TTL that exceeds your plan's maximum, the API silently uses the highest allowed value instead of returning an error.

## What gets deleted

When a document is deleted (whether by TTL expiration, manual deletion in the dashboard, or an [API call](https://pdfmonkey.io/docs/api/documents.md#delete-a-document)), PDFMonkey removes:

- **The generated file** (PDF, PNG, WebP, or JPG) from storage
- **The payload** (the dynamic data you sent to generate the document)
- **The meta data** associated with the document

The document no longer appears in API responses or the dashboard. Any [share link](https://pdfmonkey.io/docs/generating-documents/share-links.md) pointing to the document returns a 404 error.

> [!CAUTION]
> **Deletion is permanent**
>
> There is no way to recover a deleted document, its generated file, or its payload. If you need to keep files long-term, download them to your own storage before the TTL expires. See [The Download URL](https://pdfmonkey.io/docs/generating-documents/download-url.md) for details.


## Plan changes and retention

When you change plans, PDFMonkey adjusts TTL settings to match the new plan's limits:

- **Upgrading:** Templates keep their current TTL. If you previously set a lower TTL because of plan restrictions, you can now increase it up to your new plan's maximum.
- **Downgrading:** Any template with a TTL exceeding the new plan's maximum is automatically capped. Existing documents from those templates have their expiration dates recalculated, which may cause documents to expire sooner than originally expected.

See [Changing My Plan](https://pdfmonkey.io/docs/pricing-and-billing/changing-my-plan.md) for a broader overview of how plan changes affect your account.

## Manual deletion

If you prefer to delete documents on your own schedule rather than relying on TTL, you have two options:

1. **Dashboard:** Open the document and click the delete button.
2. **API:** Send a `DELETE` request to `/api/v1/documents/:id`. See the [API reference](https://pdfmonkey.io/docs/api/documents.md#delete-a-document) for details.

Manual deletion removes the same data as automatic TTL deletion.

## Frequently asked questions

**Why was my document deleted before the TTL I set?**

If you recently downgraded your plan, PDFMonkey may have recalculated expiration dates for existing documents. A template set to "1 week" on a Pro plan that is downgraded to Starter (1-day maximum) sees its documents' TTL shortened accordingly.

**Can I set different TTL values for different templates?**

Yes. TTL is a per-template setting. Each template in your account can have its own retention period, within your plan's limits.

**Does TTL apply to failed documents?**

No. Only documents with a `success` [status](https://pdfmonkey.io/docs/generating-documents/document-statuses.md) receive an expiration date. Failed documents are not automatically deleted by the TTL system.

**Is there an API to check when a document expires?**

The document object does not expose the `expires_at` field directly. However, you can calculate it from the template's `ttl` value and the document's `updated_at` timestamp.

## Related pages

- [Document Statuses and Lifecycle](https://pdfmonkey.io/docs/generating-documents/document-statuses.md) -- understand when documents become eligible for auto-deletion
- [The Download URL](https://pdfmonkey.io/docs/generating-documents/download-url.md) -- save files to your own storage before they expire
- [Permanent Share Links](https://pdfmonkey.io/docs/generating-documents/share-links.md) -- how deletion affects share links
- [Our Plans](https://pdfmonkey.io/docs/pricing-and-billing/our-plans.md) -- plan-based retention limits at a glance
- [Changing My Plan](https://pdfmonkey.io/docs/pricing-and-billing/changing-my-plan.md) -- what happens to TTL settings when you switch plans
- [Data Storage and Retention](https://pdfmonkey.io/docs/account-and-security/data-storage-and-retention.md) -- broader overview of what PDFMonkey stores
- [API: Templates](https://pdfmonkey.io/docs/api/templates.md) -- set TTL when creating or updating a template
- [API: Documents](https://pdfmonkey.io/docs/api/documents.md#delete-a-document) -- delete documents programmatically


## FAQ

**How long does PDFMonkey keep my generated documents?**

It depends on your plan and TTL setting. Free and Starter plans retain documents for up to 1 day. Pro allows up to 7 days. Pro+ and Premium offer unlimited retention. Within those limits, you set the exact TTL per template.

**What data is deleted when a document expires?**

When a document is deleted (manually or via TTL), PDFMonkey removes the generated file from storage and clears the payload and meta data. The document no longer appears in the API or dashboard.

**Can I delete documents manually instead of using TTL?**

Yes. You can delete documents from the PDFMonkey dashboard or by calling the DELETE /api/v1/documents/:id endpoint. Manual deletion removes the same data as automatic TTL deletion.

**What happens to my TTL settings if I downgrade my plan?**

When you downgrade, any template with a TTL exceeding your new plan's maximum is automatically capped to that maximum. Existing documents from those templates have their expiration dates recalculated accordingly.


---

# Webhooks: Receive Real-Time Document Generation Notifications

Source: https://pdfmonkey.io/docs/generating-documents/webhooks.md
Webhooks let you receive an HTTP notification whenever a document finishes generating, so you can react immediately without polling the API. PDFMonkey uses [Svix](https://www.svix.com/) to deliver webhooks with automatic retries and signature verification.

This page covers [event types](#event-types), the [webhook payload format](#webhook-payload), how to [configure endpoint routing](#set-up-a-workspace-wide-webhook) (workspace-wide, template-specific, or custom channels), and how to [verify webhook signatures](#verify-webhook-signatures).

## Event types

PDFMonkey fires two webhook event types:

| Event | When it fires |
|:------|:--------------|
| `documents.generation.success` | A document has been generated successfully. The `download_url` is available. |
| `documents.generation.failure` | A document failed to generate. The `failure_cause` field describes what went wrong. |

Subscribe to one or both depending on your needs. Most integrations subscribe to `documents.generation.success` at minimum.

## Webhook payload

Every webhook delivers a [DocumentCard](https://pdfmonkey.io/docs/api/documents.md#the-documentcard-object) object wrapped in a `document` key:

```json title="Webhook payload"
{
  "document": {
    "id": "a5e86d72-f5b7-43d4-a04e-8b7e08e6741c",
    "app_id": "d6b4e8f2-7a3c-4d1e-9f5b-2c8a1d3e6f90",
    "created_at": "2050-03-13T12:34:56.181+02:00",
    "document_template_id": "2903f5b4-623b-4e10-b2e3-dc7e2e67ea39",
    "document_template_identifier": "My Invoice Template",
    "download_url": "https://pdfmonkey.s3.eu-west-1.amazonaws.com/...",
    "failure_cause": null,
    "filename": "2050-03-14 Peter Parker.pdf",
    "meta": {
      "_filename": "2050-03-14 Peter Parker.pdf",
      "clientRef": "spidey-616"
    },
    "output_type": "pdf",
    "preview_url": "https://preview.pdfmonkey.io/...",
    "public_share_link": null,
    "status": "success",
    "updated_at": "2050-03-13T12:34:59.412+02:00"
  }
}
```

> [!NOTE]
> **DocumentCard, not Document**
>
> The webhook payload is a **DocumentCard**, not a full Document. It does not include the `payload` (dynamic data), `generation_logs`, or `checksum` fields. If you need to pass data through to your webhook handler, use the `meta` field when creating the document. See [The DocumentCard Object](https://pdfmonkey.io/docs/api/documents.md#the-documentcard-object) for a full attribute reference.


## Set up a workspace-wide webhook

To receive notifications for every document generated in a workspace:

1. Click the **Webhooks** link in the main navigation.
2. Click the **+ Add Endpoint** button.
3. Enter your endpoint URL.
4. Select the event type(s) you want to receive (`documents.generation.success`, `documents.generation.failure`, or both).

Your endpoint is now called whenever any document in the workspace finishes generating.

## Set up a template-specific webhook

In many cases (particularly when using no-code platforms like [Zapier](https://pdfmonkey.io/docs/integrations/zapier.md), [Make](https://pdfmonkey.io/docs/integrations/make.md), or [n8n](https://pdfmonkey.io/docs/integrations/n8n.md)), you need a webhook that fires only for a specific template.

1. Copy the **ID** of the template you want to target.
2. Click the **Webhooks** link in the main navigation.
3. Click the **+ Add Endpoint** button.
4. Enter your endpoint URL and select the event type(s).
5. In the **channels** field, add `template-YOUR_TEMPLATE_ID`.

``` title="Channel example"
template-07C63E0B-620F-44A9-AF9F-4CA0DA025A0A
```

Your endpoint is now called only when a document is generated from that specific template.

> [!WARNING]
> **Channels are case-sensitive**
>
> When adding a template or folder ID to the channels list, always paste it in **upper-case**. A lower-case ID will silently fail to match, and your endpoint will never be called.


### Target multiple templates or a folder

If you need the same webhook endpoint for several templates but not all of them, you can add up to **3 channels** to a single endpoint.

If 3 channels are not enough, group the templates in a folder and use the folder ID as a channel. This way, any template in that folder triggers the webhook.

Follow the same steps as above, but add `folder-YOUR_FOLDER_ID` in the channels list:

``` title="Channel example"
folder-440DA20B-C5A0-A0A9-C62F-4070FAF963EA
```

### Custom channels via meta

You can route webhooks dynamically on a per-document basis by setting the `_webhook_channel` key in the document's `meta` field. This adds an extra channel to the webhook notification for that specific document.

```json title="Setting a custom webhook channel via the API"
{
  "document": {
    "document_template_id": "2903f5b4-623b-4e10-b2e3-dc7e2e67ea39",
    "payload": "{}",
    "status": "pending",
    "meta": "{\"_webhook_channel\": \"order-42\"}"
  }
}
```

Then configure a webhook endpoint with `order-42` as a channel. Only documents that include this value in their `meta` will trigger that endpoint.

> [!TIP]
> **Combine with template channels**
>
> A document&#39;s webhook notification always includes its template channel (and folder channel, if applicable) in addition to any custom channel from `meta`. This means a single webhook event can match multiple endpoints.


## Verify webhook signatures

Because webhooks are HTTP requests sent to a public URL, an attacker could impersonate PDFMonkey by sending a fake request to your endpoint. To prevent this, Svix signs every webhook with a unique secret key for each endpoint.

You should verify the signature on every incoming webhook before processing it. Svix provides libraries for popular languages that handle verification in a few lines of code.

Learn how to verify signatures in [Svix's verification documentation](https://docs.svix.com/receiving/verifying-payloads/how).

> [!CAUTION]
> **Always verify in production**
>
> Skipping signature verification exposes your endpoint to spoofed requests. Always verify the webhook signature before acting on the payload.


## Frequently asked questions

**Do webhooks work with image generation?**

Yes. Webhooks fire for all [output formats](https://pdfmonkey.io/docs/generating-documents/output-format.md) (PDF, PNG, JPG, WebP). The event types are the same regardless of output type.

**Is the `download_url` in the webhook payload permanent?**

No. The `download_url` is a temporary signed link valid for 1 hour. Download the file immediately when you receive the webhook, or fetch a fresh URL later via the API. See [The Download URL](https://pdfmonkey.io/docs/generating-documents/download-url.md) for details.

**Does the webhook include the original dynamic data (payload)?**

No. The webhook delivers a [DocumentCard](https://pdfmonkey.io/docs/api/documents.md#the-documentcard-object), which omits the `payload` field. Store any data you need in the `meta` field when creating the document; `meta` is included in the webhook.

**What happens if my endpoint is down?**

Svix automatically retries failed deliveries with exponential backoff over several hours. You can monitor delivery attempts and manually replay failed messages from the **Webhooks** section in the PDFMonkey dashboard.

**How do I test webhooks during development?**

Use a tunneling service like [ngrok](https://ngrok.com/) or [localtunnel](https://theboringtech.io/localtunnel/) to expose your local server to the internet. Point your webhook endpoint at the tunnel URL, then generate a test document from the [Dashboard](https://pdfmonkey.io/docs/generating-documents/using-the-dashboard.md).

**Can I use the synchronous endpoint instead of webhooks?**

Yes. The `/api/v1/documents/sync` endpoint waits for generation to complete and returns the result in a single request. This is convenient for prototyping but has a 6-minute timeout. For production workloads, webhooks are more reliable and scalable. See [Synchronous Generation](https://pdfmonkey.io/docs/api/documents.md#synchronous-generation).

## Related pages

- [Document Statuses and Lifecycle](https://pdfmonkey.io/docs/generating-documents/document-statuses.md) -- understand when webhooks fire in the document lifecycle
- [The Download URL](https://pdfmonkey.io/docs/generating-documents/download-url.md) -- how temporary download links work and how to refresh them
- [API Documents reference](https://pdfmonkey.io/docs/api/documents.md) -- full endpoint and field documentation
- [The DocumentCard Object](https://pdfmonkey.io/docs/api/documents.md#the-documentcard-object) -- complete attribute reference for webhook payloads
- [Custom Filename](https://pdfmonkey.io/docs/generating-documents/custom-filename.md) -- use the `meta` field to set filenames and pass data through to webhooks
- [Generate Documents with the API](https://pdfmonkey.io/docs/generating-documents/api-pdf-generation.md) -- end-to-end asynchronous generation workflow
- [Generate Documents with No-Code Integrations](https://pdfmonkey.io/docs/generating-documents/using-an-integration.md) -- use webhooks with Zapier, Make, or n8n


## FAQ

**What data does PDFMonkey send in a webhook?**

PDFMonkey sends a DocumentCard object wrapped in a "document" key. It includes the document ID, status, download URL, filename, meta, output type, template ID, and more. The payload does not include the original dynamic data — use the meta field to pass through any data you need in the webhook.

**How do I verify that a webhook really comes from PDFMonkey?**

PDFMonkey uses Svix to deliver webhooks. Every webhook is signed with a unique key for each endpoint. You can verify the signature using Svix's official libraries for Node.js, Python, Ruby, Go, and other languages.

**Can I receive webhooks for only specific templates?**

Yes. When creating a webhook endpoint, add a channel in the format template-YOUR_TEMPLATE_ID to filter notifications to a specific template. You can also use folder-YOUR_FOLDER_ID to receive webhooks for all templates in a folder.

**Does PDFMonkey send webhooks for failed documents?**

Yes. PDFMonkey fires two event types: documents.generation.success when a document is generated successfully, and documents.generation.failure when generation fails. Subscribe to both to handle errors in your integration.

**What happens if my webhook endpoint is down?**

Svix automatically retries failed deliveries with exponential backoff over several hours. You can monitor delivery attempts and manually replay failed messages from the Webhooks section in the PDFMonkey dashboard.



---

# API Authentication

Source: https://pdfmonkey.io/docs/api/authentication.mdEvery request to the PDFMonkey API must include your secret API key. This page explains how to find your key, send it with requests, and verify that authentication works.

## Find your API secret key

Your API secret key is available on the dedicated API Key page in the PDFMonkey Dashboard, accessible directly from the sidebar.

> [!WARNING]
> **Keep your key secret**
>
> Your API secret key carries the same privileges as your account. Do not share it publicly or commit it to version control. If you believe your key has been compromised, regenerate it from the API Key page.


## Send your key with requests

Pass your key in the `Authorization` HTTP header, prefixed with `Bearer`:

```http
Authorization: Bearer YOUR_SECRET_KEY
```

## Make a test API call

To verify that authentication works, call the `current_user` endpoint:

```http
GET https://api.pdfmonkey.io/api/v1/current_user
Authorization: Bearer YOUR_SECRET_KEY
```

Using curl, the request looks like this:

```bash
curl https://api.pdfmonkey.io/api/v1/current_user \
  -H "Authorization: Bearer YOUR_SECRET_KEY"
```

A successful response returns your account information:

```json
{
  "current_user": {
    "id": "12345678-90ab-cdef-1234-567890abcdef",
    "auth_token": "1234567890ABCDEF1234",
    "available_documents": 300,
    "created_at": "2022-01-01T12:34:56.123+00:00",
    "current_plan": "free",
    "current_plan_interval": "month",
    "desired_name": "Jane Doe",
    "email": "jane.doe@example.com",
    "lang": "en",
    "paying_customer": false,
    "trial_ends_on": "2022-01-15",
    "updated_at": "2022-01-01T12:34:56.123+00:00",
    "block_resources": true,
    "share_links": false
  }
}
```

### Authentication errors

If the key is missing or invalid, the API returns a `401 Unauthorized` response:

```json
{
  "errors": [
    {
      "status": "401",
      "title": "Unauthorized",
      "detail": "We were unable to authenticate you based on the provided API key. Please verify that you provided the intended key."
    }
  ]
}
```

## Next steps

Now that you can authenticate, you are ready to:

- [Generate your first document](https://pdfmonkey.io/docs/api/documents.md#create-a-document) using the Documents API
- [Generate a PDF from the API](https://pdfmonkey.io/docs/generating-documents/api-pdf-generation.md) with step-by-step examples in multiple languages
- [Set up webhooks](https://pdfmonkey.io/docs/generating-documents/webhooks.md) to get notified when your documents are ready


## FAQ

**How do I authenticate with the PDFMonkey API?**

Pass your secret API key in the Authorization HTTP header as a Bearer token. The format is: Authorization: Bearer YOUR_SECRET_KEY. Every request to the PDFMonkey API requires this header.

**Where do I find my PDFMonkey API key?**

Your API secret key is available on the API Key page in the PDFMonkey Dashboard, accessible directly from the sidebar.

**What should I do if my PDFMonkey API key is compromised?**

Regenerate it immediately from the API Key page in the Dashboard. The old key will stop working and a new one will be issued.


---

# Documents API: Create, List, and Manage Generated Documents

Source: https://pdfmonkey.io/docs/api/documents.mdComplete API reference for creating, retrieving, updating, and deleting documents in PDFMonkey.

## Quick start

Generation is asynchronous: you create a document, then check its status until it's ready.

```bash
# 1. Create a document and queue it for generation
curl https://api.pdfmonkey.io/api/v1/documents \
  -X POST \
  -H 'Authorization: Bearer YOUR_SECRET_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "document": {
      "document_template_id": "YOUR_TEMPLATE_ID",
      "status": "pending",
      "payload": { "name": "Jane Doe" }
    }
  }'
# Returns a document with "status": "pending" and "download_url": null

# 2. Poll the document status until it reaches "success"
curl -H 'Authorization: Bearer YOUR_SECRET_KEY' \
  https://api.pdfmonkey.io/api/v1/document_cards/DOCUMENT_ID
# Once status is "success", read the download_url from the response
```

Setting `"status": "pending"` queues the document for generation immediately. The file isn't ready yet at this point — you need to poll the document or set up a [webhook](https://pdfmonkey.io/docs/generating-documents/webhooks.md) to know when it's done. Once the status reaches `success`, the `download_url` field contains a signed link to the generated file.

Read on for the full details, including the [synchronous endpoint](#synchronous-generation) that waits for the result in a single request.

## Authentication

All requests require a Bearer token in the `Authorization` header:

```
Authorization: Bearer YOUR_SECRET_KEY
```

See [Authentication](https://pdfmonkey.io/docs/api/authentication.md) for how to find your API key and manage access tokens.

## Create a document

**`POST /api/v1/documents`**

Creates a new document. Set `status` to `"pending"` to queue generation immediately, or omit it (defaults to `"draft"`) to generate later.

### Parameters

All parameters are nested under a `document` key.

| Name | Type | Required | Description |
|:--- |:--- |:--- |:--- |
| `document_template_id` | String (UUID) | **Yes** | ID of the template to use for generation. |
| `payload` | Object or String | No | The [dynamic data](https://pdfmonkey.io/docs/code-templates/defining-dynamic-data.md) used to build the document. Must be a JSON object (not an array). Can be passed as a JSON object or a JSON string. |
| `meta` | Object or String | No | Metadata to attach to the document. Supports [special keys](https://pdfmonkey.io/docs/generating-documents/custom-filename.md) like `_filename`. Must be a JSON object. Max 200 KB. |
| `status` | String | No | `"draft"` (default) or `"pending"`. Set to `"pending"` to trigger generation on creation. |

> [!TIP]
> Set `&#34;status&#34;: &#34;pending&#34;` in your create request to generate the document in one step. Without it, the document is created as a draft and you must [update it later](#update-a-document) to trigger generation.


### Request








**curl**

```bash
curl https://api.pdfmonkey.io/api/v1/documents \
  -X POST \
  -H &#39;Authorization: Bearer YOUR_SECRET_KEY&#39; \
  -H &#39;Content-Type: application/json&#39; \
  -d &#39;{
    &#34;document&#34;: {
      &#34;document_template_id&#34;: &#34;2903f5b4-623b-4e10-b2e3-dc7e2e67ea39&#34;,
      &#34;status&#34;: &#34;pending&#34;,
      &#34;payload&#34;: {
        &#34;clientName&#34;: &#34;Peter Parker&#34;,
        &#34;orderDate&#34;: &#34;2050-03-14&#34;,
        &#34;products&#34;: [
          { &#34;name&#34;: &#34;Spider silk&#34;, &#34;quantity&#34;: 12, &#34;unitPrice&#34;: 123.50 },
          { &#34;name&#34;: &#34;Spandex fabric&#34;, &#34;quantity&#34;: 2, &#34;unitPrice&#34;: 28.90 }
        ]
      },
      &#34;meta&#34;: {
        &#34;_filename&#34;: &#34;2050-03-14 Peter Parker.pdf&#34;,
        &#34;clientRef&#34;: &#34;spidey-616&#34;
      }
    }
  }&#39;
```

**Ruby**

```ruby
document = Pdfmonkey::Document.generate(
  document_template_id: &#39;2903f5b4-623b-4e10-b2e3-dc7e2e67ea39&#39;,
  payload: {
    clientName: &#39;Peter Parker&#39;,
    orderDate: &#39;2050-03-14&#39;,
    products: [
      { name: &#39;Spider silk&#39;, quantity: 12, unitPrice: 123.50 },
      { name: &#39;Spandex fabric&#39;, quantity: 2, unitPrice: 28.90 }
    ]
  },
  meta: {
    _filename: &#39;2050-03-14 Peter Parker.pdf&#39;,
    clientRef: &#39;spidey-616&#39;
  }
)

document.status # =&gt; &#39;pending&#39;
```

**Node.js**

```javascript
const response = await fetch(&#39;https://api.pdfmonkey.io/api/v1/documents&#39;, {
  method: &#39;POST&#39;,
  headers: {
    &#39;Authorization&#39;: &#39;Bearer YOUR_SECRET_KEY&#39;,
    &#39;Content-Type&#39;: &#39;application/json&#39;,
  },
  body: JSON.stringify({
    document: {
      document_template_id: &#39;2903f5b4-623b-4e10-b2e3-dc7e2e67ea39&#39;,
      status: &#39;pending&#39;,
      payload: {
        clientName: &#39;Peter Parker&#39;,
        orderDate: &#39;2050-03-14&#39;,
        products: [
          { name: &#39;Spider silk&#39;, quantity: 12, unitPrice: 123.50 },
          { name: &#39;Spandex fabric&#39;, quantity: 2, unitPrice: 28.90 },
        ],
      },
      meta: {
        _filename: &#39;2050-03-14 Peter Parker.pdf&#39;,
        clientRef: &#39;spidey-616&#39;,
      },
    },
  }),
});

const data = await response.json();
console.log(data);
```

**Python**

```python
import requests

response = requests.post(
    &#39;https://api.pdfmonkey.io/api/v1/documents&#39;,
    headers={
        &#39;Authorization&#39;: &#39;Bearer YOUR_SECRET_KEY&#39;,
    },
    json={
        &#39;document&#39;: {
            &#39;document_template_id&#39;: &#39;2903f5b4-623b-4e10-b2e3-dc7e2e67ea39&#39;,
            &#39;status&#39;: &#39;pending&#39;,
            &#39;payload&#39;: {
                &#39;clientName&#39;: &#39;Peter Parker&#39;,
                &#39;orderDate&#39;: &#39;2050-03-14&#39;,
                &#39;products&#39;: [
                    {&#39;name&#39;: &#39;Spider silk&#39;, &#39;quantity&#39;: 12, &#39;unitPrice&#39;: 123.50},
                    {&#39;name&#39;: &#39;Spandex fabric&#39;, &#39;quantity&#39;: 2, &#39;unitPrice&#39;: 28.90},
                ],
            },
            &#39;meta&#39;: {
                &#39;_filename&#39;: &#39;2050-03-14 Peter Parker.pdf&#39;,
                &#39;clientRef&#39;: &#39;spidey-616&#39;,
            },
        },
    },
)

print(response.json())
```

**PHP**

```php
&lt;?php
$ch = curl_init(&#39;https://api.pdfmonkey.io/api/v1/documents&#39;);

curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER =&gt; true,
    CURLOPT_POST =&gt; true,
    CURLOPT_HTTPHEADER =&gt; [
        &#39;Authorization: Bearer YOUR_SECRET_KEY&#39;,
        &#39;Content-Type: application/json&#39;,
    ],
    CURLOPT_POSTFIELDS =&gt; json_encode([
        &#39;document&#39; =&gt; [
            &#39;document_template_id&#39; =&gt; &#39;2903f5b4-623b-4e10-b2e3-dc7e2e67ea39&#39;,
            &#39;status&#39; =&gt; &#39;pending&#39;,
            &#39;payload&#39; =&gt; [
                &#39;clientName&#39; =&gt; &#39;Peter Parker&#39;,
                &#39;orderDate&#39; =&gt; &#39;2050-03-14&#39;,
                &#39;products&#39; =&gt; [
                    [&#39;name&#39; =&gt; &#39;Spider silk&#39;, &#39;quantity&#39; =&gt; 12, &#39;unitPrice&#39; =&gt; 123.50],
                    [&#39;name&#39; =&gt; &#39;Spandex fabric&#39;, &#39;quantity&#39; =&gt; 2, &#39;unitPrice&#39; =&gt; 28.90],
                ],
            ],
            &#39;meta&#39; =&gt; [
                &#39;_filename&#39; =&gt; &#39;2050-03-14 Peter Parker.pdf&#39;,
                &#39;clientRef&#39; =&gt; &#39;spidey-616&#39;,
            ],
        ],
    ]),
]);

$response = curl_exec($ch);
curl_close($ch);

echo $response;
```



### Response

```json title="201 Created"
{
  "document": {
    "id": "a5e86d72-f5b7-43d4-a04e-8b7e08e6741c",
    "app_id": "d6b4e8f2-7a3c-4d1e-9f5b-2c8a1d3e6f90",
    "checksum": "c230530f6f0aa32900af0924cf228e5c",
    "created_at": "2050-03-13T12:34:56.181+02:00",
    "document_template_id": "2903f5b4-623b-4e10-b2e3-dc7e2e67ea39",
    "download_url": null,
    "failure_cause": null,
    "filename": null,
    "generation_logs": [],
    "meta": {
      "_filename": "2050-03-14 Peter Parker.pdf",
      "clientRef": "spidey-616"
    },
    "output_type": "pdf",
    "payload": {
      "clientName": "Peter Parker",
      "orderDate": "2050-03-14",
      "products": [
        { "name": "Spider silk", "quantity": 12, "unitPrice": 123.50 },
        { "name": "Spandex fabric", "quantity": 2, "unitPrice": 28.90 }
      ]
    },
    "preview_url": "https://preview.pdfmonkey.io/pdf/web/viewer.html?file=...",
    "public_share_link": null,
    "status": "pending",
    "updated_at": "2050-03-13T12:34:56.181+02:00"
  }
}
```

### Validation errors

If required fields are missing or invalid, the API returns a `422 Unprocessable Entity`:

```json title="422 Unprocessable Entity"
{
  "errors": {
    "document_template_id": ["can't be blank"]
  }
}
```

## Synchronous generation

**`POST /api/v1/documents/sync`**

A convenience wrapper that creates a document and polls for completion server-side, so you get the finished result in a single request. The response is a [DocumentCard](#the-documentcard-object) (not a Document). For a guided walkthrough, see [Generate Documents with the API](https://pdfmonkey.io/docs/generating-documents/api-pdf-generation.md).

This endpoint accepts the same parameters as [Create a document](#create-a-document). You must set `"status": "pending"` for generation to start.

### When to use sync vs async

| | Async | Sync |
|:--- |:--- |:--- |
| **Response** | Returns immediately | Waits until generation completes |
| **Getting the result** | Poll or use [webhooks](https://pdfmonkey.io/docs/generating-documents/webhooks.md) | Included in the response |
| **Response object** | [Document](#the-document-object) | [DocumentCard](#the-documentcard-object) |
| **Scales to high volume** | Yes | No — one open request per document |
| **Timeout** | None | 6 minutes |
| **Best for** | Production pipelines, batch generation | Low-volume or interactive use cases |

> [!WARNING]
> The sync endpoint will wait up to 6 minutes for generation to complete. For production pipelines or batch generation, prefer async generation with [webhooks](https://pdfmonkey.io/docs/generating-documents/webhooks.md).


### Request








**curl**

```bash
curl https://api.pdfmonkey.io/api/v1/documents/sync \
  -X POST \
  -H &#39;Authorization: Bearer YOUR_SECRET_KEY&#39; \
  -H &#39;Content-Type: application/json&#39; \
  -d &#39;{
    &#34;document&#34;: {
      &#34;document_template_id&#34;: &#34;2903f5b4-623b-4e10-b2e3-dc7e2e67ea39&#34;,
      &#34;status&#34;: &#34;pending&#34;,
      &#34;payload&#34;: {
        &#34;clientName&#34;: &#34;Peter Parker&#34;,
        &#34;orderDate&#34;: &#34;2050-03-14&#34;,
        &#34;products&#34;: [
          { &#34;name&#34;: &#34;Spider silk&#34;, &#34;quantity&#34;: 12, &#34;unitPrice&#34;: 123.50 },
          { &#34;name&#34;: &#34;Spandex fabric&#34;, &#34;quantity&#34;: 2, &#34;unitPrice&#34;: 28.90 }
        ]
      },
      &#34;meta&#34;: {
        &#34;_filename&#34;: &#34;2050-03-14 Peter Parker.pdf&#34;,
        &#34;clientRef&#34;: &#34;spidey-616&#34;
      }
    }
  }&#39;
```

**Ruby**

```ruby
document = Pdfmonkey::Document.generate!(
  document_template_id: &#39;2903f5b4-623b-4e10-b2e3-dc7e2e67ea39&#39;,
  payload: {
    clientName: &#39;Peter Parker&#39;,
    orderDate: &#39;2050-03-14&#39;,
    products: [
      { name: &#39;Spider silk&#39;, quantity: 12, unitPrice: 123.50 },
      { name: &#39;Spandex fabric&#39;, quantity: 2, unitPrice: 28.90 }
    ]
  },
  meta: {
    _filename: &#39;2050-03-14 Peter Parker.pdf&#39;,
    clientRef: &#39;spidey-616&#39;
  }
)

document.status       # =&gt; &#39;success&#39;
document.download_url # =&gt; &#39;https://…&#39;
```

**Node.js**

```javascript
const response = await fetch(&#39;https://api.pdfmonkey.io/api/v1/documents/sync&#39;, {
  method: &#39;POST&#39;,
  headers: {
    &#39;Authorization&#39;: &#39;Bearer YOUR_SECRET_KEY&#39;,
    &#39;Content-Type&#39;: &#39;application/json&#39;,
  },
  body: JSON.stringify({
    document: {
      document_template_id: &#39;2903f5b4-623b-4e10-b2e3-dc7e2e67ea39&#39;,
      status: &#39;pending&#39;,
      payload: {
        clientName: &#39;Peter Parker&#39;,
        orderDate: &#39;2050-03-14&#39;,
        products: [
          { name: &#39;Spider silk&#39;, quantity: 12, unitPrice: 123.50 },
          { name: &#39;Spandex fabric&#39;, quantity: 2, unitPrice: 28.90 },
        ],
      },
      meta: {
        _filename: &#39;2050-03-14 Peter Parker.pdf&#39;,
        clientRef: &#39;spidey-616&#39;,
      },
    },
  }),
});

const data = await response.json();
console.log(data.document_card.download_url);
```

**Python**

```python
import requests

response = requests.post(
    &#39;https://api.pdfmonkey.io/api/v1/documents/sync&#39;,
    headers={
        &#39;Authorization&#39;: &#39;Bearer YOUR_SECRET_KEY&#39;,
    },
    json={
        &#39;document&#39;: {
            &#39;document_template_id&#39;: &#39;2903f5b4-623b-4e10-b2e3-dc7e2e67ea39&#39;,
            &#39;status&#39;: &#39;pending&#39;,
            &#39;payload&#39;: {
                &#39;clientName&#39;: &#39;Peter Parker&#39;,
                &#39;orderDate&#39;: &#39;2050-03-14&#39;,
                &#39;products&#39;: [
                    {&#39;name&#39;: &#39;Spider silk&#39;, &#39;quantity&#39;: 12, &#39;unitPrice&#39;: 123.50},
                    {&#39;name&#39;: &#39;Spandex fabric&#39;, &#39;quantity&#39;: 2, &#39;unitPrice&#39;: 28.90},
                ],
            },
            &#39;meta&#39;: {
                &#39;_filename&#39;: &#39;2050-03-14 Peter Parker.pdf&#39;,
                &#39;clientRef&#39;: &#39;spidey-616&#39;,
            },
        },
    },
    timeout=400,
)

data = response.json()
print(data[&#39;document_card&#39;][&#39;download_url&#39;])
```

**PHP**

```php
&lt;?php
$ch = curl_init(&#39;https://api.pdfmonkey.io/api/v1/documents/sync&#39;);

curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER =&gt; true,
    CURLOPT_POST =&gt; true,
    CURLOPT_TIMEOUT =&gt; 400,
    CURLOPT_HTTPHEADER =&gt; [
        &#39;Authorization: Bearer YOUR_SECRET_KEY&#39;,
        &#39;Content-Type: application/json&#39;,
    ],
    CURLOPT_POSTFIELDS =&gt; json_encode([
        &#39;document&#39; =&gt; [
            &#39;document_template_id&#39; =&gt; &#39;2903f5b4-623b-4e10-b2e3-dc7e2e67ea39&#39;,
            &#39;status&#39; =&gt; &#39;pending&#39;,
            &#39;payload&#39; =&gt; [
                &#39;clientName&#39; =&gt; &#39;Peter Parker&#39;,
                &#39;orderDate&#39; =&gt; &#39;2050-03-14&#39;,
                &#39;products&#39; =&gt; [
                    [&#39;name&#39; =&gt; &#39;Spider silk&#39;, &#39;quantity&#39; =&gt; 12, &#39;unitPrice&#39; =&gt; 123.50],
                    [&#39;name&#39; =&gt; &#39;Spandex fabric&#39;, &#39;quantity&#39; =&gt; 2, &#39;unitPrice&#39; =&gt; 28.90],
                ],
            ],
            &#39;meta&#39; =&gt; [
                &#39;_filename&#39; =&gt; &#39;2050-03-14 Peter Parker.pdf&#39;,
                &#39;clientRef&#39; =&gt; &#39;spidey-616&#39;,
            ],
        ],
    ]),
]);

$response = curl_exec($ch);
curl_close($ch);

$data = json_decode($response, true);
echo $data[&#39;document_card&#39;][&#39;download_url&#39;];
```



### Response

> [!NOTE]
> The sync endpoint returns a **DocumentCard**, not a Document. The result is nested under `document_card` and does not include `payload` or `generation_logs`.


```json title="200 OK"
{
  "document_card": {
    "app_id": "d6b4e8f2-7a3c-4d1e-9f5b-2c8a1d3e6f90",
    "created_at": "2050-03-13T12:34:56.181+02:00",
    "document_template_id": "2903f5b4-623b-4e10-b2e3-dc7e2e67ea39",
    "document_template_identifier": "My Invoice Template",
    "download_url": "https://pdfmonkey.s3.eu-west-1.amazonaws.com/production/backend/document/a5e86d72-f5b7-43d4-a04e-8b7e08e6741c/2050-03-14-peter-parker.pdf?X-Amz-Algorithm=AWS4-HMAC-SHA256&...",
    "failure_cause": null,
    "filename": "2050-03-14 Peter Parker.pdf",
    "id": "a5e86d72-f5b7-43d4-a04e-8b7e08e6741c",
    "meta": {
      "_filename": "2050-03-14 Peter Parker.pdf",
      "clientRef": "spidey-616"
    },
    "output_type": "pdf",
    "preview_url": "https://preview.pdfmonkey.io/pdf/web/viewer.html?file=...",
    "public_share_link": null,
    "status": "success",
    "updated_at": "2050-03-13T12:34:59.412+02:00"
  }
}
```

## The Document object

The Document object is the full representation of a generated document, including its payload and generation logs.

```json title="Document"
{
  "id": "a5e86d72-f5b7-43d4-a04e-8b7e08e6741c",
  "app_id": "d6b4e8f2-7a3c-4d1e-9f5b-2c8a1d3e6f90",
  "checksum": "c230530f6f0aa32900af0924cf228e5c",
  "created_at": "2050-03-13T12:34:56.181+02:00",
  "document_template_id": "2903f5b4-623b-4e10-b2e3-dc7e2e67ea39",
  "download_url": "https://pdfmonkey.s3.eu-west-1.amazonaws.com/production/backend/document/a5e86d72-f5b7-43d4-a04e-8b7e08e6741c/2050-03-14-peter-parker.pdf?X-Amz-Algorithm=AWS4-HMAC-SHA256&...",
  "failure_cause": null,
  "filename": "2050-03-14 Peter Parker.pdf",
  "generation_logs": [
    {
      "type": "info",
      "message": "Starting PDF generation.",
      "timestamp": "Thu, 13 Mar 2050 10:34:57 GMT"
    },
    {
      "type": "info",
      "message": "Generation took 1617ms to load and render.",
      "timestamp": "Thu, 13 Mar 2050 10:34:58 GMT"
    },
    {
      "type": "info",
      "message": "Content size is 96302.",
      "timestamp": "Thu, 13 Mar 2050 10:34:59 GMT"
    }
  ],
  "meta": {
    "_filename": "2050-03-14 Peter Parker.pdf",
    "clientRef": "spidey-616"
  },
  "output_type": "pdf",
  "payload": {
    "clientName": "Peter Parker",
    "orderDate": "2050-03-14",
    "products": [
      { "name": "Spider silk", "quantity": 12, "unitPrice": 123.50 },
      { "name": "Spandex fabric", "quantity": 2, "unitPrice": 28.90 }
    ]
  },
  "preview_url": "https://preview.pdfmonkey.io/pdf/web/viewer.html?file=...",
  "public_share_link": "https://files.pdfmonkey.io/share/72BE2293-D130-4C19-9E11-C82B5CEA8C37/2050-03-14-peter-parker.pdf",
  "status": "success",
  "updated_at": "2050-03-13T12:34:59.412+02:00"
}
```

### Attributes

| Name | Type | Description |
|:--- |:--- |:--- |
| `id` | String (UUID) | Unique identifier for the document. |
| `app_id` | String (UUID) | Unique identifier of the document's workspace. |
| `checksum` | String | Internal checksum used for preview rendering. |
| `created_at` | String (ISO 8601) | Timestamp when the document was created. |
| `document_template_id` | String (UUID) | ID of the template used to generate this document. |
| `download_url` | String (URL) or `null` | Temporary signed URL to download the generated file. `null` until generation succeeds. Valid for **1 hour** (see [Download URLs](#download-urls)). |
| `failure_cause` | String or `null` | Reason for generation failure. `null` unless status is `failure`. |
| `filename` | String or `null` | Name of the generated file. `null` until generation succeeds. Controllable via the `_filename` meta key. |
| `generation_logs` | Array | Logs collected during generation. Each entry has `type` (`"info"` or `"error"`), `message`, and `timestamp`. Empty array before generation starts. |
| `meta` | Object or `null` | Arbitrary metadata attached to the document. Supports [special keys](https://pdfmonkey.io/docs/generating-documents/custom-filename.md) like `_filename`. Also accessible in no-code integrations (Zapier, Make) where `payload` is not available. |
| `output_type` | String | Output format: `"pdf"` or `"image"`. Inherited from the template. |
| `payload` | Object or `null` | The [dynamic data](https://pdfmonkey.io/docs/code-templates/defining-dynamic-data.md) used to generate the document. |
| `preview_url` | String (URL) | URL for embedding a visual preview of the document. Intended for use in an `<iframe>`, **not** for downloading. |
| `public_share_link` | String (URL) or `null` | Permanent public link to the generated file. Only available when the [Share Links](https://pdfmonkey.io/docs/generating-documents/share-links.md) feature is enabled (Pro+ plans). |
| `status` | String | Current status of the document: `draft`, `pending`, `generating`, `success`, or `failure`. See [Document Statuses and Lifecycle](https://pdfmonkey.io/docs/generating-documents/document-statuses.md). |
| `updated_at` | String (ISO 8601) | Timestamp when the document was last updated. |

## The DocumentCard object

The DocumentCard is a lightweight version of the Document. It contains the same fields **except** `payload`, `generation_logs`, and `checksum`. It also adds `document_template_identifier`.

Use DocumentCards when you do not need the full payload, they are faster and lighter. They are the object returned by list endpoints, the sync endpoint, webhooks, and no-code integrations.

> [!TIP]
> **Prefer DocumentCard over Document.**
>
> Store any data you need later in `meta` instead of (or in addition to) `payload`. That way you will never need to fetch the full Document object.


```json title="DocumentCard"
{
  "id": "a5e86d72-f5b7-43d4-a04e-8b7e08e6741c",
  "app_id": "d6b4e8f2-7a3c-4d1e-9f5b-2c8a1d3e6f90",
  "created_at": "2050-03-13T12:34:56.181+02:00",
  "document_template_id": "2903f5b4-623b-4e10-b2e3-dc7e2e67ea39",
  "document_template_identifier": "My Invoice Template",
  "download_url": "https://pdfmonkey.s3.eu-west-1.amazonaws.com/production/backend/document/a5e86d72-f5b7-43d4-a04e-8b7e08e6741c/2050-03-14-peter-parker.pdf?X-Amz-Algorithm=AWS4-HMAC-SHA256&...",
  "failure_cause": null,
  "filename": "2050-03-14 Peter Parker.pdf",
  "meta": {
    "_filename": "2050-03-14 Peter Parker.pdf",
    "clientRef": "spidey-616"
  },
  "output_type": "pdf",
  "preview_url": "https://preview.pdfmonkey.io/pdf/web/viewer.html?file=...",
  "public_share_link": "https://files.pdfmonkey.io/share/72BE2293-D130-4C19-9E11-C82B5CEA8C37/2050-03-14-peter-parker.pdf",
  "status": "success",
  "updated_at": "2050-03-13T12:34:59.412+02:00"
}
```

### Attributes

| Name | Type | Description |
|:--- |:--- |:--- |
| `id` | String (UUID) | Unique identifier for the document. |
| `app_id` | String (UUID) | Unique identifier of the document's workspace. |
| `created_at` | String (ISO 8601) | Timestamp when the document was created. |
| `document_template_id` | String (UUID) | ID of the template used to generate this document. |
| `document_template_identifier` | String | The name of the template as displayed in the dashboard. |
| `download_url` | String (URL) or `null` | Temporary signed URL to download the generated file. `null` until generation succeeds. Valid for **1 hour**. |
| `failure_cause` | String or `null` | Reason for generation failure. `null` unless status is `failure`. |
| `filename` | String or `null` | Name of the generated file. `null` until generation succeeds. |
| `meta` | Object or `null` | Arbitrary metadata attached to the document. |
| `output_type` | String | Output format: `"pdf"` or `"image"`. Inherited from the template. |
| `preview_url` | String (URL) | URL for embedding a visual preview. Not for downloading. |
| `public_share_link` | String (URL) or `null` | Permanent public link. Requires [Share Links](https://pdfmonkey.io/docs/generating-documents/share-links.md) (Pro+ plans). |
| `status` | String | Current status: `draft`, `pending`, `generating`, `success`, or `failure`. |
| `updated_at` | String (ISO 8601) | Timestamp when the document was last updated. |

### Comparison: Document vs DocumentCard

| Field | Document | DocumentCard |
|:--- |:--- |:--- |
| `payload` | Included | **Not included** |
| `generation_logs` | Included | **Not included** |
| `checksum` | Included | **Not included** |
| `document_template_identifier` | **Not included** | Included |

## Get a document

### Get a DocumentCard (recommended)

**`GET /api/v1/document_cards/{id}`**

Returns a [DocumentCard](#the-documentcard-object) for the given document. This is the recommended way to check generation status and retrieve the download URL.








**curl**

```bash
curl -H &#39;Authorization: Bearer YOUR_SECRET_KEY&#39; \
  https://api.pdfmonkey.io/api/v1/document_cards/a5e86d72-f5b7-43d4-a04e-8b7e08e6741c
```

**Ruby**

```ruby
card = Pdfmonkey::Document.fetch_card(&#39;a5e86d72-f5b7-43d4-a04e-8b7e08e6741c&#39;)

card.status       # =&gt; &#39;success&#39;
card.download_url # =&gt; &#39;https://…&#39;
```

**Node.js**

```javascript
const response = await fetch(
  &#39;https://api.pdfmonkey.io/api/v1/document_cards/a5e86d72-f5b7-43d4-a04e-8b7e08e6741c&#39;,
  {
    headers: {
      &#39;Authorization&#39;: &#39;Bearer YOUR_SECRET_KEY&#39;,
    },
  }
);

const data = await response.json();
console.log(data.document_card);
```

**Python**

```python
import requests

response = requests.get(
    &#39;https://api.pdfmonkey.io/api/v1/document_cards/a5e86d72-f5b7-43d4-a04e-8b7e08e6741c&#39;,
    headers={
        &#39;Authorization&#39;: &#39;Bearer YOUR_SECRET_KEY&#39;,
    },
)

data = response.json()
print(data[&#39;document_card&#39;])
```

**PHP**

```php
&lt;?php
$ch = curl_init(&#39;https://api.pdfmonkey.io/api/v1/document_cards/a5e86d72-f5b7-43d4-a04e-8b7e08e6741c&#39;);

curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER =&gt; true,
    CURLOPT_HTTPHEADER =&gt; [
        &#39;Authorization: Bearer YOUR_SECRET_KEY&#39;,
    ],
]);

$response = curl_exec($ch);
curl_close($ch);

$data = json_decode($response, true);
print_r($data[&#39;document_card&#39;]);
```



**Response:** `200 OK` with a `document_card` object.

### Get a full Document

**`GET /api/v1/documents/{id}`**

Returns the full [Document](#the-document-object), including `payload` and `generation_logs`. Use this only when you need those fields.








**curl**

```bash
curl -H &#39;Authorization: Bearer YOUR_SECRET_KEY&#39; \
  https://api.pdfmonkey.io/api/v1/documents/a5e86d72-f5b7-43d4-a04e-8b7e08e6741c
```

**Ruby**

```ruby
document = Pdfmonkey::Document.fetch(&#39;a5e86d72-f5b7-43d4-a04e-8b7e08e6741c&#39;)

document.status   # =&gt; &#39;success&#39;
document.payload  # =&gt; &#39;{&#34;clientName&#34;:&#34;Peter Parker&#34;,…}&#39;
```

**Node.js**

```javascript
const response = await fetch(
  &#39;https://api.pdfmonkey.io/api/v1/documents/a5e86d72-f5b7-43d4-a04e-8b7e08e6741c&#39;,
  {
    headers: {
      &#39;Authorization&#39;: &#39;Bearer YOUR_SECRET_KEY&#39;,
    },
  }
);

const data = await response.json();
console.log(data.document);
```

**Python**

```python
import requests

response = requests.get(
    &#39;https://api.pdfmonkey.io/api/v1/documents/a5e86d72-f5b7-43d4-a04e-8b7e08e6741c&#39;,
    headers={
        &#39;Authorization&#39;: &#39;Bearer YOUR_SECRET_KEY&#39;,
    },
)

data = response.json()
print(data[&#39;document&#39;])
```

**PHP**

```php
&lt;?php
$ch = curl_init(&#39;https://api.pdfmonkey.io/api/v1/documents/a5e86d72-f5b7-43d4-a04e-8b7e08e6741c&#39;);

curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER =&gt; true,
    CURLOPT_HTTPHEADER =&gt; [
        &#39;Authorization: Bearer YOUR_SECRET_KEY&#39;,
    ],
]);

$response = curl_exec($ch);
curl_close($ch);

$data = json_decode($response, true);
print_r($data[&#39;document&#39;]);
```



**Response:** `200 OK` with a `document` object.

## List documents

**`GET /api/v1/document_cards`**

Returns a paginated list of [DocumentCards](#the-documentcard-object). Results are limited to 24 items per page.

### Query parameters

| Name | Type | Description |
|:--- |:--- |:--- |
| `page[number]` | Integer | Page number (default: `1`). |
| `q[document_template_id]` | String (UUID) or Array | Filter by one or more template IDs. Accepts a single UUID or a comma-separated list. |
| `q[status]` | String | Filter by status: `draft`, `pending`, `generating`, `success`, or `failure`. See [Document Statuses](https://pdfmonkey.io/docs/generating-documents/document-statuses.md). |
| `q[workspace_id]` | String (UUID) | Filter by workspace ID. |
| `q[updated_since]` | Timestamp | Only return documents updated after this point in time. Accepts a Unix timestamp (e.g. `1640995200` for 2022-01-01 00:00:00 UTC) or an ISO 8601 string. |
| `q[search]` | String | Search by document ID or filename. If the value is a UUID, matches by exact ID; otherwise performs a partial match on filename. |








**curl**

```bash
curl -H &#39;Authorization: Bearer YOUR_SECRET_KEY&#39; \
  &#39;https://api.pdfmonkey.io/api/v1/document_cards?q[document_template_id]=2903f5b4-623b-4e10-b2e3-dc7e2e67ea39&amp;q[status]=success&amp;page[number]=1&#39;
```

**Ruby**

```ruby
cards = Pdfmonkey::Document.list_cards(
  page: 1,
  document_template_id: &#39;2903f5b4-623b-4e10-b2e3-dc7e2e67ea39&#39;,
  status: &#39;success&#39;
)

cards.each { |card| puts card.download_url }

cards.current_page # =&gt; 1
cards.total_pages  # =&gt; 1
```

**Node.js**

```javascript
const params = new URLSearchParams({
  &#39;q[document_template_id]&#39;: &#39;2903f5b4-623b-4e10-b2e3-dc7e2e67ea39&#39;,
  &#39;q[status]&#39;: &#39;success&#39;,
  &#39;page[number]&#39;: &#39;1&#39;,
});

const response = await fetch(
  `https://api.pdfmonkey.io/api/v1/document_cards?${params}`,
  {
    headers: {
      &#39;Authorization&#39;: &#39;Bearer YOUR_SECRET_KEY&#39;,
    },
  }
);

const data = await response.json();
console.log(data.document_cards);
console.log(data.meta); // Pagination info
```

**Python**

```python
import requests

response = requests.get(
    &#39;https://api.pdfmonkey.io/api/v1/document_cards&#39;,
    headers={
        &#39;Authorization&#39;: &#39;Bearer YOUR_SECRET_KEY&#39;,
    },
    params={
        &#39;q[document_template_id]&#39;: &#39;2903f5b4-623b-4e10-b2e3-dc7e2e67ea39&#39;,
        &#39;q[status]&#39;: &#39;success&#39;,
        &#39;page[number]&#39;: 1,
    },
)

data = response.json()
print(data[&#39;document_cards&#39;])
print(data[&#39;meta&#39;])  # Pagination info
```

**PHP**

```php
&lt;?php
$query = http_build_query([
    &#39;q&#39; =&gt; [
        &#39;document_template_id&#39; =&gt; &#39;2903f5b4-623b-4e10-b2e3-dc7e2e67ea39&#39;,
        &#39;status&#39; =&gt; &#39;success&#39;,
    ],
    &#39;page&#39; =&gt; [&#39;number&#39; =&gt; 1],
]);

$ch = curl_init(&#34;https://api.pdfmonkey.io/api/v1/document_cards?{$query}&#34;);

curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER =&gt; true,
    CURLOPT_HTTPHEADER =&gt; [
        &#39;Authorization: Bearer YOUR_SECRET_KEY&#39;,
    ],
]);

$response = curl_exec($ch);
curl_close($ch);

$data = json_decode($response, true);
print_r($data[&#39;document_cards&#39;]);
print_r($data[&#39;meta&#39;]); // Pagination info
```



### Response

```json title="200 OK"
{
  "document_cards": [
    {
      "id": "a5e86d72-f5b7-43d4-a04e-8b7e08e6741c",
      "app_id": "d6b4e8f2-7a3c-4d1e-9f5b-2c8a1d3e6f90",
      "created_at": "2050-03-13T12:34:56.181+02:00",
      "document_template_id": "2903f5b4-623b-4e10-b2e3-dc7e2e67ea39",
      "document_template_identifier": "My Invoice Template",
      "download_url": "https://pdfmonkey.s3.eu-west-1.amazonaws.com/...",
      "failure_cause": null,
      "filename": "2050-03-14 Peter Parker.pdf",
      "meta": {
        "_filename": "2050-03-14 Peter Parker.pdf",
        "clientRef": "spidey-616"
      },
      "output_type": "pdf",
      "preview_url": "https://preview.pdfmonkey.io/pdf/web/viewer.html?file=...",
      "public_share_link": null,
      "status": "success",
      "updated_at": "2050-03-13T12:34:59.412+02:00"
    }
  ],
  "meta": {
    "current_page": 1,
    "next_page": null,
    "prev_page": null,
    "total_pages": 1
  }
}
```

The `meta` object contains pagination information:

| Field | Type | Description |
|:--- |:--- |:--- |
| `current_page` | Integer | The current page number. |
| `next_page` | Integer or `null` | The next page number, or `null` if this is the last page. |
| `prev_page` | Integer or `null` | The previous page number, or `null` if this is the first page. |
| `total_pages` | Integer | Total number of pages available. |

## Update a document

**`PUT /api/v1/documents/{id}`**

Updates an existing document. You can change its payload, meta, or trigger generation by setting `status` to `"pending"`.

### Parameters

All parameters are nested under a `document` key.

| Name | Type | Required | Description |
|:--- |:--- |:--- |:--- |
| `document_template_id` | String (UUID) | No | Change the template. |
| `payload` | Object or String | No | Replace the dynamic data. |
| `meta` | Object or String | No | Replace the metadata. |
| `status` | String | No | Set to `"pending"` to trigger generation. |








**curl**

```bash
curl https://api.pdfmonkey.io/api/v1/documents/a5e86d72-f5b7-43d4-a04e-8b7e08e6741c \
  -X PUT \
  -H &#39;Authorization: Bearer YOUR_SECRET_KEY&#39; \
  -H &#39;Content-Type: application/json&#39; \
  -d &#39;{
    &#34;document&#34;: {
      &#34;status&#34;: &#34;pending&#34;,
      &#34;payload&#34;: { &#34;name&#34;: &#34;Mary Jane Watson&#34; }
    }
  }&#39;
```

**Ruby**

```ruby
document = Pdfmonkey::Document.fetch(&#39;a5e86d72-f5b7-43d4-a04e-8b7e08e6741c&#39;)

document.update!(
  status: &#39;pending&#39;,
  payload: { name: &#39;Mary Jane Watson&#39; }
)
```

**Node.js**

```javascript
const response = await fetch(
  &#39;https://api.pdfmonkey.io/api/v1/documents/a5e86d72-f5b7-43d4-a04e-8b7e08e6741c&#39;,
  {
    method: &#39;PUT&#39;,
    headers: {
      &#39;Authorization&#39;: &#39;Bearer YOUR_SECRET_KEY&#39;,
      &#39;Content-Type&#39;: &#39;application/json&#39;,
    },
    body: JSON.stringify({
      document: {
        status: &#39;pending&#39;,
        payload: { name: &#39;Mary Jane Watson&#39; },
      },
    }),
  }
);

const data = await response.json();
console.log(data.document);
```

**Python**

```python
import requests

response = requests.put(
    &#39;https://api.pdfmonkey.io/api/v1/documents/a5e86d72-f5b7-43d4-a04e-8b7e08e6741c&#39;,
    headers={
        &#39;Authorization&#39;: &#39;Bearer YOUR_SECRET_KEY&#39;,
    },
    json={
        &#39;document&#39;: {
            &#39;status&#39;: &#39;pending&#39;,
            &#39;payload&#39;: {&#39;name&#39;: &#39;Mary Jane Watson&#39;},
        },
    },
)

print(response.json())
```

**PHP**

```php
&lt;?php
$ch = curl_init(&#39;https://api.pdfmonkey.io/api/v1/documents/a5e86d72-f5b7-43d4-a04e-8b7e08e6741c&#39;);

curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER =&gt; true,
    CURLOPT_CUSTOMREQUEST =&gt; &#39;PUT&#39;,
    CURLOPT_HTTPHEADER =&gt; [
        &#39;Authorization: Bearer YOUR_SECRET_KEY&#39;,
        &#39;Content-Type: application/json&#39;,
    ],
    CURLOPT_POSTFIELDS =&gt; json_encode([
        &#39;document&#39; =&gt; [
            &#39;status&#39; =&gt; &#39;pending&#39;,
            &#39;payload&#39; =&gt; [&#39;name&#39; =&gt; &#39;Mary Jane Watson&#39;],
        ],
    ]),
]);

$response = curl_exec($ch);
curl_close($ch);

echo $response;
```



**Response:** `200 OK` with the updated `document` object.

## Delete a document

**`DELETE /api/v1/documents/{id}`**

Permanently deletes a document and its generated file.








**curl**

```bash
curl https://api.pdfmonkey.io/api/v1/documents/a5e86d72-f5b7-43d4-a04e-8b7e08e6741c \
  -X DELETE \
  -H &#39;Authorization: Bearer YOUR_SECRET_KEY&#39;
```

**Ruby**

```ruby
Pdfmonkey::Document.delete(&#39;a5e86d72-f5b7-43d4-a04e-8b7e08e6741c&#39;)
# =&gt; true
```

**Node.js**

```javascript
const response = await fetch(
  &#39;https://api.pdfmonkey.io/api/v1/documents/a5e86d72-f5b7-43d4-a04e-8b7e08e6741c&#39;,
  {
    method: &#39;DELETE&#39;,
    headers: {
      &#39;Authorization&#39;: &#39;Bearer YOUR_SECRET_KEY&#39;,
    },
  }
);

console.log(response.status); // 204
```

**Python**

```python
import requests

response = requests.delete(
    &#39;https://api.pdfmonkey.io/api/v1/documents/a5e86d72-f5b7-43d4-a04e-8b7e08e6741c&#39;,
    headers={
        &#39;Authorization&#39;: &#39;Bearer YOUR_SECRET_KEY&#39;,
    },
)

print(response.status_code)  # 204
```

**PHP**

```php
&lt;?php
$ch = curl_init(&#39;https://api.pdfmonkey.io/api/v1/documents/a5e86d72-f5b7-43d4-a04e-8b7e08e6741c&#39;);

curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER =&gt; true,
    CURLOPT_CUSTOMREQUEST =&gt; &#39;DELETE&#39;,
    CURLOPT_HTTPHEADER =&gt; [
        &#39;Authorization: Bearer YOUR_SECRET_KEY&#39;,
    ],
]);

curl_exec($ch);
echo curl_getinfo($ch, CURLINFO_HTTP_CODE); // 204
curl_close($ch);
```



**Response:** `204 No Content` with an empty body.

## Download URLs

Download URLs are temporary signed S3 links, valid for **1 hour**. To get a fresh URL after expiration, fetch the document again — no need to regenerate it. For permanent links, enable [Share Links](https://pdfmonkey.io/docs/generating-documents/share-links.md) (Pro+ plans).

See [Download URL](https://pdfmonkey.io/docs/generating-documents/download-url.md) for details on expiration, best practices, and troubleshooting.

## Related pages

- **[Authentication](https://pdfmonkey.io/docs/api/authentication.md)** — Find your API key and authenticate requests.
- **[Templates API](https://pdfmonkey.io/docs/api/templates.md)** — List and retrieve templates to find the `document_template_id` you need.
- **[Generate Documents with the API](https://pdfmonkey.io/docs/generating-documents/api-pdf-generation.md)** — Step-by-step guide to generating your first document.
- **[Document Statuses and Lifecycle](https://pdfmonkey.io/docs/generating-documents/document-statuses.md)** — Understand the `draft` / `pending` / `generating` / `success` / `failure` flow.
- **[Download URL](https://pdfmonkey.io/docs/generating-documents/download-url.md)** — Deep dive into download URL behavior, expiration, and best practices.
- **[Webhooks](https://pdfmonkey.io/docs/generating-documents/webhooks.md)** — Receive real-time notifications when generation completes.
- **[Custom Filename](https://pdfmonkey.io/docs/generating-documents/custom-filename.md)** — Control the filename of generated documents via the `_filename` meta key.
- **[Share Links](https://pdfmonkey.io/docs/generating-documents/share-links.md)** — Permanent public URLs for generated documents (Pro+ plans).
- **[Embedding a Preview](https://pdfmonkey.io/docs/generating-documents/embedding-a-preview.md)** — Embed a visual preview of your document in a web page.


## FAQ

**How do I generate a document with the PDFMonkey API?**

Send a POST request to /api/v1/documents with your template ID and dynamic data. Set status to "pending" to queue generation immediately. Then poll the document status or use webhooks to know when the file is ready to download.

**What is the difference between Document and DocumentCard in PDFMonkey?**

A Document is the full object including payload, generation_logs, and checksum. A DocumentCard is a lighter version without those fields but with document_template_identifier added. Use DocumentCards when you don't need the payload.

**Does PDFMonkey support synchronous document generation?**

Yes. POST to /api/v1/documents/sync to create a document and wait for the result in a single request. The endpoint has a 6-minute timeout and returns a DocumentCard.

**How long is a PDFMonkey download URL valid?**

Download URLs are temporary signed S3 URLs valid for 1 hour. After expiration, fetch the document again to get a fresh URL -- no need to regenerate.


---

# Templates API: List, Retrieve, Create, Update, and Delete Templates

Source: https://pdfmonkey.io/docs/api/templates.mdComplete API reference for listing, retrieving, creating, updating, and deleting templates in PDFMonkey.

> [!TIP]
> **Most users don&#39;t need the Templates API**
>
> Templates are typically designed in the [Dashboard](https://pdfmonkey.io/docs/generating-documents/using-the-dashboard.md) or the [visual Builder](https://pdfmonkey.io/docs/builder-templates/_index.md). The Templates API is useful when you manage templates programmatically (for example, syncing from a CI pipeline or building a custom editor). To generate documents from an existing template, see the [Documents API](https://pdfmonkey.io/docs/api/documents.md).


## Authentication

All requests require a Bearer token in the `Authorization` header:

```
Authorization: Bearer YOUR_SECRET_KEY
```

See [Authentication](https://pdfmonkey.io/docs/api/authentication.md) for how to find your API key.

## The DocumentTemplate object

A DocumentTemplate is the reusable design that defines a document's layout. It contains:

- **HTML + Liquid** for dynamic content
- **CSS / SCSS** for styling
- **Test data** for previewing in the Dashboard
- **Settings** for paper size, margins, headers, and footers

### Draft vs published properties

Each template maintains two sets of properties:

- **Draft** properties (`body_draft`, `scss_style_draft`, `settings_draft`, `sample_data_draft`, `pdf_engine_draft_id`) for content being edited in the Dashboard but not yet published.
- **Published** properties (`body`, `scss_style`, `settings`, `sample_data`, `pdf_engine_id`) used when generating documents.

When you publish a template in the Dashboard, draft values are copied to their published counterparts.

### Attributes

```json5 title="DocumentTemplate object"
{
  "id": "8ac0d8f7-dbd3-46dd-b2d3-af036a2776d9",
  "app_id": "3161c5e5-9966-4630-9b07-63f718092784",
  "identifier": "My Awesome Template",
  "edition_mode": "code",
  "output_type": "pdf",
  "body": "<p>Hello {{name}}</p>",
  "body_draft": "<p>Hello, <strong>{{name}}!</strong></p>",
  "scss_style": "p { color: green; }",
  "scss_style_draft": "p { color: purple; }",
  "sample_data": "{ \"name\": \"Peter Parker\" }",
  "sample_data_draft": "{ \"name\": \"Spider-Man\" }",
  "settings": {
    "footer": {
      "center": null,
      "content": null,
      "left": null,
      "right": "page [page]/[topage]"
    },
    "header": {
      "center": null,
      "content": null,
      "left": null,
      "right": null
    },
    "inject_javascript": false,
    "margin": {
      "bottom": 0,
      "left": 0,
      "right": 0,
      "top": 0
    },
    "orientation": "portrait",
    "paper_format": "a4",
    "paper_height": 297,
    "paper_width": 210,
    "transparent_background": false,
    "use_emojis": false,
    "use_paged": false
  },
  "settings_draft": { /* same structure as settings */ },
  "pdf_engine_id": "5c709522-90db-4aea-b49f-15aeaa7180c7",
  "pdf_engine_draft_id": "5c709522-90db-4aea-b49f-15aeaa7180c7",
  "template_folder_id": null,
  "ttl": 86400,
  "created_at": "2050-01-02T03:04:05.678+02:00",
  "updated_at": "2050-01-02T03:04:05.678+02:00",
  "auth_token": "ZCsspcSZieyfdCUHYjKW1B9D8mnrz2ck",
  "checksum": "kfYsx6xzMx3JkYxLd4LW6YeU5rkcuTxQ",
  "preview_url": "https://preview.pdfmonkey.io/pdf/..."
}
```

| Attribute | Type | Description |
|:--- |:--- |:--- |
| `id` | UUID | Unique identifier. |
| `app_id` | UUID | Unique identifier of the template's [workspace](https://pdfmonkey.io/docs/getting-started/_index.md). |
| `identifier` | String | Human-readable name (1--100 characters). |
| `edition_mode` | String | `code`, `visual` (deprecated), or `builder`. |
| `output_type` | String | `pdf` or `image`. Determines the format of generated documents. |
| `body` | String | Published HTML + Liquid content used to generate documents. |
| `body_draft` | String | Unpublished HTML + Liquid content, not yet used for generation. |
| `scss_style` | String | Published CSS or SCSS styles applied to the content. Does not apply to headers or footers. |
| `scss_style_draft` | String | Unpublished CSS or SCSS styles. |
| `sample_data` | String | Published test data. Not used for generation; serves as a rollback point for draft changes. |
| `sample_data_draft` | String | Draft JSON data used to preview the template. Not used for generation. |
| `settings` | Object | Published printing settings. See [Settings](#settings) below. |
| `settings_draft` | Object | Unpublished printing settings. See [Settings](#settings) below. |
| `pdf_engine_id` | UUID | ID of the PDF engine used when generating documents. See [PDF engines](#pdf-engines) below. |
| `pdf_engine_draft_id` | UUID | ID of the PDF engine used to preview draft content. Useful to test a new engine before switching. See [PDF engines](#pdf-engines) below. |
| `template_folder_id` | UUID or `null` | ID of a folder to group the template into. |
| `ttl` | Number | Time-to-live in seconds. Documents generated from this template are automatically deleted after this delay. See [Retention and Deletion](https://pdfmonkey.io/docs/generating-documents/retention-and-deletion.md). |
| `created_at` | String (ISO 8601) | Timestamp when the template was created. |
| `updated_at` | String (ISO 8601) | Timestamp when the template was last updated. |
| `auth_token` | String | *Internal. Not used.* |
| `checksum` | String | Internal. Used for preview cache invalidation. |
| `preview_url` | String (URL) | URL to preview the template using draft properties. Embed in an `<iframe>` or open directly. |

### Settings

The `settings` attribute (and its draft counterpart `settings_draft`) controls the layout, formatting, and behavior of generated documents.

Not all settings apply to every template configuration. The **Applies to** column indicates which edition modes and output types each setting is relevant to.

| Attribute | Type | Applies to | Description |
|:--- |:--- |:--- |:--- |
| `footer` | Object | PDF (code, builder) | Configures the footer. |
| `footer.left` / `footer.center` / `footer.right` | String | PDF (code, builder) | Content for the left, center, or right parts of the footer. Magic tokens `[page]` and `[topage]` insert the current page number and total pages. HTML + Liquid is not supported. |
| `footer.content` | String | PDF (code, builder) | Full-width footer content. Overrides `left`, `center`, and `right` when set. |
| `header` | Object | PDF (code, builder) | Configures the header. |
| `header.left` / `header.center` / `header.right` | String | PDF (code, builder) | Content for the left, center, or right parts of the header. Magic tokens `[page]` and `[topage]` can be used. HTML + Liquid is not supported. |
| `header.content` | String | PDF (code, builder) | Full-width header content. Overrides `left`, `center`, and `right` when set. |
| `inject_javascript` | Boolean | All | When `true`, the document's payload (or test data) is accessible in JavaScript via the `$docPayload` variable. Can impact performance with large payloads. **Always enabled for builder templates.** |
| `margin` | Object | PDF (code, builder) | Sets the margins of the document. |
| `margin.bottom` / `margin.left` / `margin.right` / `margin.top` | Number | PDF (code, builder) | Margin in millimeters. Defaults to `10` if set to `null` or omitted. |
| `orientation` | String | PDF (code, builder) | Page orientation: `portrait` or `landscape`. |
| `paper_format` | String | PDF (code, builder) | Paper format: `a0`, `a1`, `a2`, `a3`, `a4`, `a5`, `a6`, `letter`, or `custom`. |
| `paper_height` | Number | PDF (code, builder) | Paper height in millimeters. Only used when `paper_format` is `custom`; otherwise derived from the format. |
| `paper_width` | Number | PDF (code, builder) | Paper width in millimeters. Only used when `paper_format` is `custom`; otherwise derived from the format. |
| `transparent_background` | Boolean | Image | When `true`, the generated image has a transparent background instead of white. |
| `use_emojis` | Boolean | All | When `true`, enables emoji rendering (via [Noto Color Emoji](https://fonts.google.com/noto/specimen/Noto+Color+Emoji)) in the generated document. |
| `use_paged` | Boolean | PDF (code, builder) | Specific to [PDF Engine v3](https://pdfmonkey.io/docs/code-templates/our-engines.md). When `true`, the engine waits for Paged.js rendering to complete before generating the PDF. Other engines ignore this setting. |

### PDF engines

PDFMonkey provides multiple PDF engines, each with different capabilities. **We strongly recommend using v4**, the most recent and powerful engine. See [Our Engines](https://pdfmonkey.io/docs/code-templates/our-engines.md) for a detailed comparison.

To retrieve the list of available engines:

```bash title="Request"
curl https://api.pdfmonkey.io/api/v1/engines \
  -H "Authorization: Bearer YOUR_SECRET_KEY"
```

```json5 title="Response"
{
  "pdf_engines": [
    { "id": "5c709522-90db-4aea-b49f-15aeaa7180c7", "name": "v4", "deprecated_on": null },
    { "id": "61749ef7-6aca-4edb-84ca-685adb638c34", "name": "v3", "deprecated_on": null },
    { "id": "1f8da2ab-29c4-455c-a5fb-8771e44148c3", "name": "v2", "deprecated_on": null }
  ],
  "meta": {
    "current_page": 1,
    "next_page": null,
    "prev_page": null,
    "total_pages": 1
  }
}
```

## List templates

**`GET /api/v1/document_template_cards`**

Returns a paginated list of template cards. Template cards are lightweight objects that omit the template body, styles, and test data.

### Query parameters

| Name | Type | Required | Description |
|:--- |:--- |:--- |:--- |
| `q[workspace_id]` | String (UUID) | **Yes** | The workspace to list templates from. Also accepts `q[workspaceId]`, `q[app_id]`, or `q[appId]`. |
| `q[folders]` | String | No | Comma-separated list of folder IDs. Use `"none"` for templates not in any folder, or `"all"` (default) for all templates. |
| `page` | Integer | No | Page number for pagination. |
| `sort` | String | No | Attribute to sort by. |

### Request








**curl**

```bash
curl -H &#39;Authorization: Bearer YOUR_SECRET_KEY&#39; \
  &#39;https://api.pdfmonkey.io/api/v1/document_template_cards?q[workspace_id]=3161c5e5-9966-4630-9b07-63f718092784&#39;
```

**Ruby**

```ruby
cards = Pdfmonkey::Template.list_cards(
  workspace_id: &#39;3161c5e5-9966-4630-9b07-63f718092784&#39;
)

cards.each { |card| puts card.identifier }
```

**Node.js**

```javascript
const response = await fetch(
  &#39;https://api.pdfmonkey.io/api/v1/document_template_cards?q[workspace_id]=3161c5e5-9966-4630-9b07-63f718092784&#39;,
  {
    headers: {
      &#39;Authorization&#39;: &#39;Bearer YOUR_SECRET_KEY&#39;,
    },
  }
);

const data = await response.json();
console.log(data.document_template_cards);
```

**Python**

```python
import requests

response = requests.get(
    &#39;https://api.pdfmonkey.io/api/v1/document_template_cards&#39;,
    headers={
        &#39;Authorization&#39;: &#39;Bearer YOUR_SECRET_KEY&#39;,
    },
    params={
        &#39;q[workspace_id]&#39;: &#39;3161c5e5-9966-4630-9b07-63f718092784&#39;,
    },
)

data = response.json()
print(data[&#39;document_template_cards&#39;])
```

**PHP**

```php
&lt;?php
$ch = curl_init(&#39;https://api.pdfmonkey.io/api/v1/document_template_cards?q[workspace_id]=3161c5e5-9966-4630-9b07-63f718092784&#39;);

curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER =&gt; true,
    CURLOPT_HTTPHEADER =&gt; [
        &#39;Authorization: Bearer YOUR_SECRET_KEY&#39;,
    ],
]);

$response = curl_exec($ch);
curl_close($ch);

$data = json_decode($response, true);
print_r($data[&#39;document_template_cards&#39;]);
```



### Response

```json title="200 OK"
{
  "document_template_cards": [
    {
      "id": "8ac0d8f7-dbd3-46dd-b2d3-af036a2776d9",
      "app_id": "3161c5e5-9966-4630-9b07-63f718092784",
      "auth_token": "ZCsspcSZieyfdCUHYjKW1B9D8mnrz2ck",
      "created_at": "2050-01-02T03:04:05.678+02:00",
      "edition_mode": "code",
      "identifier": "My Awesome Template",
      "is_draft": true,
      "output_type": "pdf",
      "pdf_engine_deprecated_on": null,
      "pdf_engine_name": "v4",
      "template_folder_id": null,
      "template_folder_identifier": null,
      "updated_at": "2050-01-02T03:04:05.678+02:00"
    }
  ],
  "meta": {
    "current_page": 1,
    "next_page": null,
    "prev_page": null,
    "total_pages": 1
  }
}
```

> [!NOTE]
> **Template cards vs full templates**
>
> Template cards are lightweight: they include metadata like `identifier`, `edition_mode`, and `is_draft`, but **not** the template body, styles, or test data. To get the full template content, use [Get a template](#get-a-template).


## Get a template

**`GET /api/v1/document_templates/{id}`**

Returns the full [DocumentTemplate object](#the-documenttemplate-object) including body, styles, test data, and settings.

### Request








**curl**

```bash
curl -H &#39;Authorization: Bearer YOUR_SECRET_KEY&#39; \
  https://api.pdfmonkey.io/api/v1/document_templates/8ac0d8f7-dbd3-46dd-b2d3-af036a2776d9
```

**Ruby**

```ruby
template = Pdfmonkey::Template.fetch(&#39;8ac0d8f7-dbd3-46dd-b2d3-af036a2776d9&#39;)

puts template.identifier
puts template.body
puts template.settings
```

**Node.js**

```javascript
const response = await fetch(
  &#39;https://api.pdfmonkey.io/api/v1/document_templates/8ac0d8f7-dbd3-46dd-b2d3-af036a2776d9&#39;,
  {
    headers: {
      &#39;Authorization&#39;: &#39;Bearer YOUR_SECRET_KEY&#39;,
    },
  }
);

const data = await response.json();
console.log(data.document_template);
```

**Python**

```python
import requests

response = requests.get(
    &#39;https://api.pdfmonkey.io/api/v1/document_templates/8ac0d8f7-dbd3-46dd-b2d3-af036a2776d9&#39;,
    headers={
        &#39;Authorization&#39;: &#39;Bearer YOUR_SECRET_KEY&#39;,
    },
)

data = response.json()
print(data[&#39;document_template&#39;])
```

**PHP**

```php
&lt;?php
$ch = curl_init(&#39;https://api.pdfmonkey.io/api/v1/document_templates/8ac0d8f7-dbd3-46dd-b2d3-af036a2776d9&#39;);

curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER =&gt; true,
    CURLOPT_HTTPHEADER =&gt; [
        &#39;Authorization: Bearer YOUR_SECRET_KEY&#39;,
    ],
]);

$response = curl_exec($ch);
curl_close($ch);

$data = json_decode($response, true);
print_r($data[&#39;document_template&#39;]);
```



### Response

Returns `200 OK` with a `document_template` object:

```json title="200 OK"
{
  "document_template": {
    "id": "8ac0d8f7-dbd3-46dd-b2d3-af036a2776d9",
    "app_id": "3161c5e5-9966-4630-9b07-63f718092784",
    "identifier": "My Awesome Template",
    "edition_mode": "code",
    "output_type": "pdf",
    "body": "<p>Hello {{name}}</p>",
    "body_draft": "<p>Hello, <strong>{{name}}!</strong></p>",
    "scss_style": "p { color: green; }",
    "scss_style_draft": "p { color: purple; }",
    "sample_data": "{ \"name\": \"Peter Parker\" }",
    "sample_data_draft": "{ \"name\": \"Spider-Man\" }",
    "settings": { "...": "..." },
    "settings_draft": { "...": "..." },
    "pdf_engine_id": "5c709522-90db-4aea-b49f-15aeaa7180c7",
    "pdf_engine_draft_id": "5c709522-90db-4aea-b49f-15aeaa7180c7",
    "template_folder_id": null,
    "ttl": 86400,
    "created_at": "2050-01-02T03:04:05.678+02:00",
    "updated_at": "2050-01-02T03:04:05.678+02:00",
    "auth_token": "ZCsspcSZieyfdCUHYjKW1B9D8mnrz2ck",
    "checksum": "kfYsx6xzMx3JkYxLd4LW6YeU5rkcuTxQ",
    "preview_url": "https://preview.pdfmonkey.io/pdf/..."
  }
}
```

## Create a template

**`POST /api/v1/document_templates`**

Creates a new template. In most cases you should create templates through the [Dashboard](https://pdfmonkey.io/docs/generating-documents/using-the-dashboard.md), but the API is available for programmatic workflows.

### Parameters

All parameters are nested under a `document_template` key.

| Name | Type | Required | Description |
|:--- |:--- |:--- |:--- |
| `app_id` | String (UUID) | **Yes** | The workspace to create the template in. |
| `identifier` | String | **Yes** | Human-readable name (1--100 characters). |
| `body` | String | No | Published HTML + Liquid content. |
| `body_draft` | String | No | Draft HTML + Liquid content. |
| `scss_style` | String | No | Published CSS/SCSS styles. |
| `scss_style_draft` | String | No | Draft CSS/SCSS styles. |
| `sample_data` | String | No | Published test data (JSON string). |
| `sample_data_draft` | String | No | Draft test data (JSON string). |
| `settings` | Object or String | No | Published printing settings. See [Settings](#settings). |
| `settings_draft` | Object or String | No | Draft printing settings. |
| `pdf_engine_id` | String (UUID) | No | PDF engine for generation. Defaults to the latest engine. See [PDF engines](#pdf-engines). |
| `pdf_engine_draft_id` | String (UUID) | No | PDF engine for preview. Defaults to the latest engine. |
| `template_folder_id` | String (UUID) | No | Folder to place the template in. |
| `ttl` | Integer | No | Time-to-live in seconds for generated documents. Allowed values depend on your plan. See [Retention and Deletion](https://pdfmonkey.io/docs/generating-documents/retention-and-deletion.md). |
| `edition_mode` | String | No | `code` (default) or `builder`. |
| `output_type` | String | No | `pdf` (default) or `image`. See [Output Format](https://pdfmonkey.io/docs/generating-documents/output-format.md). |

### Request








**curl**

```bash
curl https://api.pdfmonkey.io/api/v1/document_templates \
  -X POST \
  -H &#39;Authorization: Bearer YOUR_SECRET_KEY&#39; \
  -H &#39;Content-Type: application/json&#39; \
  -d &#39;{
    &#34;document_template&#34;: {
      &#34;app_id&#34;: &#34;3161c5e5-9966-4630-9b07-63f718092784&#34;,
      &#34;identifier&#34;: &#34;Invoice Template&#34;,
      &#34;body_draft&#34;: &#34;&lt;h1&gt;Invoice #{{number}}&lt;/h1&gt;&lt;p&gt;Total: {{total}}&lt;/p&gt;&#34;,
      &#34;scss_style_draft&#34;: &#34;h1 { color: #333; }&#34;,
      &#34;sample_data_draft&#34;: &#34;{ \&#34;number\&#34;: \&#34;INV-001\&#34;, \&#34;total\&#34;: \&#34;$123.50\&#34; }&#34;,
      &#34;settings_draft&#34;: {
        &#34;paper_format&#34;: &#34;a4&#34;,
        &#34;orientation&#34;: &#34;portrait&#34;,
        &#34;margin&#34;: { &#34;top&#34;: 20, &#34;bottom&#34;: 20, &#34;left&#34;: 15, &#34;right&#34;: 15 }
      }
    }
  }&#39;
```

**Ruby**

```ruby
template = Pdfmonkey::Template.create(
  workspace_id: &#39;3161c5e5-9966-4630-9b07-63f718092784&#39;,
  identifier: &#39;Invoice Template&#39;,
  body: &#39;&lt;h1&gt;Invoice #{{number}}&lt;/h1&gt;&lt;p&gt;Total: {{total}}&lt;/p&gt;&#39;,
  scss_style: &#39;h1 { color: #333; }&#39;,
  sample_data: &#39;{ &#34;number&#34;: &#34;INV-001&#34;, &#34;total&#34;: &#34;$123.50&#34; }&#39;,
  settings: {
    paper_format: &#39;a4&#39;,
    orientation: &#39;portrait&#39;,
    margin: { top: 20, bottom: 20, left: 15, right: 15 },
  },
)

puts template.id
```

**Node.js**

```javascript
const response = await fetch(&#39;https://api.pdfmonkey.io/api/v1/document_templates&#39;, {
  method: &#39;POST&#39;,
  headers: {
    &#39;Authorization&#39;: &#39;Bearer YOUR_SECRET_KEY&#39;,
    &#39;Content-Type&#39;: &#39;application/json&#39;,
  },
  body: JSON.stringify({
    document_template: {
      app_id: &#39;3161c5e5-9966-4630-9b07-63f718092784&#39;,
      identifier: &#39;Invoice Template&#39;,
      body_draft: &#39;&lt;h1&gt;Invoice #{{number}}&lt;/h1&gt;&lt;p&gt;Total: {{total}}&lt;/p&gt;&#39;,
      scss_style_draft: &#39;h1 { color: #333; }&#39;,
      sample_data_draft: &#39;{ &#34;number&#34;: &#34;INV-001&#34;, &#34;total&#34;: &#34;$123.50&#34; }&#39;,
      settings_draft: {
        paper_format: &#39;a4&#39;,
        orientation: &#39;portrait&#39;,
        margin: { top: 20, bottom: 20, left: 15, right: 15 },
      },
    },
  }),
});

const data = await response.json();
console.log(data.document_template);
```

**Python**

```python
import requests

response = requests.post(
    &#39;https://api.pdfmonkey.io/api/v1/document_templates&#39;,
    headers={
        &#39;Authorization&#39;: &#39;Bearer YOUR_SECRET_KEY&#39;,
    },
    json={
        &#39;document_template&#39;: {
            &#39;app_id&#39;: &#39;3161c5e5-9966-4630-9b07-63f718092784&#39;,
            &#39;identifier&#39;: &#39;Invoice Template&#39;,
            &#39;body_draft&#39;: &#39;&lt;h1&gt;Invoice #{{number}}&lt;/h1&gt;&lt;p&gt;Total: {{total}}&lt;/p&gt;&#39;,
            &#39;scss_style_draft&#39;: &#39;h1 { color: #333; }&#39;,
            &#39;sample_data_draft&#39;: &#39;{ &#34;number&#34;: &#34;INV-001&#34;, &#34;total&#34;: &#34;$123.50&#34; }&#39;,
            &#39;settings_draft&#39;: {
                &#39;paper_format&#39;: &#39;a4&#39;,
                &#39;orientation&#39;: &#39;portrait&#39;,
                &#39;margin&#39;: {&#39;top&#39;: 20, &#39;bottom&#39;: 20, &#39;left&#39;: 15, &#39;right&#39;: 15},
            },
        },
    },
)

data = response.json()
print(data[&#39;document_template&#39;])
```

**PHP**

```php
&lt;?php
$ch = curl_init(&#39;https://api.pdfmonkey.io/api/v1/document_templates&#39;);

curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER =&gt; true,
    CURLOPT_POST =&gt; true,
    CURLOPT_HTTPHEADER =&gt; [
        &#39;Authorization: Bearer YOUR_SECRET_KEY&#39;,
        &#39;Content-Type: application/json&#39;,
    ],
    CURLOPT_POSTFIELDS =&gt; json_encode([
        &#39;document_template&#39; =&gt; [
            &#39;app_id&#39; =&gt; &#39;3161c5e5-9966-4630-9b07-63f718092784&#39;,
            &#39;identifier&#39; =&gt; &#39;Invoice Template&#39;,
            &#39;body_draft&#39; =&gt; &#39;&lt;h1&gt;Invoice #{{number}}&lt;/h1&gt;&lt;p&gt;Total: {{total}}&lt;/p&gt;&#39;,
            &#39;scss_style_draft&#39; =&gt; &#39;h1 { color: #333; }&#39;,
            &#39;sample_data_draft&#39; =&gt; &#39;{ &#34;number&#34;: &#34;INV-001&#34;, &#34;total&#34;: &#34;$123.50&#34; }&#39;,
            &#39;settings_draft&#39; =&gt; [
                &#39;paper_format&#39; =&gt; &#39;a4&#39;,
                &#39;orientation&#39; =&gt; &#39;portrait&#39;,
                &#39;margin&#39; =&gt; [&#39;top&#39; =&gt; 20, &#39;bottom&#39; =&gt; 20, &#39;left&#39; =&gt; 15, &#39;right&#39; =&gt; 15],
            ],
        ],
    ]),
]);

$response = curl_exec($ch);
curl_close($ch);

$data = json_decode($response, true);
print_r($data[&#39;document_template&#39;]);
```



### Response

Returns `201 Created` with the full `document_template` object.

### Validation errors

If required fields are missing or invalid, the API returns `422 Unprocessable Entity`:

```json title="422 Unprocessable Entity"
{
  "errors": {
    "identifier": ["can't be blank"]
  }
}
```

## Update a template

**`PUT /api/v1/document_templates/{id}`**

Updates an existing template. Only the fields you include in the request body are changed.

### Parameters

All parameters are nested under a `document_template` key. The same fields as [Create a template](#create-a-template) are accepted.

### Request








**curl**

```bash
curl https://api.pdfmonkey.io/api/v1/document_templates/8ac0d8f7-dbd3-46dd-b2d3-af036a2776d9 \
  -X PUT \
  -H &#39;Authorization: Bearer YOUR_SECRET_KEY&#39; \
  -H &#39;Content-Type: application/json&#39; \
  -d &#39;{
    &#34;document_template&#34;: {
      &#34;body_draft&#34;: &#34;&lt;h1&gt;Invoice #{{number}}&lt;/h1&gt;&lt;p&gt;Due: {{due_date}}&lt;/p&gt;&lt;p&gt;Total: {{total}}&lt;/p&gt;&#34;,
      &#34;sample_data_draft&#34;: &#34;{ \&#34;number\&#34;: \&#34;INV-001\&#34;, \&#34;due_date\&#34;: \&#34;2050-04-01\&#34;, \&#34;total\&#34;: \&#34;$123.50\&#34; }&#34;
    }
  }&#39;
```

**Ruby**

```ruby
template = Pdfmonkey::Template.fetch(&#39;8ac0d8f7-dbd3-46dd-b2d3-af036a2776d9&#39;)

template.update!(
  body: &#39;&lt;h1&gt;Invoice #{{number}}&lt;/h1&gt;&lt;p&gt;Due: {{due_date}}&lt;/p&gt;&lt;p&gt;Total: {{total}}&lt;/p&gt;&#39;,
  sample_data: &#39;{ &#34;number&#34;: &#34;INV-001&#34;, &#34;due_date&#34;: &#34;2050-04-01&#34;, &#34;total&#34;: &#34;$123.50&#34; }&#39;,
)
```

**Node.js**

```javascript
const response = await fetch(
  &#39;https://api.pdfmonkey.io/api/v1/document_templates/8ac0d8f7-dbd3-46dd-b2d3-af036a2776d9&#39;,
  {
    method: &#39;PUT&#39;,
    headers: {
      &#39;Authorization&#39;: &#39;Bearer YOUR_SECRET_KEY&#39;,
      &#39;Content-Type&#39;: &#39;application/json&#39;,
    },
    body: JSON.stringify({
      document_template: {
        body_draft: &#39;&lt;h1&gt;Invoice #{{number}}&lt;/h1&gt;&lt;p&gt;Due: {{due_date}}&lt;/p&gt;&lt;p&gt;Total: {{total}}&lt;/p&gt;&#39;,
        sample_data_draft: &#39;{ &#34;number&#34;: &#34;INV-001&#34;, &#34;due_date&#34;: &#34;2050-04-01&#34;, &#34;total&#34;: &#34;$123.50&#34; }&#39;,
      },
    }),
  }
);

const data = await response.json();
console.log(data.document_template);
```

**Python**

```python
import requests

response = requests.put(
    &#39;https://api.pdfmonkey.io/api/v1/document_templates/8ac0d8f7-dbd3-46dd-b2d3-af036a2776d9&#39;,
    headers={
        &#39;Authorization&#39;: &#39;Bearer YOUR_SECRET_KEY&#39;,
    },
    json={
        &#39;document_template&#39;: {
            &#39;body_draft&#39;: &#39;&lt;h1&gt;Invoice #{{number}}&lt;/h1&gt;&lt;p&gt;Due: {{due_date}}&lt;/p&gt;&lt;p&gt;Total: {{total}}&lt;/p&gt;&#39;,
            &#39;sample_data_draft&#39;: &#39;{ &#34;number&#34;: &#34;INV-001&#34;, &#34;due_date&#34;: &#34;2050-04-01&#34;, &#34;total&#34;: &#34;$123.50&#34; }&#39;,
        },
    },
)

data = response.json()
print(data[&#39;document_template&#39;])
```

**PHP**

```php
&lt;?php
$ch = curl_init(&#39;https://api.pdfmonkey.io/api/v1/document_templates/8ac0d8f7-dbd3-46dd-b2d3-af036a2776d9&#39;);

curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER =&gt; true,
    CURLOPT_CUSTOMREQUEST =&gt; &#39;PUT&#39;,
    CURLOPT_HTTPHEADER =&gt; [
        &#39;Authorization: Bearer YOUR_SECRET_KEY&#39;,
        &#39;Content-Type: application/json&#39;,
    ],
    CURLOPT_POSTFIELDS =&gt; json_encode([
        &#39;document_template&#39; =&gt; [
            &#39;body_draft&#39; =&gt; &#39;&lt;h1&gt;Invoice #{{number}}&lt;/h1&gt;&lt;p&gt;Due: {{due_date}}&lt;/p&gt;&lt;p&gt;Total: {{total}}&lt;/p&gt;&#39;,
            &#39;sample_data_draft&#39; =&gt; &#39;{ &#34;number&#34;: &#34;INV-001&#34;, &#34;due_date&#34;: &#34;2050-04-01&#34;, &#34;total&#34;: &#34;$123.50&#34; }&#39;,
        ],
    ]),
]);

$response = curl_exec($ch);
curl_close($ch);

$data = json_decode($response, true);
print_r($data[&#39;document_template&#39;]);
```



### Response

Returns `200 OK` with the updated `document_template` object.

## Delete a template

**`DELETE /api/v1/document_templates/{id}`**

Permanently deletes a template.

> [!CAUTION]
> Deleting a template is irreversible. All documents linked to this template will lose their template reference.


### Request








**curl**

```bash
curl https://api.pdfmonkey.io/api/v1/document_templates/8ac0d8f7-dbd3-46dd-b2d3-af036a2776d9 \
  -X DELETE \
  -H &#39;Authorization: Bearer YOUR_SECRET_KEY&#39;
```

**Ruby**

```ruby
Pdfmonkey::Template.delete(&#39;8ac0d8f7-dbd3-46dd-b2d3-af036a2776d9&#39;)
```

**Node.js**

```javascript
const response = await fetch(
  &#39;https://api.pdfmonkey.io/api/v1/document_templates/8ac0d8f7-dbd3-46dd-b2d3-af036a2776d9&#39;,
  {
    method: &#39;DELETE&#39;,
    headers: {
      &#39;Authorization&#39;: &#39;Bearer YOUR_SECRET_KEY&#39;,
    },
  }
);

console.log(response.status); // =&gt; 204
```

**Python**

```python
import requests

response = requests.delete(
    &#39;https://api.pdfmonkey.io/api/v1/document_templates/8ac0d8f7-dbd3-46dd-b2d3-af036a2776d9&#39;,
    headers={
        &#39;Authorization&#39;: &#39;Bearer YOUR_SECRET_KEY&#39;,
    },
)

print(response.status_code)  # =&gt; 204
```

**PHP**

```php
&lt;?php
$ch = curl_init(&#39;https://api.pdfmonkey.io/api/v1/document_templates/8ac0d8f7-dbd3-46dd-b2d3-af036a2776d9&#39;);

curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER =&gt; true,
    CURLOPT_CUSTOMREQUEST =&gt; &#39;DELETE&#39;,
    CURLOPT_HTTPHEADER =&gt; [
        &#39;Authorization: Bearer YOUR_SECRET_KEY&#39;,
    ],
]);

curl_exec($ch);
echo curl_getinfo($ch, CURLINFO_HTTP_CODE); // =&gt; 204
curl_close($ch);
```



### Response

Returns `204 No Content` with an empty body.

## Related pages

- **[Authentication](https://pdfmonkey.io/docs/api/authentication.md)** -- Find your API key and authenticate requests.
- **[Documents API](https://pdfmonkey.io/docs/api/documents.md)** -- Create, list, and manage generated documents.
- **[Generate Documents with the API](https://pdfmonkey.io/docs/generating-documents/api-pdf-generation.md)** -- Step-by-step guide with examples in multiple languages.
- **[Our Engines](https://pdfmonkey.io/docs/code-templates/our-engines.md)** -- Detailed comparison of PDF engine versions.
- **[Output Format](https://pdfmonkey.io/docs/generating-documents/output-format.md)** -- Choose between PDF and image output.
- **[Retention and Deletion](https://pdfmonkey.io/docs/generating-documents/retention-and-deletion.md)** -- Understand TTL values and automatic document cleanup.
- **[Webhooks](https://pdfmonkey.io/docs/generating-documents/webhooks.md)** -- Receive notifications when document generation completes.


## FAQ

**What is a DocumentTemplate in PDFMonkey?**

A DocumentTemplate is the reusable design that defines a document's layout. It contains HTML + Liquid for dynamic content, CSS/SCSS for styling, test data for previewing, and settings for paper size, margins, headers, and footers.

**How do I list all templates with the PDFMonkey API?**

Send a GET request to /api/v1/document_template_cards with a q[workspace_id] parameter. The response returns a paginated list of lightweight template card objects.

**Can I create and update templates via the API?**

Yes. POST to /api/v1/document_templates to create a template and PUT to /api/v1/document_templates/{id} to update one. Most users design templates in the Dashboard and only use the API for document generation.



---

# Zapier Integration: Automate Document Generation

Source: https://pdfmonkey.io/docs/integrations/zapier.md
The PDFMonkey Zapier integration lets you generate, retrieve, and manage documents directly from your Zaps. If you are new to the integration, start with the [Getting Started](#getting-started) section below for a complete end-to-end tutorial.

## Getting Started {#getting-started}

<iframe width="100%" height="400" src="https://www.youtube.com/embed/yLMBYxehDMg" title="YouTube video player" frameBorder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowFullScreen></iframe>

Before you begin, make sure you have a PDFMonkey account and a published template. See [From Zero to First Document](https://pdfmonkey.io/docs/getting-started/from-zero-to-first-document.md) for setup instructions.

### Writing Your First Template

In the **HTML** tab of your template, insert the following code:

```liquid title="HTML"
<p class="greeting">Hello {{name}}!</p>
<p>Your favorite number is {{favoriteNumber}}.</p>
```

In the **CSS** tab, insert the following code:

```css
.greeting {
  color: #6D28D9;
  font-size: 24px;
}
```

And finally in the **Test data** tab, insert this:

```json
{
  "name": "Peter Parker",
  "favoriteNumber": 8
}
```

Click **Save** to see the preview update, then click **Publish** to make the template available for generation.

> [!WARNING]
> **Always publish your template!**
>
> Forgetting to publish your template is a frequent mistake, especially when switching back and forth between Zapier and PDFMonkey. If the documents you generate don&#39;t match your template, always check you published it.


### Generating Your First Document

Now that your template is complete, let's head to Zapier.

For this guide we will define a Zap triggered by a form submission on [Tally](https://tally.so/), generate a document in PDFMonkey, and then send it by email.

#### The Tally Form

We will use the following Tally form as our source of information in our Zap:

![Tally form used as Zap trigger](https://pdfmonkey.io/docs/img/zapier-guide-select-pdfmonkey.webp)

#### Setting Up Your Zap

Start by creating a new Zap. As trigger we will use Tally's **New Response** event:

![Creating a new Zap with Tally trigger](https://pdfmonkey.io/docs/img/zapier-guide-create-document.webp)

We then proceed to fill out our form and check it's correctly connected in Zapier:

![Selecting the PDFMonkey template](https://pdfmonkey.io/docs/img/zapier-guide-select-template.webp)

![Connecting your PDFMonkey account](https://pdfmonkey.io/docs/img/zapier-guide-connect-account.webp)

#### Calling PDFMonkey

Now that we have some data to work with, we will configure our PDFMonkey action.

Select the PDFMonkey app and choose the **Generate Document** action.

![Mapping fields in the PDFMonkey action](https://pdfmonkey.io/docs/img/zapier-guide-map-fields.webp)

You can then map the data from the form to variables for your document. Make sure to use the same names as the ones used when writing the template.

![Testing the PDFMonkey action](https://pdfmonkey.io/docs/img/zapier-guide-test-action.webp)

> [!NOTE]
> **Naming variables**
>
> If you&#39;re wondering how to write proper names so it works in PDFMonkey, we provide [a list of correct/incorrect variable name formats](https://pdfmonkey.io/docs/code-templates/defining-dynamic-data.md#naming-your-variables).


We're now ready to test the document generation.

![Document successfully created](https://pdfmonkey.io/docs/img/zapier-guide-document-created.webp)

![Downloading the generated document](https://pdfmonkey.io/docs/img/zapier-guide-download-pdf.webp)

#### Sending the Document by Email

Now that our document is generated, let's send it by email.

Add a new action and select the Email by Zapier app, then choose the **Send Outbound Email** action.

![Configuring the send email action](https://pdfmonkey.io/docs/img/zapier-guide-send-email.webp)

We can now use our document's **Download URL** as attachment for the email. Zapier automatically downloads the file and attaches it.

![The complete Zap from trigger to email](https://pdfmonkey.io/docs/img/zapier-guide-final-zap.webp)

You can now test this last action and you should receive an email with the document attached.

Congrats! You generated your very first PDFMonkey document using Zapier!

## Generate a Document {#generate-a-document}

The **Generate Document** action creates a document from one of your PDFMonkey templates. You select a template, map your data fields, and PDFMonkey generates the document. The action returns a [download URL](https://pdfmonkey.io/docs/generating-documents/download-url.md) you can use in subsequent Zap steps.

For a step-by-step walkthrough of your first Zap, see the [Getting Started](#getting-started) section above.

### Advanced JSON Payload {#advanced-json}

> [!WARNING]
> **Be careful!**
>
> With great power comes great trouble sometimes. Only switch to advanced JSON if you know what you are doing and know how to escape your data properly.
&gt; 
&gt; See [Troubleshooting](#troubleshooting) for more information.


By default, the integration provides a simple mapping field to define what gets sent to PDFMonkey. In most cases the simple mapping is sufficient, but there are situations where you need to structure your data differently. The **Use a custom JSON structure** option switches from the simple mapping to a text area where you can insert your own JSON with nested properties:

![Custom JSON payload option in the PDFMonkey Zapier action](https://pdfmonkey.io/docs/img/zapier-custom-json-payload.webp)

### Custom Filename {#custom-filename}

You can specify a custom name for the generated file. This is useful if you plan on storing the document in a service like Drive or Dropbox.

You can use dynamic parts to build the filename, but keep these restrictions in mind:

- The filename must not contain any slash `/` or backslash `\`
- Non-latin characters should be avoided as they can be corrupted when saving the file

Short names based on dates or IDs tend to work best.

> [!TIP]
> For more details on filename options (including setting filenames via the API), see [Custom Filename](https://pdfmonkey.io/docs/generating-documents/custom-filename.md).


### Metadata {#metadata}

When you generate a document, you can attach metadata to it. Metadata is not available in the template and cannot influence the content of the document; it is simply attached to it.

A common use case is receiving the document via a [webhook](https://pdfmonkey.io/docs/generating-documents/webhooks.md) and using its metadata to route or handle it differently.

![Metadata fields in the PDFMonkey Zapier action](https://pdfmonkey.io/docs/img/zapier-metadata-fields.webp)

### Line Items {#line-items}

If you are generating an invoice or a quote, you will likely need to deal with line items. Zapier provides a way to access those items if the trigger you use supports them.

Take the example of a Stripe invoice. Items in the invoice are available through a Line Items collection. To send those items in a way that PDFMonkey can understand, set **Add Line Items** to **Yes**.

This opens a section where you specify what a **single item** looks like. For example, consider a Stripe invoice with these items:

```
Delicious waffle         3.50€      x12      = 42.00€
Perfectly round donut    4.99€      x5       = 24.95€
TOTAL                                          66.95€
```

The `TOTAL` should be sent as basic data for the document, while the name, unit price, quantity, and total amount for each item should be sent as line items from Zapier:

![Line items mapping in the PDFMonkey Zapier action](https://pdfmonkey.io/docs/img/zapier-line-items-mapping.webp)

> [!TIP]
> **Mapping or JSON**
>
> The field to define the data for a line item uses the same form as the main data. If you use [advanced JSON](#advanced-json) for the main data, the line item payload is also defined using advanced JSON.


#### Using the Line Items in Your Template

When Zapier sends the line items to PDFMonkey, they are accessible through a special `lineItems` variable. In the example above, the payload would look like this:

```json title="JSON"
{
  "lineItems": [
    {
      "product": "Delicious waffle",
      "quantity": "12",
      "unitPrice": "3.50",
      "totalAmount": "42.00"
    },
    {
      "product": "Perfectly round donut",
      "quantity": "5",
      "unitPrice": "4.99",
      "totalAmount": "24.95"
    }
  ]
}
```

> [!NOTE]
> **Only strings attached**
>
> If you look closely at the payload above, only strings are sent. Zapier does not differentiate between text and numbers.
&gt; 
&gt; Luckily, Liquid (the template language we use) is smart enough to convert those values to numbers when you do math with them. Just keep this in mind if you run into trouble with numbers. See [How to Do Maths](https://pdfmonkey.io/docs/code-templates/how-to-do-maths.md) for arithmetic tips.


You can loop over the `lineItems` array to display content for each item individually:

```liquid title="HTML"
{% for item in lineItems %}
  <p>{{item.product}} at {{item.unitPrice}}€ x{{item.quantity}} = {{item.totalAmount}}€</p>
{% endfor %}
```

This produces the following HTML:

```html title="HTML"
<p>Delicious waffle at 3.50€ x12 = 42.00€</p>
<p>Perfectly round donut at 4.99€ x5 = 24.95€</p>
```

You will probably want to build a table row for each item, but this gives you a good idea of how to get started. See [Conditions and Loops](https://pdfmonkey.io/docs/code-templates/conditions-and-loops.md) for more Liquid loop techniques.

## Document Generated Trigger {#document-generated-trigger}

The **Document Generated** trigger fires your Zap every time a document finishes generating (reaches the `success` [status](https://pdfmonkey.io/docs/generating-documents/document-statuses.md)). This is useful for automating post-generation tasks like storing the file in Dropbox, sending it by email, or logging it in a spreadsheet.

![Selecting the Document Generated event in Zapier](https://pdfmonkey.io/docs/img/zapier-trigger-select-event.webp)

You can choose to trigger your Zap for:

- Any template in your workspace
- A single template
- Several specific templates

![Connecting your PDFMonkey account in the trigger](https://pdfmonkey.io/docs/img/zapier-trigger-connect-account.webp)

Make sure to have at least one generated document before testing your trigger in Zapier.

![Selecting which template to trigger on](https://pdfmonkey.io/docs/img/zapier-trigger-select-template.webp)

You can then use the generated file to store it, send it by email, or get notified in some way.

> [!NOTE]
> **Leveraging metadata**
>
> The document exposed by the trigger does not contain your payload. If you need any information in the following actions, we recommend [attaching metadata](#metadata) to the document.
&gt; 
&gt; That is what we did with the Tally information in this example.


![Test result showing the trigger output](https://pdfmonkey.io/docs/img/zapier-trigger-test-result.webp)

## Retrieve and Delete Documents {#retrieve-and-delete}

### Retrieve a Document

The **Retrieve Document** action fetches a previously generated document by its ID. Use this when you need to access a document's details or [download URL](https://pdfmonkey.io/docs/generating-documents/download-url.md) in a later step of your Zap; for example, after a delay or in a separate workflow from the one that generated it.

### Delete a Document

The **Delete Document** action removes a single document from PDFMonkey. Use this to clean up documents after you have processed them; for example, after downloading and storing the file elsewhere. See [Retention and Deletion](https://pdfmonkey.io/docs/generating-documents/retention-and-deletion.md) for more on document lifecycle management.

## Troubleshooting {#troubleshooting}

### Download URL Expired {#download-url-expired}

If you get an expired download URL error while building your Zap, reload the example record in your trigger.

The [download URL](https://pdfmonkey.io/docs/generating-documents/download-url.md) is only valid for 1 hour. You need to refresh the documents in Zapier to get a new URL. Click the **Load More** button in the Test section of your trigger:

![Refreshing trigger fields to get a new download URL](https://pdfmonkey.io/docs/img/zapier-refresh-trigger-fields.webp)

> [!NOTE]
> **Generation output**
>
> This tip applies to the trigger only. For the output of a Generate Document action, you need to generate a new document to get fresh data and a valid download URL.


> [!TIP]
> If your Zaps fail because the URL has expired by the time a later step runs, see [Download URL Returns 403](https://pdfmonkey.io/docs/troubleshooting/download-url-gives-403.md) for solutions.


### 422 Responses {#422-responses}

This error usually happens when you use the custom JSON option and have values that need escaping before being sent to PDFMonkey.

#### Values Containing Double Quotes

Consider the following custom JSON:

```json5 title="Custom JSON"
{
  "user": {
    "name": "(Dynamic Field From Zapier)"
  }
}
```

If the value in `Dynamic Field From Zapier` contains quotes, the resulting JSON breaks. Take `Peter "Spiderman" Parker` as an example:

```json title="Invalid JSON"
{
  "user": {
    "name": "Peter "Spiderman" Parker"
  }
}
```

This is not valid JSON. What you need is to _escape_ the double quotes:

```json title="Valid JSON"
{
  "user": {
    "name": "Peter \"Spiderman\" Parker"
  }
}
```

> [!NOTE]
> **HTML attributes**
>
> If you send HTML, this happens frequently since attributes almost always use double quotes (e.g., `&lt;div class=&#34;test&#34;&gt;`).


#### Values Containing Line Breaks

JSON does not support values that include raw line breaks:

```json title="Invalid JSON"
{
  "userBio": "Once upon a time,
They lived happily ever after."
}
```

Escape the line breaks by replacing them with a `<br />` tag or using the text representation `\n`:

```json title="Valid JSON"
{
  "userBio": "Once upon a time,\nThey lived happily ever after."
}
```

#### Solution {#escaping-solution}

> [!NOTE]
> **Do you really need custom JSON?**
>
> The first question to ask yourself is whether you truly need custom JSON. In most cases the simple mapping approach is sufficient and takes care of escaping automatically.


If you cannot escape the values before they reach Zapier, add a **Code by Zapier** action before calling PDFMonkey.

Suppose your data contains both line breaks and double quotes:

| Item                           | Value                                                                                                                                                                                |
| ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Trigger App User Bio**       | <p>This is the bio of the user.</p><p>It's a free form text that the user can edit so it can contain line breaks.</p><p><br />It could even be split in a few paragraphs... why not?</p> |
| **Trigger App User Name**      | Peter Parker                                                                                                                                                                         |
| **Trigger App User Full Name** | Peter "Spiderman" Parker                                                                                                                                                             |

You need to escape values for both `Trigger App User Bio` and `Trigger App User Full Name`. Start by adding a **Code by Zapier** action to your Zap and selecting **Run Javascript**:

![Adding a Code by Zapier action with raw input data](https://pdfmonkey.io/docs/img/zapier-error-422-raw-body.webp)

Give your fields names that help identify them in the following steps:

![Naming the input fields in Code by Zapier](https://pdfmonkey.io/docs/img/zapier-error-422-json-format.webp)

Now add the code that escapes the values:

```javascript title="Code by Zapier"
let data = Object.assign({}, inputData);

for (let key in data) {
  if (typeof(data[key]) === "string" && data[key].length > 0) {
    data[key] = data[key].replace(/\r?\n/g, '<br>').replace(/\t/g, " ").replace(/"/g, '\\\"');
  }
}

output = [data];
```

This gives you the same fields in the output but with their values properly escaped:

![The escaped output from Code by Zapier](https://pdfmonkey.io/docs/img/zapier-error-422-custom-request.webp)

You can now use those values when building your PDFMonkey payload:

![Using the escaped values in the PDFMonkey action](https://pdfmonkey.io/docs/img/zapier-error-422-fixed-payload.webp)

Notice how we used the fields from the Code by Zapier step, not from the trigger directly.

## Next Steps {#next-steps}

- [From Zero to First Document](https://pdfmonkey.io/docs/getting-started/from-zero-to-first-document.md): Set up your PDFMonkey account and create your first template
- [Defining Dynamic Data](https://pdfmonkey.io/docs/code-templates/defining-dynamic-data.md): Learn how to structure the JSON payload for your templates
- [Document Statuses](https://pdfmonkey.io/docs/generating-documents/document-statuses.md): Understand the lifecycle of a generated document
- [Webhooks](https://pdfmonkey.io/docs/generating-documents/webhooks.md): Receive real-time notifications when documents finish generating
- Explore other integrations: [Make](https://pdfmonkey.io/docs/integrations/make.md), [n8n](https://pdfmonkey.io/docs/integrations/n8n.md), [Workato](https://pdfmonkey.io/docs/integrations/workato.md)


---

# Make Integration: Automate Document Generation

Source: https://pdfmonkey.io/docs/integrations/make.md
The PDFMonkey module for [Make](https://www.make.com/) lets you generate documents as part of your automated scenarios. Combine it with triggers from form builders, CRMs, or databases to produce and deliver files without writing code.

## Setup {#setup}

Before you begin, make sure you have:

- A PDFMonkey account ([sign up here](https://dashboard.pdfmonkey.io/register))
- A [Make](https://www.make.com/) account
- A published template in PDFMonkey

For account creation and template setup, see [From Zero to First Document](https://pdfmonkey.io/docs/getting-started/from-zero-to-first-document.md).

To connect PDFMonkey to Make, add the PDFMonkey module to your scenario and click **Create a connection**. Enter your API Secret Key from the [My Account](https://dashboard.pdfmonkey.io/account) page.

## Generate a Document {#generate-a-document}

Add the PDFMonkey **Generate a Document** module to your scenario. Select your Workspace and Template, then map fields from previous modules to the variables defined in your template.

![PDFMonkey field mapping in Make](https://pdfmonkey.io/docs/img/make-pdfmonkey-field-mapping.webp)

> [!NOTE]
> **Naming variables**
>
> Variable names in your template must follow specific formatting rules. See the [naming variables](https://pdfmonkey.io/docs/code-templates/defining-dynamic-data.md#naming-your-variables) reference for correct and incorrect formats.


After the module runs, it returns data about the generated document, including the [download URL](https://pdfmonkey.io/docs/generating-documents/download-url.md) and filename.

![Document generated result in Make](https://pdfmonkey.io/docs/img/make-document-generated.webp)

## Working with the Generated File {#working-with-the-generated-file}

### Downloading the File {#downloading-the-file}

To use the generated file in downstream modules, download it first. Add the HTTP **Get a File** module and pass it the **Download URL** returned by the PDFMonkey module.

![HTTP Get a File module configuration](https://pdfmonkey.io/docs/img/make-http-get-file.webp)

> [!TIP]
> The download URL expires after 1 hour. If you plan to use it later, download the file immediately or upload it to permanent storage. See [Download URL](https://pdfmonkey.io/docs/generating-documents/download-url.md) for details.


### Sending by Email {#sending-by-email}

Add your email provider module (or Make's built-in **Send an email** module) and attach the downloaded file. Customize the **File name** field to avoid the default `file.pdf` name; the PDFMonkey module returns a filename you can use directly.

![Email attachment configuration with custom filename](https://pdfmonkey.io/docs/img/make-email-attachment.webp)

> [!TIP]
> You can also set a [custom filename](https://pdfmonkey.io/docs/generating-documents/custom-filename.md) in PDFMonkey so it arrives with a meaningful name in every scenario.


## Example: Tally Form to Document {#example-tally-form}

This example shows a complete scenario that receives a [Tally](https://tally.so/) form submission, generates a document, and sends it by email.

### The Tally Form {#the-tally-form}

The scenario uses a Tally form as its data source:

![Tally form used as scenario trigger](https://pdfmonkey.io/docs/img/make-tally-form.webp)

### Setting Up the Trigger {#setting-up-the-trigger}

Create a new scenario with Tally's **Watch New Responses** trigger. Make creates a webhook URL and attaches it to your Tally form automatically.

![Tally webhook setup in Make](https://pdfmonkey.io/docs/img/make-tally-webhook-setup.webp)

Submit a test form entry and click **Run once** to verify the connection:

![Run once button in Make scenario](https://pdfmonkey.io/docs/img/make-run-once-trigger.webp)

![Trigger data received from Tally](https://pdfmonkey.io/docs/img/make-trigger-data-received.webp)

### Mapping Fields and Generating {#mapping-fields-and-generating}

With the trigger data available, configure the PDFMonkey module to map Tally fields to your template variables, then add the HTTP and email modules as described in [Working with the Generated File](#working-with-the-generated-file).

> [!WARNING]
> **Always publish your template**
>
> If the documents you generate don&#39;t match your template, check that you published it. Forgetting to publish after making changes is a common mistake, especially when switching between Make and PDFMonkey.


## Troubleshooting {#troubleshooting}

### JSON Escaping {#json-escaping}

The Make module sends data as JSON. If your data contains double quotes or line breaks, the JSON becomes invalid. For example, a name like `Peter "Spider-Man" Parker` breaks the JSON structure.

Replace `"` with `\"` inside values to escape double quotes:

![JSON escaping configuration in Make](https://pdfmonkey.io/docs/img/make-json-escaping.webp)

Line breaks (`\n`) require the same treatment: replace `\n` with `\\n` to keep the JSON valid.

### Template Not Published {#template-not-published}

If the generated documents don't reflect your latest template changes, the most likely cause is an unpublished template. Open your template in PDFMonkey and click **Publish** before running the scenario again.

### Download URL Expired {#download-url-expired}

The [download URL](https://pdfmonkey.io/docs/generating-documents/download-url.md) is valid for 1 hour. If a later module in your scenario fails because the URL has expired, move the HTTP **Get a File** step closer to the PDFMonkey module so the download happens immediately.

For more details, see [Download URL Returns 403](https://pdfmonkey.io/docs/troubleshooting/download-url-gives-403.md).

## Next Steps {#next-steps}

- [From Zero to First Document](https://pdfmonkey.io/docs/getting-started/from-zero-to-first-document.md): Set up your PDFMonkey account and create your first template
- [Defining Dynamic Data](https://pdfmonkey.io/docs/code-templates/defining-dynamic-data.md): Learn how to structure the JSON payload for your templates
- [Custom Filename](https://pdfmonkey.io/docs/generating-documents/custom-filename.md): Control the name of generated files
- [Document Statuses](https://pdfmonkey.io/docs/generating-documents/document-statuses.md): Understand the lifecycle of a generated document
- [Webhooks](https://pdfmonkey.io/docs/generating-documents/webhooks.md): Receive real-time notifications when documents finish generating
- Explore other integrations: [Zapier](https://pdfmonkey.io/docs/integrations/zapier.md), [n8n](https://pdfmonkey.io/docs/integrations/n8n.md), [Workato](https://pdfmonkey.io/docs/integrations/workato.md)


---

# n8n Integration: Automate Document Generation

Source: https://pdfmonkey.io/docs/integrations/n8n.md
The PDFMonkey n8n node lets you generate, retrieve, download, and delete documents directly from your n8n workflows. If you are setting up PDFMonkey with n8n for the first time, start with the [Getting Started](#getting-started) section below.

## Getting Started {#getting-started}

n8n is a workflow automation platform that connects different apps and services together. It is an open-source alternative to tools like [Zapier](https://pdfmonkey.io/docs/integrations/zapier.md) and [Make](https://pdfmonkey.io/docs/integrations/make.md), offering both cloud and self-hosted options.

Before you begin, make sure you have:

- A PDFMonkey account ([sign up here](https://dashboard.pdfmonkey.io/register))
- An n8n account or instance ([sign up at n8n.io](https://n8n.io) or [self-host](https://docs.n8n.io/hosting/))
- Your PDFMonkey API key
- A published template in PDFMonkey

For the full account creation and template setup walkthrough, see [From Zero to First Document](https://pdfmonkey.io/docs/getting-started/from-zero-to-first-document.md).

### Setting Up Credentials {#setting-up-credentials}

Before using the PDFMonkey node, you need to configure your API credentials:

1. In your n8n workflow, add a PDFMonkey node
2. Click on **Create New Credentials**
3. Enter your PDFMonkey API key (found in [your PDFMonkey dashboard](https://dashboard.pdfmonkey.io/account))
4. Click **Save**

> [!TIP]
> **Where to find your API key**
>
> Your API key is available in your PDFMonkey dashboard under **Account** then **API**. See [Authentication](https://pdfmonkey.io/docs/api/authentication.md) for more details.


### Your First Workflow {#your-first-workflow}

Let's create a simple workflow that generates a document when triggered manually. Use the template you created in [From Zero to First Document](https://pdfmonkey.io/docs/getting-started/from-zero-to-first-document.md), or create a simple template with a greeting variable.

#### Step 1: Add a Manual Trigger

1. Create a new workflow in n8n
2. The **Manual Trigger** node should already be there
3. This allows you to test your workflow manually

#### Step 2: Add the PDFMonkey Node

1. Click the **+** button to add a new node
2. Search for **PDFMonkey**
3. Select the **PDFMonkey** node
4. Choose **Generate Document** as the operation

#### Step 3: Configure the Generate Document Operation

In the PDFMonkey node configuration:

1. Select your PDFMonkey credentials (or create them if you haven't)
2. Set your Template ID from your PDFMonkey template
3. Set the **Payload Input Method** to **Key-Value Pairs**
4. Add the following fields:
   - Key: `name` → Value: `Peter Parker`
   - Key: `favoriteNumber` → Value: `8`

> [!NOTE]
> **Payload methods**
>
> You can choose between **Key-Value Pairs** (simple) or **JSON** (for complex data structures). The JSON method is covered in the [Generate a Document](#generate-a-document) section below.


> [!NOTE]
> **Variable naming**
>
> Variable names in your template must follow specific formatting rules. See the [naming variables](https://pdfmonkey.io/docs/code-templates/defining-dynamic-data.md#naming-your-variables) reference for correct and incorrect formats.


#### Step 4: Test Your Workflow

1. Click on **Execute Workflow** (the play button at the bottom)
2. Wait a few seconds for the document to generate
3. You should see the document details in the output
4. The file is now available at the `download_url` provided

#### Step 5: Download the File (Optional)

If you want to download the generated file as binary data in n8n:

1. Enable **Download File** in the PDFMonkey node options
2. The file is available as binary data in the next nodes

### Example: Webhook to Document to Email {#example-webhook-to-document-to-email}

Let's create a more practical workflow that:
1. Receives data from a webhook
2. Generates a document with PDFMonkey
3. Sends the document by email

#### The Workflow Structure

1. **Webhook** node: receives form data
2. **PDFMonkey** node: generates the document
3. **Send Email** node: sends the file as attachment

#### Configuration

**Webhook node:**
- Set to POST method
- Path: `/generate-document`

**PDFMonkey node:**
- Operation: Generate Document
- Select your template
- Map webhook data to template variables:
  - `name` → `{{ $json.name }}`
  - `favoriteNumber` → `{{ $json.favoriteNumber }}`
- Enable **Download File** option

**Send Email node:**
- Use Gmail, SendGrid, or any SMTP service
- In attachments, reference the PDFMonkey binary data:
  - Property Name: `data`
  - File Name: `document.pdf`

> [!TIP]
> **Testing webhooks**
>
> Use the **Test URL** provided by n8n to send POST requests with JSON data like:
&gt; ```json
&gt; {
&gt;   &#34;name&#34;: &#34;John Doe&#34;,
&gt;   &#34;favoriteNumber&#34;: 42
&gt; }
&gt; ```


You've successfully set up your first PDFMonkey workflow in n8n.

## Generate a Document {#generate-a-document}

The Generate Document operation creates a document from one of your PDFMonkey templates. You provide a template and a [dynamic data payload](https://pdfmonkey.io/docs/code-templates/defining-dynamic-data.md), and PDFMonkey renders the file.

### Payload Input Methods {#payload-input-methods}

The PDFMonkey node offers two ways to send data to your template.

**Key-Value Pairs (Simple Mode)** is the easiest way to send simple data structures. You add fields one by one, each with a key (the variable name in your template) and a value (static or dynamic from previous nodes).

**JSON Format (Advanced Mode)** handles complex data structures, nested objects, or arrays. Use JSON when your template expects structured data:

```json title="JSON Payload"
{
  "customer": {
    "name": "Acme Inc.",
    "email": "contact@acme.com",
    "address": {
      "street": "123 Main St",
      "city": "New York",
      "zip": "10001"
    }
  },
  "items": [
    {
      "product": "Widget",
      "quantity": 5,
      "price": 10.99
    },
    {
      "product": "Gadget",
      "quantity": 2,
      "price": 24.99
    }
  ],
  "total": 104.93
}
```

In your template, access nested data with dot notation:

```liquid title="HTML"
<h2>Invoice for {{customer.name}}</h2>
<p>{{customer.address.street}}, {{customer.address.city}}</p>

{% for item in items %}
  <p>{{item.product}} x{{item.quantity}} = {{item.price}}</p>
{% endfor %}
```

For more on structuring your dynamic data, see [Defining Dynamic Data](https://pdfmonkey.io/docs/code-templates/defining-dynamic-data.md).

### Using Expressions {#using-expressions}

n8n expressions let you reference data from previous nodes dynamically:

```javascript
{{ $json.customerName }}              // Simple field
{{ $node["Webhook"].json["email"] }}  // From specific node
{{ $json.items.length }}              // Array length
{{ new Date().toISOString() }}        // Current date
```

You can use expressions in Key-Value pair values, JSON payloads (as string values), the custom filename field, and metadata fields.

### Custom Filename {#custom-filename}

You can specify a custom name for the generated file. This is useful when storing files in Google Drive, Dropbox, or other storage services.

In the PDFMonkey node options:

1. Expand **Additional Options**
2. Set **Custom Filename**
3. Use a static name or n8n expressions:

```
Invoice-{{ $json.invoiceNumber }}.pdf
Report-{{ $now.format('YYYY-MM-DD') }}.pdf
{{ $json.customerName }}-Contract.pdf
```

> [!WARNING]
> **Filename restrictions**
>
> - Do not use slashes `/` or backslashes `\`
&gt; - Avoid special characters that might cause issues on different operating systems
&gt; - Non-latin characters may be escaped or replaced


For more details on filename options, see [Custom Filename](https://pdfmonkey.io/docs/generating-documents/custom-filename.md).

### Metadata {#metadata}

Metadata is additional information attached to a document that does not appear in the generated file itself. It is useful for tracking document origin, storing reference IDs, and filtering in [webhooks](https://pdfmonkey.io/docs/generating-documents/webhooks.md).

To add metadata:

1. Expand **Additional Options** in the PDFMonkey node
2. Set **Metadata** to **Key-Value Pairs** or **JSON**
3. Add your metadata fields:

```json
{
  "orderId": "ORD-12345",
  "customerEmail": "john@example.com",
  "environment": "production"
}
```

You can retrieve metadata later using the Get Document operation or in [webhook triggers](#pdfmonkey-trigger).

> [!NOTE]
> **Metadata vs Payload**
>
> - **Payload (dynamic data):** Data used to render the document content
&gt; - **Metadata:** Information attached to the document but not visible in the output; included in webhook notifications


### Wait for Document {#wait-for-document}

By default, the Generate Document operation waits for the document to be fully generated before continuing.

> [!NOTE]
> **Document generation time**
>
> Most documents generate in a few seconds. Complex documents with many pages, images, or JavaScript may take longer. See [Document Statuses](https://pdfmonkey.io/docs/generating-documents/document-statuses.md) for the full generation lifecycle.


If you need to disable waiting and handle completion asynchronously, you can use the [PDFMonkey Trigger](#pdfmonkey-trigger) or [poll for completion](#polling-for-completion) instead.

### Arrays and Complex Data {#arrays-and-complex-data}

n8n makes it easy to work with arrays from previous nodes. Here is an example using Google Sheets data.

**Google Sheets node output:**

```json
[
  { "product": "Widget", "qty": 5, "price": 10 },
  { "product": "Gadget", "qty": 2, "price": 25 }
]
```

**In PDFMonkey node (JSON mode):**

```json
{
  "customerName": "{{ $json.customerName }}",
  "items": {{ $node["Google Sheets"].json }}
}
```

The array is passed directly to your template where you can loop over it:

```liquid
{% for item in items %}
  <tr>
    <td>{{item.product}}</td>
    <td>{{item.qty}}</td>
    <td>{{item.price}}</td>
  </tr>
{% endfor %}
```

For more on loops and conditional rendering, see [Conditions and Loops](https://pdfmonkey.io/docs/code-templates/conditions-and-loops.md).

### Handling Multiple Items {#handling-multiple-items}

If your workflow processes multiple items (like multiple customers or orders), use n8n's **Split In Batches** node:

```
1. Get Data (returns 100 items)
2. Split In Batches (batch size: 1)
3. PDFMonkey - Generate Document (runs 100 times)
4. Store files
```

Or use the **Loop Over Items** node for more control.

> [!WARNING]
> **Rate limits**
>
> Be mindful of your PDFMonkey plan limits when generating multiple documents. Consider adding **Wait** nodes between batches if generating many documents. See [Rate Limiting](#rate-limiting) for details, and [Our Plans](https://pdfmonkey.io/docs/pricing-and-billing/our-plans.md) for quota information.


### Error Handling {#error-handling}

Use n8n's error handling features to manage failures:

1. Click on the PDFMonkey node
2. Go to **Settings** tab
3. Configure **On Error**:
   - **Stop Workflow** (default)
   - **Continue With Last Successful Item**
   - **Continue Execution**

For more robust error handling, add an **IF** node after PDFMonkey to check the [document status](https://pdfmonkey.io/docs/generating-documents/document-statuses.md):

```
IF: {{ $json.status }} equals "success"
  -> TRUE: Continue with the file
  -> FALSE: Send error notification
```

## PDFMonkey Trigger {#pdfmonkey-trigger}

The PDFMonkey Trigger is a webhook-based trigger that listens for document generation events. When a document finishes generating, PDFMonkey sends a notification to your n8n workflow. This is useful for automating post-generation actions like storing files, sending notifications, or updating databases.

For background on how PDFMonkey webhooks work (including event types, payload format, and signature verification), see [Webhooks](https://pdfmonkey.io/docs/generating-documents/webhooks.md).

### Setup {#trigger-setup}

1. In your n8n workflow, click **+** to add a new node
2. Search for **PDFMonkey Trigger** and select it as your workflow's starting point
3. Select your PDFMonkey API credentials
4. Choose which templates to listen to:
   - **Any Template:** trigger for all documents in your workspace
   - **Specific Template:** trigger for a single template
   - **Multiple Templates:** trigger for several selected templates
5. Copy the **Webhook URL** displayed by the trigger node
6. In your [PDFMonkey dashboard](https://dashboard.pdfmonkey.io), go to the **Webhooks** section
7. Create a new endpoint with the n8n webhook URL
8. Check the success and failure events, then press **Create**
9. Back in n8n, click the **Activate** toggle to enable your workflow

> [!NOTE]
> **Production vs Test webhooks**
>
> n8n provides two URLs:
&gt; - **Test URL:** For testing in the n8n editor
&gt; - **Production URL:** For activated/published workflows
&gt; 
&gt; Make sure to update your PDFMonkey webhook URL when activating your workflow.


### Trigger Data {#trigger-data}

When a document finishes generating, the trigger receives a [DocumentCard](https://pdfmonkey.io/docs/api/documents.md#the-documentcard-object) object. This includes document metadata, status, and download URL, but does not include the original dynamic data you sent:

```json
{
  "document": {
    "id": "a5e86d72-f5b7-43d4-a04e-8b7e08e6741c",
    "app_id": "d6b4e8f2-7a3c-4d1e-9f5b-2c8a1d3e6f90",
    "created_at": "2050-03-13T12:34:56.181+02:00",
    "document_template_id": "2903f5b4-623b-4e10-b2e3-dc7e2e67ea39",
    "document_template_identifier": "My Invoice Template",
    "download_url": "https://pdfmonkey.s3.eu-west-1.amazonaws.com/...",
    "failure_cause": null,
    "filename": "2050-03-14 Peter Parker.pdf",
    "meta": {
      "_filename": "2050-03-14 Peter Parker.pdf",
      "clientRef": "spidey-616"
    },
    "output_type": "pdf",
    "preview_url": "https://preview.pdfmonkey.io/...",
    "public_share_link": null,
    "status": "success",
    "updated_at": "2050-03-13T12:34:59.412+02:00"
  }
}
```

> [!WARNING]
> **Dynamic data is not included**
>
> The webhook payload does not include the original dynamic data (payload) you sent to generate the document. If you need this information in your workflow, store it in the [metadata](#metadata) field when generating the document. Metadata is included in every webhook notification.


### Auto-Download {#auto-download}

The PDFMonkey Trigger has a **Download File** option that automatically downloads the generated file when the trigger fires.

When enabled:
- The file is downloaded as binary data
- It is available immediately in the next nodes
- No need for a separate Download File operation

To enable it:
1. Open the trigger node settings
2. Expand **Additional Options**
3. Toggle **Download File** to ON

The binary data is available with the key `data`.

### Use Cases {#trigger-use-cases}

**Store files in Google Drive:**

```
1. PDFMonkey Trigger (Download File: enabled)
2. Google Drive - Upload File
   - File: {{ $binary.data }}
   - Folder: /Invoices/
   - Filename: {{ $json.filename }}
```

**Send notification to Slack:**

```
1. PDFMonkey Trigger
2. Slack - Send Message
   - Channel: #notifications
   - Message: "New document generated: {{ $json.filename }}"
   - Attachment: {{ $json.download_url }}
```

**Update database record:**

```
1. PDFMonkey Trigger
2. Postgres - Update
   - Table: orders
   - Where: id = {{ $json.metadata.orderId }}
   - Set: pdf_url = {{ $json.download_url }}, status = 'completed'
```

**Email document to customer:**

```
1. PDFMonkey Trigger (Download File: enabled)
2. Gmail - Send Email
   - To: {{ $json.metadata.customerEmail }}
   - Subject: Your invoice is ready
   - Attachments: {{ $binary.data }}
```

### Metadata for Routing {#metadata-for-routing}

Metadata enables conditional workflows. When generating a document, attach routing information:

```json
{
  "metadata": {
    "documentType": "invoice",
    "customerId": "12345",
    "sendEmail": true
  }
}
```

Then in your triggered workflow, use an **IF** node or **Switch** node to route based on metadata:

```
1. PDFMonkey Trigger
2. Switch node
   - Case 1: {{ $json.metadata.documentType }} = "invoice" -> Store in accounting
   - Case 2: {{ $json.metadata.documentType }} = "report" -> Share on Slack
   - Case 3: {{ $json.metadata.documentType }} = "contract" -> Store in DocuSign
```

### Testing {#trigger-testing}

**Method 1: Generate a test document.** Use another workflow or the API to generate a document, wait for the webhook to fire, and check the trigger node execution in n8n.

**Method 2: Use the test webhook.**

1. Click **Listen for event** in the trigger node
2. Generate a document from your PDFMonkey template
3. The trigger catches the event and displays the data
4. Click **Use test event** to use this data while building your workflow

> [!TIP]
> **Trigger from the dashboard**
>
> You can manually trigger a test generation from your PDFMonkey template editor by clicking the **Generate** button. This fires the webhook immediately.


You can also have multiple n8n workflows listening to the same template. Each webhook receives the notification independently, which is useful for separating environments or having different workflows for different document types.

### Delivery Guarantees {#delivery-guarantees}

PDFMonkey uses [Svix](https://www.svix.com/) to deliver webhooks. Deliveries follow these guarantees:

- **At-least-once delivery:** You might receive the same event multiple times
- **Best-effort ordering:** Events are usually in order but not guaranteed
- **Automatic retries:** Failed deliveries are retried with exponential backoff
- **Signature verification:** Every webhook is signed so you can verify authenticity

> [!NOTE]
> **Make your workflow idempotent**
>
> Since webhooks might be delivered multiple times, design your workflow to handle duplicate events gracefully. Use document IDs to check if you have already processed an event.


For full details on webhook configuration (including channel routing and signature verification), see [Webhooks](https://pdfmonkey.io/docs/generating-documents/webhooks.md).

## Other Operations {#other-operations}

Beyond generating documents and reacting to triggers, the PDFMonkey node supports several operations for managing documents.

### Get Document {#get-document}

The Get Document operation retrieves information about a previously generated document. Use it to check a document's [status](https://pdfmonkey.io/docs/generating-documents/document-statuses.md), retrieve its [download URL](https://pdfmonkey.io/docs/generating-documents/download-url.md), access attached metadata, or verify a document exists before processing.

**Required field:** Document ID

```
Document ID: {{ $json.documentId }}
```

The operation returns complete document information including status, download URL, preview URL, metadata, and timestamps.

**Document status values:**
- `draft` — document is created but not yet queued for generation
- `pending` — document is queued for generation
- `generating` — document is currently being rendered
- `success` — document generated successfully
- `failure` — generation failed (check `failure_cause` for details)

For the full status lifecycle, see [Document Statuses](https://pdfmonkey.io/docs/generating-documents/document-statuses.md).

### Download File {#download-file}

The Download File operation downloads a generated file as binary data. Use it to download a file that was generated earlier, get binary data separately from generation, or re-download a document for processing.

**Required field:** Document ID

**Optional field:** Binary Property Name (default: `data`)

```
Document ID: {{ $json.documentId }}
Binary Property Name: pdfFile
```

The file is stored as binary data and can be used in email attachments, file storage nodes (Google Drive, Dropbox, etc.), FTP uploads, or further processing nodes.

> [!NOTE]
> **Generate Document has built-in download**
>
> If you are generating and immediately downloading, use the **Download File** option in the Generate Document operation instead of a separate Download File node.


### Delete Document {#delete-document}

The Delete Document operation permanently removes a document from PDFMonkey. Use it to clean up after sending a document, remove documents containing sensitive data, manage storage quotas, or implement document retention policies.

**Required field:** Document ID

```
Document ID: {{ $json.documentId }}
```

> [!WARNING]
> **Deletion is permanent**
>
> Once deleted, documents cannot be recovered. The download URL stops working. Make sure you have saved the file elsewhere if you need it.


> [!NOTE]
> **TTL as alternative**
>
> Consider using [automatic deletion (TTL)](https://pdfmonkey.io/docs/generating-documents/retention-and-deletion.md) instead of manually deleting documents. You can set documents to auto-delete after a configurable period when generating them.


### Polling for Completion {#polling-for-completion}

If you generated a document with **Wait for Document** disabled, you can poll for its completion instead of using a webhook trigger:

```
1. PDFMonkey - Generate Document (Wait: disabled)
2. Wait (10 seconds)
3. PDFMonkey - Get Document
   - Document ID: {{ $node["PDFMonkey"].json.id }}
4. IF node
   - {{ $json.status }} = "success"
   - TRUE: Continue with the file
   - FALSE: Loop back to step 2
```

> [!NOTE]
> **Better approach: Use the trigger**
>
> Instead of polling, consider using the [PDFMonkey Trigger](#pdfmonkey-trigger) to be notified when documents are ready. Triggers are more efficient and respond faster.


### Combining Operations {#combining-operations}

**Generate, store, and clean up:**

```
1. Manual Trigger
2. PDFMonkey - Generate Document (Download: enabled)
3. Google Drive - Upload File
   - File: {{ $binary.data }}
   - Folder: /Invoices/
4. Postgres - Insert
   - Table: documents
   - Data: {
       drive_url: {{ $node["Google Drive"].json.webViewLink }},
       pdfmonkey_id: {{ $node["PDFMonkey"].json.id }}
     }
5. PDFMonkey - Delete Document
   - Document ID: {{ $node["PDFMonkey"].json.id }}
```

**Conditional download based on status:**

```
1. Webhook (receives document ID)
2. PDFMonkey - Get Document
   - Document ID: {{ $json.documentId }}
3. IF node
   - Condition: {{ $json.status }} = "success"
   - TRUE:
     4a. PDFMonkey - Download File
     5a. Send to customer
   - FALSE:
     4b. Send error notification
     5b. PDFMonkey - Delete Document (cleanup failed attempt)
```

**Re-generate and replace:**

```
1. Webhook (receives order update)
2. PDFMonkey - Delete Document
   - Document ID: {{ $json.oldDocumentId }}
3. PDFMonkey - Generate Document
   - Template: Invoice
   - Payload: {{ $json.updatedData }}
4. Update database with new document ID
```

## Troubleshooting {#troubleshooting}

### Authentication Errors {#authentication-errors}

**Invalid API key:**

```
401 Unauthorized - Invalid API key
```

1. Go to your [PDFMonkey dashboard](https://dashboard.pdfmonkey.io/account)
2. Navigate to **Account** then **API**
3. Copy your API key
4. In n8n, update your PDFMonkey credentials with the correct key
5. Test the connection

For more on API authentication, see [Authentication](https://pdfmonkey.io/docs/api/authentication.md).

> [!NOTE]
> **Multiple workspaces**
>
> If you have multiple PDFMonkey workspaces, make sure you are using the API key from the correct workspace.


If your credentials suddenly stop working, delete the old credentials in n8n, create new ones with a fresh API key, and update all nodes using those credentials.

### Template Not Found {#template-not-found}

```
404 Not Found - Template does not exist
```

**Causes:** the template was deleted, the wrong workspace or API key is in use, or the template ID is incorrect.

**Solution:** Verify the template exists in your PDFMonkey dashboard, check you are using the correct API key, and re-select the template from the dropdown in n8n.

**Template not published:**

```
422 Unprocessable Entity - Template is not published
```

Go to your template in PDFMonkey and make sure it is published by clicking the **Publish** button, then try generating again.

> [!WARNING]
> **Common mistake**
>
> This is one of the most frequent errors. Always remember to publish your template after making changes.


### Invalid Payload {#invalid-payload}

```
422 Unprocessable Entity - Invalid payload
```

**Causes:** invalid JSON syntax (when using JSON mode), wrong data types, or missing required fields.

Common JSON syntax issues:

**Missing quotes:**
```json
// Wrong
{ name: "John" }

// Correct
{ "name": "John" }
```

**Trailing commas:**
```json
// Wrong
{
  "name": "John",
  "age": 30,
}

// Correct
{
  "name": "John",
  "age": 30
}
```

**Unescaped double quotes in values:**
```json
// Wrong - nested quotes break the JSON
{ "name": "Peter "Spider-Man" Parker" }

// Correct - escape inner quotes with backslash
{ "name": "Peter \"Spider-Man\" Parker" }
```

**Using n8n expressions in JSON:**

When using expressions, make sure to stringify objects:

```json
// Wrong - Will create invalid JSON
{
  "items": {{ $json.items }}
}

// Correct - Properly stringify
{
  "items": {{ JSON.stringify($json.items) }}
}
```

> [!TIP]
> **Use Key-Value Pairs mode**
>
> If you are struggling with JSON syntax, switch to **Key-Value Pairs** mode. n8n handles all the escaping and formatting automatically.


### Download Errors {#download-errors}

**Download URL expired:**

```
403 Forbidden - Download URL has expired
```

[Download URLs](https://pdfmonkey.io/docs/generating-documents/download-url.md) expire after 1 hour for security reasons.

**Option 1:** Use Get Document to get a fresh URL, then download from the new URL with an HTTP Request node.

**Option 2:** Enable the **Download File** option in the Generate Document node to download immediately after generation.

**Option 3:** Store the binary data in a file storage service (Google Drive, S3, etc.) instead of relying on PDFMonkey URLs.

For more details, see [Download URL Returns 403](https://pdfmonkey.io/docs/troubleshooting/download-url-gives-403.md).

**Binary data not available:**

If no binary data is available for attachment or storage, make sure **Download File** is enabled:
- In **Generate Document** operation: Additional Options then Download File
- In **PDFMonkey Trigger**: Additional Options then Download File
- Or use a **Download File** operation explicitly

### Webhook Issues {#webhook-issues}

**Webhook not receiving events checklist:**

1. Workflow is **activated** (not just saved)
2. Webhook URL is correct in PDFMonkey
3. Using **Production URL** not Test URL
4. Template is published
5. Firewall is not blocking requests

**To debug:** check the **Executions** tab in n8n for errors, go to template settings in the PDFMonkey dashboard and check webhook delivery logs, and try generating a test document manually. See [Webhooks](https://pdfmonkey.io/docs/generating-documents/webhooks.md) for webhook configuration details.

**Receiving duplicate webhook events** is expected behavior. PDFMonkey webhooks use at-least-once delivery. Make your workflow idempotent by checking if you have already processed a document:

```
1. PDFMonkey Trigger
2. Postgres - Check if document ID exists
3. IF node
   - Already processed: Stop
   - New document: Continue processing
```

**Wrong webhook URL:** After activating your workflow, the webhook URL changes from Test to Production. Copy the **Production URL** from the trigger node and update the webhook URL in your PDFMonkey settings.

### Expression Errors {#expression-errors}

**Cannot read property of undefined:**

```
Cannot read property 'field' of undefined
```

This happens when trying to access data that does not exist from a previous node.

**Check the node name:**
```javascript
// Wrong node name
{{ $node["PDFmonkey"].json.id }}

// Correct node name (capital M)
{{ $node["PDFMonkey"].json.id }}
```

**Check the data exists:**
```javascript
// Assumes field exists
{{ $json.customer.email }}

// Use optional chaining (n8n 1.0+)
{{ $json.customer?.email }}

// Or provide default value
{{ $json.customer?.email || 'no-email@example.com' }}
```

Use the expression editor in n8n (click the **Expression** button) and use the autocomplete to ensure you are referencing the correct fields.

### Workflow Timeout {#workflow-timeout}

```
Workflow execution timed out
```

**Causes:** document taking too long to generate, network issues, or large file downloads.

**Option 1:** Increase the timeout in workflow settings (Execution Timeout).

**Option 2:** Disable "Wait for Document" and use a [webhook trigger](#pdfmonkey-trigger) in a separate workflow.

**Option 3:** Split into multiple workflows and use webhooks to chain them together.

### Memory Errors {#memory-errors}

```
JavaScript heap out of memory
```

This happens when processing very large files or data in n8n.

**Solutions:**
1. Process items in smaller batches (use the Split In Batches node)
2. Use streaming where possible
3. Increase n8n memory allocation (self-hosted only)
4. Store large files externally instead of passing them through the workflow

### Rate Limiting {#rate-limiting}

```
429 Too Many Requests - Rate limit exceeded
```

Add **Wait** nodes between operations when processing multiple documents:

```
1. Get items to process
2. Split In Batches (size: 10)
3. Wait (5 seconds)
4. PDFMonkey - Generate Document
5. Loop
```

Or use the **Code** node to add delays:

```javascript
// Wait 1 second per item
await new Promise(resolve => setTimeout(resolve, 1000));
return items;
```

### JSON Formatting {#json-formatting}

**Line breaks in JSON:** JSON does not support raw line breaks in strings:

```json
// Wrong
{
  "description": "Line 1
Line 2"
}

// Correct
{
  "description": "Line 1\nLine 2"
}
```

Or use a **Code** node to escape:

```javascript
items[0].json.description = items[0].json.description.replace(/\n/g, '\\n');
return items;
```

**Special characters:** Escape double quotes inside string values:

```json
// Wrong - unescaped quotes break JSON
{ "html": "<div class=\"test\">Hello</div>" }

// Correct - escaped inner quotes
{ "html": "<div class=\"test\">Hello</div>" }
```

Or use **Key-Value Pairs** mode which handles escaping automatically.

## Next Steps {#next-steps}

- [From Zero to First Document](https://pdfmonkey.io/docs/getting-started/from-zero-to-first-document.md): Set up your PDFMonkey account and create your first template
- [Defining Dynamic Data](https://pdfmonkey.io/docs/code-templates/defining-dynamic-data.md): Learn how to structure the JSON payload for your templates
- [Custom Filename](https://pdfmonkey.io/docs/generating-documents/custom-filename.md): Control the name of generated files
- [Document Statuses](https://pdfmonkey.io/docs/generating-documents/document-statuses.md): Understand the lifecycle of a generated document
- [Webhooks](https://pdfmonkey.io/docs/generating-documents/webhooks.md): Receive real-time notifications when documents finish generating
- [Download URL](https://pdfmonkey.io/docs/generating-documents/download-url.md): How temporary download links work and how to refresh them
- [Retention and Deletion](https://pdfmonkey.io/docs/generating-documents/retention-and-deletion.md): Set up automatic document cleanup with TTL
- Explore other integrations: [Zapier](https://pdfmonkey.io/docs/integrations/zapier.md), [Make](https://pdfmonkey.io/docs/integrations/make.md), [Workato](https://pdfmonkey.io/docs/integrations/workato.md)

## Need More Help? {#need-more-help}

If you are still experiencing issues:

1. **n8n documentation:** [docs.n8n.io](https://docs.n8n.io)
2. **PDFMonkey status:** [status.pdfmonkey.io](https://status.pdfmonkey.io)
3. **n8n Community:** [community.n8n.io](https://community.n8n.io)
4. **PDFMonkey support:** support@pdfmonkey.io

> [!NOTE]
> **Include details in support requests**
>
> When asking for help, include the full error message, your n8n version, a workflow screenshot, and the steps to reproduce.



---

# Workato Integration: Automate Document Generation

Source: https://pdfmonkey.io/docs/integrations/workato.md
The PDFMonkey connector for [Workato](https://www.workato.com/) lets you generate, monitor, and clean up documents as part of your automated recipes. Combine it with triggers from CRMs, form builders, or databases to produce and deliver files without writing code.

## Setup {#setup}

Before you begin, make sure you have:

- A PDFMonkey account ([sign up here](https://dashboard.pdfmonkey.io/register))
- A [Workato](https://www.workato.com/) account
- A published template in PDFMonkey

For account creation and template setup, see [From Zero to First Document](https://pdfmonkey.io/docs/getting-started/from-zero-to-first-document.md).

To connect PDFMonkey to Workato:

1. Add the **PDFMonkey** connector to your recipe.
2. Create a new connection and enter your API Secret Key, available on the [My Account](https://dashboard.pdfmonkey.io/account) page.

Once connected, the PDFMonkey actions and triggers are available in your recipe steps.

## Generate a Document {#generate-a-document}

Use the **Generate Document** action to create a document from one of your templates.

1. Select the template to use for generation.
2. Provide the [dynamic data](https://pdfmonkey.io/docs/code-templates/defining-dynamic-data.md) as a JSON payload. This data populates the variables defined in your template.
3. Optionally attach [metadata](#metadata) (such as a custom filename or a reference ID for downstream processing).

> [!NOTE]
> **Naming variables**
>
> Variable names in your template must follow specific formatting rules. See the [naming variables](https://pdfmonkey.io/docs/code-templates/defining-dynamic-data.md#naming-your-variables) reference for correct and incorrect formats.


Document generation is asynchronous: the action sends the generation request and returns immediately. Use the [Document Generated trigger](#document-generated-trigger) below to react when the file is ready.

### Custom Filename {#custom-filename}

You can specify a custom name for the generated file. This is useful when storing documents in services like Google Drive, Dropbox, or another cloud storage platform.

Keep these restrictions in mind:

- The filename must not contain any slash `/` or backslash `\`
- Non-latin characters should be avoided as they can be corrupted when saving the file

Short names based on dates or IDs tend to work best.

> [!TIP]
> For more details on filename options (including setting filenames via the API), see [Custom Filename](https://pdfmonkey.io/docs/generating-documents/custom-filename.md).


### Metadata {#metadata}

When you generate a document, you can attach metadata to it. Metadata is not available in the template and does not influence the document content; it is simply attached to the document for later use.

A common use case is receiving the document via a [webhook](https://pdfmonkey.io/docs/generating-documents/webhooks.md) and using its metadata to route or handle it differently in your automation.

## Document Generated Trigger {#document-generated-trigger}

Use the **Document Generated** trigger to start a recipe when a document finishes generating. This is the recommended way to handle the asynchronous generation workflow.

The trigger provides the completed document's data, including:

- **Download URL** — a temporary link to the generated file (valid for 1 hour). See [Download URL](https://pdfmonkey.io/docs/generating-documents/download-url.md) for details.
- **Filename** — the name of the generated file
- **Metadata** — any metadata attached during generation
- **Status** — the generation result (`success` or `failure`). See [Document Statuses](https://pdfmonkey.io/docs/generating-documents/document-statuses.md) for the full lifecycle.

You can filter by template to ensure the recipe only runs for documents from a specific template.

> [!WARNING]
> **Dynamic data is not included**
>
> The trigger does not include the original dynamic data (payload) you sent to generate the document. If you need this information in later recipe steps, store it in the [metadata](#metadata) field when generating the document.


## Delete a Document {#delete-a-document}

Use the **Delete Document** action to remove a previously generated document from your PDFMonkey account. This is useful for cleaning up documents after they have been downloaded, emailed, or stored elsewhere in your workflow.

> [!TIP]
> **Automatic cleanup**
>
> Instead of manually deleting documents, consider using [automatic deletion (TTL)](https://pdfmonkey.io/docs/generating-documents/retention-and-deletion.md) to have documents cleaned up after a configurable period.


## Example Recipes {#example-recipes}

### Form Submission to Document to Email {#form-to-email}

1. Trigger on a form submission (from a connected app).
2. Use **Generate Document** to create the document with the form data.
3. Use **Document Generated** to wait for the file.
4. Download the file and send it as an email attachment.

### CRM Record to Document to Cloud Storage {#crm-to-storage}

1. Trigger on a new or updated CRM record.
2. Use **Generate Document** to create a contract, invoice, or report.
3. Use **Document Generated** to get the [download URL](https://pdfmonkey.io/docs/generating-documents/download-url.md).
4. Upload the file to Google Drive, Dropbox, or another storage service.

### Generate, Store, and Clean Up {#generate-store-cleanup}

1. Trigger on an event in your app (new order, approved contract, etc.).
2. Use **Generate Document** to create the file.
3. Use **Document Generated** to get the download URL.
4. Upload the file to permanent storage (S3, Google Drive, Sharepoint).
5. Use **Delete Document** to remove the file from PDFMonkey.

## Troubleshooting {#troubleshooting}

### Download URL Expired {#download-url-expired}

The [download URL](https://pdfmonkey.io/docs/generating-documents/download-url.md) is valid for 1 hour. If a later step in your recipe fails because the URL has expired, restructure your recipe so the download happens immediately after the **Document Generated** trigger fires.

For more details, see [Download URL Returns 403](https://pdfmonkey.io/docs/troubleshooting/download-url-gives-403.md).

### Template Not Published {#template-not-published}

If the generated documents do not reflect your latest template changes, the most likely cause is an unpublished template. Open your template in PDFMonkey and click **Publish** before running the recipe again.

> [!WARNING]
> **Common mistake**
>
> Forgetting to publish your template is a frequent error, especially when switching between Workato and PDFMonkey. Always publish after making changes.


## Next Steps {#next-steps}

- [From Zero to First Document](https://pdfmonkey.io/docs/getting-started/from-zero-to-first-document.md): Set up your PDFMonkey account and create your first template
- [Defining Dynamic Data](https://pdfmonkey.io/docs/code-templates/defining-dynamic-data.md): Learn how to structure the JSON payload for your templates
- [Custom Filename](https://pdfmonkey.io/docs/generating-documents/custom-filename.md): Control the name of generated files
- [Document Statuses](https://pdfmonkey.io/docs/generating-documents/document-statuses.md): Understand the lifecycle of a generated document
- [Webhooks](https://pdfmonkey.io/docs/generating-documents/webhooks.md): Receive real-time notifications when documents finish generating
- [Retention and Deletion](https://pdfmonkey.io/docs/generating-documents/retention-and-deletion.md): Set up automatic document cleanup with TTL
- Explore other integrations: [Zapier](https://pdfmonkey.io/docs/integrations/zapier.md), [Make](https://pdfmonkey.io/docs/integrations/make.md), [n8n](https://pdfmonkey.io/docs/integrations/n8n.md)


## FAQ

**How do I generate documents with PDFMonkey and Workato?**

Add the PDFMonkey connector to your Workato recipe, enter your API Secret Key to connect, then use the Generate Document action to create a document from a template with your dynamic data payload.

**How do I know when a PDFMonkey document is ready in Workato?**

Use the Document Generated trigger to start a recipe step when a document finishes generating. It provides the download URL, filename, metadata, and status. You can filter by template so the recipe only runs for specific documents.

**Can I automatically delete documents after processing in Workato?**

Yes. Use the Delete Document action in a later recipe step to remove the document from PDFMonkey after you’ve downloaded, emailed, or stored it. Alternatively, configure automatic deletion (TTL) in PDFMonkey to clean up documents after a set period.


---

# Bubble Integration: Generate Documents in Your Bubble App

Source: https://pdfmonkey.io/docs/integrations/bubble.md
The official PDFMonkey plugin for [Bubble](https://bubble.io/) lets you generate documents directly from your Bubble workflows without writing backend code. Install it from the Bubble marketplace, add a single workflow action, and get a download URL back when the document is ready.

There are two ways to connect PDFMonkey to Bubble:

- **[PDFMonkey plugin](#pdfmonkey-plugin)** (recommended) — install from the marketplace for a no-code setup with built-in polling.
- **[API Connector](#api-connector)** — call the PDFMonkey REST API directly for full control over requests and responses.

## Prerequisites {#prerequisites}

Before you begin, make sure you have:

- A PDFMonkey account ([sign up here](https://dashboard.pdfmonkey.io/register))
- A [Bubble](https://bubble.io/) account with an app
- A published template in PDFMonkey

For account creation and template setup, see [From Zero to First Document](https://pdfmonkey.io/docs/getting-started/from-zero-to-first-document.md).

You also need your **API Secret Key**, available on the [My Account](https://dashboard.pdfmonkey.io/account) page. See [Authentication](https://pdfmonkey.io/docs/api/authentication.md) for details.

## PDFMonkey Plugin {#pdfmonkey-plugin}

The official PDFMonkey plugin is the fastest way to generate documents from Bubble. It handles authentication, document creation, and polling automatically: you add a single action to your workflow, and it returns the finished document.

### Installing the Plugin {#installing-the-plugin}

1. Open your Bubble app editor.
2. Go to **Plugins** and click **Add plugins**.
3. Search for **PDFMonkey** and install the [PDFMonkey](https://bubble.io/plugin/pdfmonkey-uploader-1674229694738x439725903180202000) plugin.
4. In the plugin settings, paste your **API Secret Key** from the [My Account](https://dashboard.pdfmonkey.io/account) page.

That is all you need for authentication. The plugin passes your key via the `Authorization` header on every request.

### Generate a Document Action {#generate-a-document-action}

The plugin provides a server-side action called **PDFMonkey - Generate a Document**. Add it to any Bubble workflow to create and generate a document from one of your templates.

#### Input Fields {#input-fields}

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| **Template ID** | Dynamic value | Yes | The ID of your PDFMonkey template (found in the template settings) |
| **Document data** | Key/value pairs | Yes | The dynamic data for your template; keys must match the variable names defined in your template |
| **Document meta-data** | Key/value pairs | No | Metadata attached to the document (not available inside the template) |
| **Filename** | Dynamic value | No | A custom filename for the generated file |

> [!NOTE]
> **Naming variables**
>
> The keys in **Document data** must match the variable names in your template exactly. See the [naming variables](https://pdfmonkey.io/docs/code-templates/defining-dynamic-data.md#naming-your-variables) reference for formatting rules.


#### Returned Values {#returned-values}

Once the action completes, the following values are available for use in subsequent workflow steps (via **Result of step X**):

| Field | Type | Description |
| --- | --- | --- |
| **id** | text | The unique ID of the generated document |
| **Download URL** | file | A temporary URL to download the file (valid for 1 hour) |
| **Public Share Link** | text | A permanent share link (available on Premium plans) |
| **Filename** | text | The filename of the generated file |
| **Document meta-data** | text | The metadata attached to the document |
| **Status** | text | The document status (`success` or `failure`) |
| **Failure cause** | text | The error message if generation failed |
| **Creation Date** | date | When the document was created |
| **Generation Date** | date | When the document finished generating |
| **Workspace ID** | text | The ID of the workspace containing the template |
| **Template ID** | text | The ID of the template used |
| **Template name** | text | The name (identifier) of the template used |

### How the Action Works {#how-the-action-works}

When the action runs, it:

1. Creates a document via the PDFMonkey API with status `pending`, which starts generation immediately.
2. Polls the API automatically until the document reaches `success` or `failure`.
3. Returns the result to your workflow.

This means the action **blocks until the document is ready**. You do not need to set up polling, webhooks, or any async handling. When the next step in your workflow runs, the document is already generated and the download URL is available.

> [!TIP]
> Because the action handles polling for you, it may take a few seconds to complete depending on your template&#39;s complexity. This is normal behavior; Bubble waits for the result before moving to the next step.


### Workflow Example {#workflow-example}

Here is a typical workflow that generates an invoice and emails it to the customer:

1. A user clicks a **Generate Invoice** button.
2. In the workflow, add the **PDFMonkey - Generate a Document** action.
3. Set **Template ID** to the ID of your invoice template (you can hardcode it or pull it dynamically from your database).
4. Map your Bubble data to the **Document data** keys. For example:
   - `customerName` → Current User's Name
   - `invoiceNumber` → Current Invoice's Number
   - `lineItems` → Current Invoice's Items (formatted as JSON)
5. The action waits until the document is ready.
6. In the next step, add a **Send Email** action and use **Result of step X's Download URL** as the attachment.

> [!WARNING]
> **Publish your template first**
>
> If your generated documents don&#39;t reflect your latest changes, check that you published the template in PDFMonkey. Forgetting to publish after editing is a common mistake.


### List Workspaces Data Source {#list-workspaces}

The plugin also exposes a **List Workspaces** data source that returns the workspaces available in your PDFMonkey account. You can use it to build dynamic dropdowns or let users select a workspace before generating a document.

## API Connector {#api-connector}

If you need more control over requests (custom headers, specific endpoints, or direct access to the full API response), you can call the PDFMonkey REST API using Bubble's built-in API Connector plugin.

> [!NOTE]
> **When to use the API Connector**
>
> For most use cases, the [PDFMonkey plugin](#pdfmonkey-plugin) is simpler and sufficient. Consider the API Connector if you need to call endpoints the plugin does not cover (such as listing or deleting documents), or if you want to handle polling or webhooks yourself.


### Setting Up the API Connector {#setting-up-the-api-connector}

1. In your Bubble app editor, go to **Plugins** and install the **API Connector** plugin (if not already installed).
2. Click **Add another API** and name it `PDFMonkey`.
3. Set **Authentication** to **Private key in header** and configure:
   - **Key name:** `Authorization`
   - **Key value:** `Bearer YOUR_API_SECRET_KEY`
4. Add a new API call with the following settings:

| Setting | Value |
| ------- | ----- |
| **Name** | Create Document |
| **Use as** | Action |
| **Method** | POST |
| **URL** | `https://api.pdfmonkey.io/api/v1/documents` |
| **Headers** | `Content-Type`: `application/json` |

5. In the **Body**, paste the following JSON:

```json
{
  "document": {
    "document_template_id": "<template_id>",
    "status": "pending",
    "payload": {
      "name": "<name>"
    }
  }
}
```

Replace `<template_id>` with your template's ID (found in your PDFMonkey dashboard) and adjust the `payload` keys to match your template's [dynamic data](https://pdfmonkey.io/docs/code-templates/defining-dynamic-data.md).

6. Click **Initialize call** to test the connection. If successful, Bubble detects the response fields automatically.

> [!WARNING]
> **Set status to pending**
>
> You must set `&#34;status&#34;: &#34;pending&#34;` for PDFMonkey to start generating the document immediately. If you omit it or set it to `&#34;draft&#34;`, the document is created but not generated. See [Document Statuses](https://pdfmonkey.io/docs/generating-documents/document-statuses.md) for details.


### Using Dynamic Values {#using-dynamic-values}

To pass dynamic data from your Bubble app, wrap placeholders in angle brackets (`<placeholder>`) in the API Connector body. Bubble turns these into fields you can map to dynamic values in your workflows.

For example, to generate an invoice, your body might look like this:

```json
{
  "document": {
    "document_template_id": "<template_id>",
    "status": "pending",
    "payload": {
      "customerName": "<customer_name>",
      "invoiceNumber": "<invoice_number>",
      "totalAmount": "<total_amount>"
    }
  }
}
```

Each `<placeholder>` becomes a field in the workflow action that you can populate with data from your Bubble app.

> [!NOTE]
> **Naming variables**
>
> Variable names in your payload must match the ones used in your template. See the [naming variables](https://pdfmonkey.io/docs/code-templates/defining-dynamic-data.md#naming-your-variables) reference for formatting rules.


### Retrieving the Generated File {#retrieving-the-generated-file}

Document generation is asynchronous. After the Create Document call returns, the document is not ready yet. You have two options to retrieve the finished file:

- **Polling** — add a second API call (`GET https://api.pdfmonkey.io/api/v1/documents/<document_id>`) and check the `status` field until it reaches `success`. The response then includes a `download_url`.
- **Webhook** — configure a [webhook](https://pdfmonkey.io/docs/generating-documents/webhooks.md) in PDFMonkey to notify your Bubble app when the document is ready. This avoids polling and is more efficient for production use.

> [!TIP]
> The [download URL](https://pdfmonkey.io/docs/generating-documents/download-url.md) expires after 1 hour. If you need a permanent link, use a [share link](https://pdfmonkey.io/docs/generating-documents/share-links.md) or store the file in your own storage.


## Troubleshooting {#troubleshooting}

### Document Generation Fails {#document-generation-fails}

If the plugin action returns a `failure` status, check the **Failure cause** field (or `failureCause` in the API response) for the error message. Common causes include syntax errors in your template or invalid dynamic data.

### Invalid JSON in API Connector {#invalid-json}

If you get a `422` error when using the API Connector, your JSON body is likely malformed. Common causes:

- **Unescaped double quotes** in dynamic values — if a user-provided value contains `"`, it breaks the JSON structure. Sanitize inputs before passing them.
- **Line breaks** in values — raw line breaks are invalid in JSON. Replace them with `\n` or `<br />` before sending.

For more on JSON escaping, see the [422 Responses](https://pdfmonkey.io/docs/integrations/zapier.md#422-responses) section of the Zapier guide (the same principles apply).

### Document Stuck in Draft {#document-stuck-in-draft}

If your document is created but never generates (API Connector only), check that `"status": "pending"` is included in the request body. Without it, PDFMonkey creates the document as a draft and waits for you to trigger generation. See [Document Statuses](https://pdfmonkey.io/docs/generating-documents/document-statuses.md).

> [!TIP]
> This issue does not affect the PDFMonkey plugin, which always sets the status to `pending` automatically.


### Download URL Expired {#download-url-expired}

The [download URL](https://pdfmonkey.io/docs/generating-documents/download-url.md) is valid for 1 hour. If your workflow takes longer to process the file, download it immediately after generation or use a [share link](https://pdfmonkey.io/docs/generating-documents/share-links.md) for permanent access.

For more details, see [Download URL Returns 403](https://pdfmonkey.io/docs/troubleshooting/download-url-gives-403.md).

## Next Steps {#next-steps}

- [From Zero to First Document](https://pdfmonkey.io/docs/getting-started/from-zero-to-first-document.md): Set up your PDFMonkey account and create your first template
- [Defining Dynamic Data](https://pdfmonkey.io/docs/code-templates/defining-dynamic-data.md): Learn how to structure the JSON payload for your templates
- [Document Statuses](https://pdfmonkey.io/docs/generating-documents/document-statuses.md): Understand the lifecycle of a generated document
- [Webhooks](https://pdfmonkey.io/docs/generating-documents/webhooks.md): Receive real-time notifications when documents finish generating
- [Download URL](https://pdfmonkey.io/docs/generating-documents/download-url.md): How download URLs work and when they expire
- Explore other integrations: [Zapier](https://pdfmonkey.io/docs/integrations/zapier.md), [Make](https://pdfmonkey.io/docs/integrations/make.md), [n8n](https://pdfmonkey.io/docs/integrations/n8n.md)


---

# Glide Integration: Generate Documents From Your No-Code App

Source: https://pdfmonkey.io/docs/integrations/glide.md
> [!WARNING]
> **Help us reach the Glide team**
>
> We have reached out to the Glide team multiple times to improve this integration — in particular to add support for arrays and line items — but have never received a response. If you have a direct contact at Glide or any way to push this forward, we would greatly appreciate it. A better integration would benefit everyone building invoices, quotes, and other documents with line items from Glide.


The PDFMonkey integration for [Glide](https://www.glideapps.com/) lets you generate documents directly from your no-code app. Add a **Generate PDF file** action to a button, form submission, or workflow, map your data to a PDFMonkey template, and get a download link back when the document is ready.

## Prerequisites {#prerequisites}

Before you begin, make sure you have:

- A PDFMonkey account ([sign up here](https://dashboard.pdfmonkey.io/register))
- A [Glide](https://www.glideapps.com/) account on a paid plan (the integration is not available on free plans)
- A published template in PDFMonkey

For account creation and template setup, see [From Zero to First Document](https://pdfmonkey.io/docs/getting-started/from-zero-to-first-document.md).

You also need your **API Secret Key**, available on the [My Account](https://dashboard.pdfmonkey.io/account) page. See [Authentication](https://pdfmonkey.io/docs/api/authentication.md) for details.

## Setting Up the Integration {#setting-up-the-integration}

1. In your Glide app, go to **Settings**.
2. Open the **Integrations** section and find **PDFMonkey**.
3. Click **Add to app**.
4. Paste your PDFMonkey **API Secret Key** and save.

Once connected, the **Generate PDF file** action becomes available in your app's actions and workflows.

## Generate PDF File Action {#generate-pdf-file-action}

The **Generate PDF file** action creates a document from one of your PDFMonkey templates and returns a link to the finished file. You can trigger it from:

- A **Button** or other interactive component
- A **Form** submission
- The **Workflow Editor**

### Action Fields {#action-fields}

| Field | Required | Description |
| --- | --- | --- |
| **Template ID** | Yes | The ID of your PDFMonkey template. Copy it from the template settings in your PDFMonkey dashboard. |
| **Filename** | Yes | The name of the generated file. You can use dynamic values from your Glide data. |
| **File output** | Yes | The column where the download link is saved once the document is ready. Use a **text** column (not a URL column). |
| **Dynamic values** | No | Key/value pairs that replace placeholders in your template. Click **+Add value** to map Glide columns to template variables. |

> [!NOTE]
> **Naming variables**
>
> The keys you add in the dynamic values section must match the variable names in your PDFMonkey template exactly. See the [naming variables](https://pdfmonkey.io/docs/code-templates/defining-dynamic-data.md#naming-your-variables) reference for formatting rules.


### How the Action Works {#how-the-action-works}

When the action runs, it sends the template ID and your dynamic values to the PDFMonkey API. PDFMonkey generates the document and returns a download link, which Glide saves in the column you specified as **File output**.

> [!WARNING]
> **Publish your template first**
>
> If the generated documents don&#39;t reflect your latest edits, check that you published the template in PDFMonkey. Forgetting to publish after making changes is a common mistake.


### Workflow Example {#workflow-example}

Here is a typical flow that generates a certificate when a user completes a course:

1. The user taps a **Download Certificate** button in your Glide app.
2. The button triggers the **Generate PDF file** action.
3. Set **Template ID** to the ID of your certificate template.
4. Set **Filename** to something descriptive, for example the user's name combined with the course title.
5. Map your dynamic values:
   - `recipientName` → the user's name column
   - `courseName` → the course title column
   - `completionDate` → the completion date column
6. Set **File output** to a text column in your data source.
7. Once generation completes, the download link appears in the output column. You can display it as a link or use it in a subsequent action (such as sending an email).

## Working with Line Items {#working-with-line-items}

The Glide integration passes data to PDFMonkey as flat key/value pairs. It does not natively support arrays or nested JSON, which means you cannot send a list of line items (such as invoice rows) the same way you would with [Zapier](https://pdfmonkey.io/docs/integrations/zapier.md#line-items) or [Make](https://pdfmonkey.io/docs/integrations/make.md).

This is a Glide-side limitation, not a PDFMonkey one. PDFMonkey templates fully support arrays and loops, but the Glide integration cannot send structured array data directly. The workarounds below let you work around this limitation depending on whether you use Code Templates or Builder Templates.

### Code Templates: JSON String with parse_json {#workaround-json-string}

The cleanest approach for [Code Templates](https://pdfmonkey.io/docs/code-templates) is to pass your line items as a JSON string and parse it in the template using the [`parse_json`](https://pdfmonkey.io/docs/code-templates/filters.md#parse_json) filter.

**In Glide:**

1. **Create a template column** in your related items table that formats each row as a JSON object string. For example: `{"product":"Waffle","qty":12,"unitPrice":"3.50","total":"42.00"}`
2. **Create a Joined List column** in the parent table that joins all rows with commas.
3. **Create another template column** that wraps the joined list in square brackets to form a valid JSON array: `[<joined list>]`
4. **Pass this string** as a dynamic value in the Generate PDF file action, for example as `lineItemsJson`.

**In your PDFMonkey template**, parse the string and loop over the resulting array:

```liquid title="HTML"
{% assign items = lineItemsJson | parse_json %}

<table>
  <thead>
    <tr>
      <th>Product</th>
      <th>Qty</th>
      <th>Unit Price</th>
      <th>Total</th>
    </tr>
  </thead>
  <tbody>
    {% for item in items %}
    <tr>
      <td>{{ item.product }}</td>
      <td>{{ item.qty }}</td>
      <td>{{ item.unitPrice }}</td>
      <td>{{ item.total }}</td>
    </tr>
    {% endfor %}
  </tbody>
</table>
```

This gives you a proper array to loop over, with full access to individual fields — exactly as if the data had been sent as structured JSON.

> [!TIP]
> If the JSON string is empty or invalid, `parse_json` returns `nil`. You can provide a fallback: `lineItemsJson | parse_json: &#34;[]&#34;`. See the full [parse_json reference](https://pdfmonkey.io/docs/code-templates/filters.md#parse_json).


### Builder Templates: Custom JS with JSON.parse {#workaround-builder-json-parse}

For [Builder Templates](https://pdfmonkey.io/docs/builder-templates), the approach is similar: pass a JSON string from Glide, then parse it in the [Custom JS](https://pdfmonkey.io/docs/builder-templates/custom-js.md) editor so you can use the resulting array in your template bindings.

**In Glide**, build the JSON string the same way as described [above](#workaround-json-string).

**In the Custom JS editor** of your Builder template, parse the string and assign the result to `window`:

```javascript
window.lineItems = JSON.parse($docPayload.lineItemsJson || '[]');
```

You can then use `lineItems` in the builder's loop and binding features to iterate over the array and display each item.

### Alternative: Pre-Built HTML {#workaround-pre-built-html}

If you prefer to handle the formatting entirely in Glide, you can build the line items as an HTML string and pass the result as a single variable:

1. **Create a template column** in your related items table that formats each row as an HTML table row. For example:

   ```html
   <tr>
     <td>Product Name</td>
     <td>2</td>
     <td>$15.00</td>
     <td>$30.00</td>
   </tr>
   ```

   Use Glide column references to pull the actual values.

2. **Create a Joined List column** in the parent table that concatenates all the formatted rows into a single string.

3. **Pass the joined HTML** as a dynamic value in the Generate PDF file action. For example, map it to a variable called `lineItemsHtml`.

4. **In your PDFMonkey template**, output the variable so the HTML renders correctly:

   ```liquid title="HTML"
   <table>
     <thead>
       <tr>
         <th>Product</th>
         <th>Qty</th>
         <th>Unit Price</th>
         <th>Total</th>
       </tr>
     </thead>
     <tbody>
       {{ lineItemsHtml }}
     </tbody>
   </table>
   ```

> [!NOTE]
> This approach is simpler to set up but less flexible — you cannot reuse the individual item data for calculations or conditional logic in the template. If you need that, use the [JSON string approach](#workaround-json-string) or the [Builder approach](#workaround-builder-json-parse) instead.


### Alternative: Use an Automation Platform {#alternative-automation-platform}

If you need structured array data without any workaround, consider routing the generation through an automation platform like [Make](https://pdfmonkey.io/docs/integrations/make.md) or [Zapier](https://pdfmonkey.io/docs/integrations/zapier.md). These platforms support line items natively and can receive a trigger from Glide via webhook, then call the PDFMonkey API with a properly structured JSON payload.

## Troubleshooting {#troubleshooting}

### Blank Documents {#blank-documents}

If the download link is generated but the document is blank:

- **Check your variable names.** Column names with spaces do not work as variable keys. Use `camelCase` or `snake_case` instead. For example, use `customerName`, not `Customer Name`.
- **Check your test data in PDFMonkey.** Open your template, go to the **Test data** tab, and verify the document renders correctly with sample JSON. If it works in PDFMonkey but not from Glide, the issue is in the data mapping.
- **Check the PDFMonkey history.** Open your PDFMonkey dashboard and look at the document in the **History** tab. The payload shows exactly what data Glide sent, making it easy to spot missing or misnamed variables.

### File Output Column Type {#file-output-column-type}

The **File output** field should point to a **text** column in your Glide data source. Using a URL column or other types may cause the link to not be saved correctly.

### Document Generation Fails {#document-generation-fails}

If no link appears in the output column:

- Verify your **API Secret Key** is correct in the integration settings.
- Confirm your **Template ID** is valid and the template is published.
- Check the PDFMonkey dashboard for error details on the failed document.

### Download URL Expired {#download-url-expired}

The [download URL](https://pdfmonkey.io/docs/generating-documents/download-url.md) is valid for 1 hour. If the link stops working after that, the URL has expired. You can:

- Generate a new document to get a fresh link.
- Use a [share link](https://pdfmonkey.io/docs/generating-documents/share-links.md) for permanent access (available on Premium plans).

For more details, see [Download URL Returns 403](https://pdfmonkey.io/docs/troubleshooting/download-url-gives-403.md).

### Glide Updates Consumption {#glide-updates-consumption}

Each successful execution of the Generate PDF file action consumes Glide updates. The exact number is shown when you configure the action. Failed actions do not consume updates. See [Glide's billing documentation](https://www.glideapps.com/docs/billing) for details on update costs and quotas.

## Next Steps {#next-steps}

- [From Zero to First Document](https://pdfmonkey.io/docs/getting-started/from-zero-to-first-document.md): Set up your PDFMonkey account and create your first template
- [Defining Dynamic Data](https://pdfmonkey.io/docs/code-templates/defining-dynamic-data.md): Learn how to structure the JSON payload for your templates
- [Document Statuses](https://pdfmonkey.io/docs/generating-documents/document-statuses.md): Understand the lifecycle of a generated document
- [Webhooks](https://pdfmonkey.io/docs/generating-documents/webhooks.md): Receive real-time notifications when documents finish generating
- [Download URL](https://pdfmonkey.io/docs/generating-documents/download-url.md): How download URLs work and when they expire
- Explore other integrations: [Zapier](https://pdfmonkey.io/docs/integrations/zapier.md), [Make](https://pdfmonkey.io/docs/integrations/make.md), [n8n](https://pdfmonkey.io/docs/integrations/n8n.md), [Workato](https://pdfmonkey.io/docs/integrations/workato.md), [Bubble](https://pdfmonkey.io/docs/integrations/bubble.md)


## FAQ

**How do I generate PDFs from a Glide app with PDFMonkey?**

In your Glide app Settings, add the PDFMonkey integration with your API Secret Key. Then use the Generate PDF file action in a button, form, or workflow, providing your Template ID, a filename, dynamic values, and a text column for the output link.

**Can I send line items or arrays from Glide to PDFMonkey?**

Not directly. Glide passes flat key/value pairs, so it cannot send arrays natively. The workaround is to build a JSON string in Glide using template columns and a Joined List column, then parse it in your PDFMonkey template with parse_json (Code Templates) or JSON.parse in Custom JS (Builder Templates).

**Why are my Glide-generated PDFMonkey documents blank?**

The most common cause is mismatched variable names. Column names with spaces don’t work as variable keys—use camelCase or snake_case instead. Check the document payload in PDFMonkey’s History tab to see exactly what data Glide sent.


---

# InvoiceBerry (via Zapier)

Source: https://pdfmonkey.io/docs/integrations/invoiceberry.md
![](https://pdfmonkey.io/docs/img/invoiceberry-logo.png)

## What is InvoiceBerry?

InvoiceBerry is an online invoicing tool preferably used by small business owners for their business. It helps the customer create and customize invoices according to their business needs, create and send quotes to their customers, setup recurring invoices, send reminders, and track expenses for their businesses. It provides user-friendly and feasible environment to keep finance and business accounting at one place.

## How does InvoiceBerry work with PDFMonkey?

InvoiceBerry is online invoicing software made to simplify your invoicing processes and PDFMonkey is an easy way to generate PDF documents. Integrating these two apps will help to automatically generate PDF documents and find documents in response to newly created InvoiceBerry clients, invoices, expenses and more. Currently there are [14 possible Zapier integrations between PDFMonkey and InvoiceBerry](https://www.zapier.com/apps/pdfmonkey/integrations/invoiceberry).

## What can you do with InvoiceBerry and PDFMonkey?

* Generate PDF from newly created InvoiceBerry invoice
* Create client in InvoiceBerry when a new document is generated in PDFMonkey
* Find document in PDFMonkey from newly created client in InvoiceBerry
* Find document In PDFMonkey in response to newly created InvoiceBerry invoice


## FAQ

**How does InvoiceBerry integrate with PDFMonkey?**

InvoiceBerry connects to PDFMonkey through Zapier. You can set up automated workflows that generate custom PDF documents whenever a new invoice, client, or expense is created in InvoiceBerry.

**What can I automate between InvoiceBerry and PDFMonkey?**

You can generate PDFs from newly created invoices, create InvoiceBerry clients when documents are generated, and find documents in response to new clients or invoices. There are 14 possible Zapier integrations between the two apps.


---

# Ruby SDK

Source: https://pdfmonkey.io/docs/integrations/ruby-sdk.md
We provide a [Ruby SDK](https://github.com/pdfmonkey/pdfmonkey-ruby) to connect to PDFMonkey. This gem is the quickest way to use our API with Ruby.

GitHub: [https://github.com/pdfmonkey/pdfmonkey-ruby](https://github.com/pdfmonkey/pdfmonkey-ruby)

## Installation

Add this line to your application's Gemfile:

```ruby title="Gemfile"
gem 'pdfmonkey'
```

And then execute:

```bash
$ bundle
```

Or install it yourself as:

```bash
$ gem install pdfmonkey
```

## Usage

### Setting up authentication

#### Using the default environment variable

PDFMonkey looks for the `PDFMONKEY_PRIVATE_KEY` environment variable. This variable should contain your private key obtained at https://dashboard.pdfmonkey.io/account.

```bash
PDFMONKEY_PRIVATE_KEY=j39ckj4…
```

#### Setting credentials manually

You can set up your credentials explicitly in your application:

```ruby
Pdfmonkey.configure do |config|
  config.private_key = 'j39ckj4…'
end
```

#### Per-request credentials

Configuration is global. If you need per-request credentials (e.g. multi-tenant scenarios), use `with_adapter`:

```ruby
config = Pdfmonkey::Configuration.new
config.private_key = 'tenant-specific-key'

adapter = Pdfmonkey::Adapter.new(config: config)

Pdfmonkey.with_adapter(adapter) do
  Pdfmonkey::Document.generate!(
    document_template_id: 'b13ebd75-…',
    payload: { name: 'John Doe' }
  )
end
```

All operations inside the block use the given adapter. Calls outside the block continue using the global configuration.

### Documents

#### Synchronous generation

If you want to wait for a document's generation before continuing with your workflow, use the `generate!` method. It requests a document generation and waits for it to succeed or fail before returning.

```ruby
document = Pdfmonkey::Document.generate!(
  document_template_id: 'b13ebd75-d290-409b-9cac-8f597ae3e785',
  payload: { name: 'John Doe' }
)

document.status       # => 'success'
document.download_url # => 'https://…'
```

> [!WARNING]
> **The download URL is temporary**
>
> The download URL of a document is only valid **for 1 hour**. Past this delay, reload the document to obtain a new one:
&gt; 
&gt; ```ruby
&gt; document.reload!
&gt; ```


#### Asynchronous generation

PDFMonkey was created with an asynchronous workflow in mind. It provides [webhooks](https://pdfmonkey.io/docs/generating-documents/webhooks.md) to inform you of a document's generation success or failure.

To leverage this behavior and continue working while your document is being generated, use the `generate` method:

```ruby
document = Pdfmonkey::Document.generate(
  document_template_id: 'b13ebd75-d290-409b-9cac-8f597ae3e785',
  payload: { name: 'John Doe' }
)

document.status       # => 'pending'
document.download_url # => nil
```

If you have a webhook URL set up, it will be called with your document once the generation is complete. You can simulate it for testing with the following cURL command:

```bash
curl <url of your app> \
  -X POST \
  -H 'Content-Type: application/json' \
  -d '{
        "document": {
          "id": "76bebeb9-9eb1-481a-bc3c-faf43dc3ac81",
          "app_id": "d9ec8249-65ae-4d50-8aee-7c12c1f9683a",
          "created_at": "2020-01-02T03:04:05.000+01:00",
          "document_template_id": "f7fbe2b4-a57c-46ee-8422-5ae8cc37daac",
          "meta": "{\"_filename\":\"my-doc.pdf\"}",
          "output_type": "pdf",
          "status": "success",
          "updated_at": "2020-01-02T03:04:15.000+01:00",
          "xml_data": null,
          "payload": "{\"name\": \"John Doe\"}",
          "download_url": "https://example.com/76bebeb9-9eb1-481a-bc3c-faf43dc3ac81.pdf",
          "checksum": "ac0c2b6bcc77e2b01dc6ca6a9f656b2d",
          "failure_cause": null,
          "filename": "my-doc.pdf",
          "generation_logs": [],
          "preview_url": "https://preview.pdfmonkey.io/pdf/web/viewer.html?file=…",
          "public_share_link": "https://example.com/76bebeb9-9eb1-481a-bc3c-faf43dc3ac81.pdf"
        }
      }'
```

#### Draft documents

You can create a draft document that won't be queued for generation.

> [!TIP]
> This is useful for embedding a preview via `preview_url` before triggering generation. That&#39;s what we do in the PDFMonkey dashboard to show you a preview of your document before generating it, using an `iframe`.


```ruby
draft = Pdfmonkey::Document.create_draft(
  document_template_id: 'b13ebd75-d290-409b-9cac-8f597ae3e785',
  payload: { name: 'John Doe' }
)
draft.status      # => 'draft'
draft.preview_url # => 'https://…'

# When ready, trigger generation and wait for completion:
draft.generate!
draft.status       # => 'success'
draft.download_url # => 'https://…'

# Or trigger generation without waiting:
draft.generate
draft.status # => 'pending'
```

#### Attaching meta data

In addition to the document's payload you can add meta data when generating a document. Pass the `meta:` keyword argument to the `generate!` and `generate` methods:

```ruby
meta = {
  _filename: 'john-doe-contract.pdf',
  client_id: '123xxx123'
}

document = Pdfmonkey::Document.generate!(
  document_template_id: template_id,
  payload: payload,
  meta: meta
)
document.meta
# => '{"_filename":"john-doe-contract.pdf","client_id":"123xxx123"}'

document = Pdfmonkey::Document.generate(
  document_template_id: template_id,
  payload: payload,
  meta: meta
)
document.meta
# => '{"_filename":"john-doe-contract.pdf","client_id":"123xxx123"}'
```

#### Image generation

Image generation uses the same API flow as PDF generation. The template's `output_type` attribute indicates whether it produces `'pdf'` or `'image'` output. Image-specific options are passed through the `meta` parameter:

```ruby
doc = Pdfmonkey::Document.generate!(
  document_template_id: template_id,
  payload: payload,
  meta: {
    _type: 'png',       # webp (default), png, or jpg
    _width: 800,        # pixels
    _height: 600,       # pixels
    _quality: 80        # webp only, default 100
  }
)
doc.download_url # => URL to the generated image
```

#### Updating a document

```ruby
document.update!(status: 'pending')
```

#### Listing documents

```ruby
cards = Pdfmonkey::Document.list_cards(page: 1, status: 'success')

cards.each do |card|
  puts card.id
  puts card.status
end

cards.current_page # => 1
cards.total_pages  # => 5

# Navigate pages
next_cards = cards.next_page
prev_cards = cards.prev_page
```

You can filter by `document_template_id:`, `status:`, `workspace_id:`, and `updated_since:`.

#### Fetching a document

> [!CAUTION]
> **Prefer fetch_card over fetch**
>
> Fetching a full document includes its payload, meaning it could be large depending on the data you provided. We **strongly** recommend using only `fetch_card` unless you have a specific reason to fetch the full document.


You can fetch an existing document using `.fetch` (or its explicit alias `.fetch_full`):

```ruby
document = Pdfmonkey::Document.fetch('76bebeb9-9eb1-481a-bc3c-faf43dc3ac81')
```

To fetch just the lightweight card representation (recommended):

```ruby
card = Pdfmonkey::Document.fetch_card('76bebeb9-9eb1-481a-bc3c-faf43dc3ac81')
```

#### Deleting a document

You can delete an existing document using the `.delete` method:

```ruby
Pdfmonkey::Document.delete('76bebeb9-9eb1-481a-bc3c-faf43dc3ac81')
#=> true
```

Alternatively you can call the `#delete!` method on a document instance:

```ruby
document.delete!
#=> true
```

### Error handling

API errors and network errors raise exceptions:

```ruby
begin
  document = Pdfmonkey::Document.generate(
    document_template_id: template_id,
    payload: data
  )
rescue Pdfmonkey::ApiError => e
  e.message     # => "Document template must exist"
  e.errors      # => ["Document template must exist"]
  e.status_code # => 422
rescue Pdfmonkey::ConnectionError => e
  e.message # => "Failed to open TCP connection to api.pdfmonkey.io:443 ..."
end
```

When using `generate!`, an additional exception may be raised if the document's status is `'error'` or `'failure'`:

```ruby
begin
  document = Pdfmonkey::Document.generate!(
    document_template_id: template_id,
    payload: data
  )
rescue Pdfmonkey::GenerationError => e
  e.message  # => "Document generation failed: Template error"
  e.document # => #<Pdfmonkey::Document …> (the failed document)
end
```

All exception classes inherit from `Pdfmonkey::Error`, so you can rescue broadly:

```ruby
begin
  document = Pdfmonkey::Document.generate!(
    document_template_id: template_id,
    payload: data
  )
rescue Pdfmonkey::Error => e
  puts "Something went wrong: #{e.message}"
end
```

### Templates

#### Fetching a template

> [!CAUTION]
> **Full templates can be large**
>
> Fetching a full template includes its body and settings, which can be large. Use `list_cards` when you only need metadata.


```ruby
template = Pdfmonkey::Template.fetch('b13ebd75-d290-409b-9cac-8f597ae3e785')
template.identifier # => 'my-invoice'
template.body       # => '<h1>Invoice</h1>…'  (published version)
template.body_draft # => '<h1>Invoice v2</h1>…'  (draft version)
```

You can also use the explicit alias `.fetch_full`:

```ruby
template = Pdfmonkey::Template.fetch_full('b13ebd75-d290-409b-9cac-8f597ae3e785')
```

#### Creating a template

When creating a template, attributes like `body`, `scss_style`, `settings`, `sample_data`, and `pdf_engine_id` are automatically written to their draft counterparts (`body_draft`, `scss_style_draft`, etc.):

```ruby
template = Pdfmonkey::Template.create(
  identifier: 'my-invoice',
  body: '<h1>Invoice</h1>'
)
template.body_draft # => '<h1>Invoice</h1>'
```

#### Updating a template

Like `create`, `update!` writes to the draft fields:

```ruby
template.update!(body: '<h1>Updated Invoice</h1>')
template.body_draft # => '<h1>Updated Invoice</h1>'
```

#### Publishing a template

Once you're happy with the draft, publish it to copy all draft fields to their published counterparts:

```ruby
template.publish!
template.body # => '<h1>Updated Invoice</h1>'
```

#### Listing templates

```ruby
cards = Pdfmonkey::Template.list_cards(workspace_id: 'f4ab650c-…')
```

#### Deleting a template

```ruby
Pdfmonkey::Template.delete('b13ebd75-…')
# or
template.delete!
```

### Template Folders

```ruby
# List folders
folders = Pdfmonkey::TemplateFolder.list

# Create a folder
folder = Pdfmonkey::TemplateFolder.create(identifier: 'invoices')

# Fetch a folder
folder = Pdfmonkey::TemplateFolder.fetch('folder-id')

# Update a folder
folder.update!(identifier: 'receipts')

# Delete a folder
Pdfmonkey::TemplateFolder.delete('folder-id')
# or
folder.delete!
```

To create a template inside a specific folder, pass the `template_folder_id`:

```ruby
folder = Pdfmonkey::TemplateFolder.create(identifier: 'invoices')

template = Pdfmonkey::Template.create(
  identifier: 'monthly-invoice',
  body: '<h1>Invoice</h1>',
  template_folder_id: folder.id
)
```

### Snippets

Snippets are reusable HTML components that can be included in templates.

```ruby
# List snippets
snippets = Pdfmonkey::Snippet.list

# Create a snippet
snippet = Pdfmonkey::Snippet.create(
  identifier: 'header',
  code: '<div class="header">…</div>',
  workspace_id: 'f4ab650c-…'
)

# Fetch a snippet
snippet = Pdfmonkey::Snippet.fetch('snippet-id')

# Update a snippet
snippet.update!(code: '<div class="header">Updated</div>')

# Delete a snippet
Pdfmonkey::Snippet.delete('snippet-id')
# or
snippet.delete!
```

### Workspaces

Workspaces are read-only resources. They can be listed and fetched but not created, updated, or deleted through the API.

```ruby
# List workspaces
workspaces = Pdfmonkey::Workspace.list_cards

workspaces.each do |workspace|
  puts workspace.identifier
end

# Fetch a workspace
workspace = Pdfmonkey::Workspace.fetch('workspace-id')
workspace.identifier # => 'my-app'
```

### Webhooks

Webhooks allow you to receive notifications when documents are generated.

```ruby
# Create a webhook for all templates in a workspace
webhook = Pdfmonkey::Webhook.create(
  url: 'https://example.com/webhooks/pdfmonkey',
  event: 'document.generation.completed',
  workspace_id: 'f4ab650c-…'
)

# Optionally restrict to specific templates
webhook = Pdfmonkey::Webhook.create(
  url: 'https://example.com/webhooks/pdfmonkey',
  event: 'document.generation.completed',
  workspace_id: 'f4ab650c-…',
  document_template_ids: ['tpl-1', 'tpl-2']
)

# You can also specify a custom channel for routing
webhook = Pdfmonkey::Webhook.create(
  url: 'https://example.com/webhooks/pdfmonkey',
  event: 'document.generation.completed',
  workspace_id: 'f4ab650c-…',
  custom_channel: 'invoices'
)

# Delete a webhook
Pdfmonkey::Webhook.delete('webhook-id')
# or
webhook.delete!
```

### Engines

List available PDF rendering engines:

```ruby
engines = Pdfmonkey::Engine.list

engines.each do |engine|
  puts "#{engine.name} (deprecated: #{engine.deprecated_on || 'no'})"
end
```

You can use an engine when creating a template:

```ruby
engines = Pdfmonkey::Engine.list
v4 = engines.find { |e| e.name == 'v4' }

template = Pdfmonkey::Template.create(
  identifier: 'my-template',
  body: '<h1>Hello</h1>',
  pdf_engine_id: v4.id
)
```

### Current User

Retrieve information about the authenticated user:

```ruby
user = Pdfmonkey::CurrentUser.fetch

user.email               # => 'user@example.com'
user.current_plan        # => 'pro'
user.available_documents # => 1000
```

### Pagination

All list methods return `Pdfmonkey::Collection` objects that support pagination:

```ruby
collection = Pdfmonkey::Document.list_cards(page: 1)

collection.current_page     # => 1
collection.total_pages      # => 5
collection.next_page_number # => 2
collection.prev_page_number # => nil

# Navigate to next/previous pages
next_page = collection.next_page  # => Collection or nil
prev_page = collection.prev_page  # => Collection or nil
```

> [!NOTE]
> Collections are `Enumerable`. Methods like `.each`, `.map`, and `.select` operate on the items **of the current page only** -- they do not automatically fetch subsequent pages.


```ruby
# These all act on the current page's items
collection.each { |item| puts item.id }
collection.map(&:status)
collection.select { |item| item.status == 'success' }

# To process all pages, navigate manually
page = Pdfmonkey::Template.list_cards(page: 1)
while page
  page.each { |item| process(item) }
  page = page.next_page
end
```

### Serialization

All resources support `to_json` and `to_h`:

```ruby
document.to_json # => '{"document":{"id":"…","status":"success",…}}'
document.to_h    # => {id: "…", status: "success", errors: nil, …}
```

> [!TIP]
> `to_json` wraps attributes under the resource&#39;s API member key, omits `nil` values, and strips the `errors` attribute (it is intended for API requests). Use `to_h` when you need the full attribute hash for logging or caching.



## FAQ

**How do I install the PDFMonkey Ruby SDK?**

Add gem ‘pdfmonkey’ to your Gemfile and run bundle install, or run gem install pdfmonkey directly. Set your API key via the PDFMONKEY_PRIVATE_KEY environment variable or configure it in an initializer.

**What is the difference between generate! and generate in the PDFMonkey Ruby gem?**

generate! is synchronous—it blocks until the document reaches success or failure, then returns the document with a download URL. generate is asynchronous—it returns immediately with a pending status, and you handle the result via webhooks.

**Can I use per-request API keys with the PDFMonkey Ruby SDK?**

Yes. Create a Pdfmonkey::Configuration with a tenant-specific key, wrap it in an Adapter, and pass it to Pdfmonkey.with_adapter. All operations inside the block use that adapter while calls outside continue using the global configuration.

**How do I handle errors in the PDFMonkey Ruby SDK?**

Rescue Pdfmonkey::ApiError for API errors (includes status_code and errors), Pdfmonkey::ConnectionError for network issues, or Pdfmonkey::GenerationError when using generate! and the document fails. All inherit from Pdfmonkey::Error for broad rescuing.



---

# How to Delete Your PDFMonkey Account

Source: https://pdfmonkey.io/docs/account-and-security/account-deletion.md
You can delete your PDFMonkey account at any time from the [My Account](https://dashboard.pdfmonkey.io/account) page in the Dashboard. The process takes two clicks if your account has no blockers, but you may need to resolve workspace ownership or invoice issues first.

## Starting the deletion process

1. Go to the [My Account](https://dashboard.pdfmonkey.io/account) page.
2. Scroll to the **Account deletion** section at the bottom.
3. Click **Delete my account**.

PDFMonkey then runs a pre-deletion check and shows you the results. Depending on your account status, you may see one or more items to address before proceeding.

## Pre-deletion checks

When you click the delete button, PDFMonkey validates three things:

| Check | What it means | How to resolve |
|:------|:--------------|:---------------|
| **Shared workspace ownership** | You own one or more Workspaces that have collaborators. | Transfer ownership of each shared Workspace to another member before deleting your account. Go to the Workspace settings to reassign ownership. |
| **Pending invoices** | You have invoices in a pending or error state. | [Contact us](https://pdfmonkey.io/contact) to resolve the billing issue before proceeding. |
| **Existing invoices** | You have past invoices on file (already paid). | Check the confirmation box to acknowledge that you have downloaded all invoices you need. Once your account is deleted, invoices are no longer accessible. |

If you have no shared Workspaces and no pending invoices, the process goes straight to the confirmation step.

> [!WARNING]
> **Resolve blockers first**
>
> You cannot delete your account while you own shared Workspaces or have pending invoices. Both must be resolved before the final confirmation button becomes active.


## Confirming the deletion

Once all checks pass (green checkmarks), click **I am sure, delete my account** to confirm. PDFMonkey immediately:

- Cancels your subscription and archives your Stripe customer record
- Deletes your user account and all associated data
- Signs you out of the Dashboard

> [!CAUTION]
> **Deletion is permanent**
>
> There is no way to undo account deletion. All your Templates, Documents, generated files, and account settings are permanently removed. Make sure you have downloaded any files or invoices you need before confirming.


## What gets deleted

When your account is deleted, PDFMonkey removes:

- **Your user profile** (email, name, company information)
- **All Workspaces you own** (along with their Templates and Documents)
- **All generated files** (PDFs, images) stored on PDFMonkey servers
- **Your Stripe subscription and customer record**

Shared resources like community snippets and suggestions that you contributed are reassigned to a placeholder account rather than deleted.

> [!NOTE]
> Workspaces where you are a collaborator (not the owner) are not affected. Only the Workspaces you own are removed with your account.


## Before you go

> [!TIP]
> **Help us improve**
>
> If you are leaving because PDFMonkey did not meet your needs, we would genuinely appreciate hearing why. [Send us a message](https://pdfmonkey.io/contact) with your feedback. We read every response and use it to shape the product.


## Related pages

- [Data Storage and Retention](https://pdfmonkey.io/docs/account-and-security/data-storage-and-retention.md) -- what data PDFMonkey keeps and for how long
- [Security Measures](https://pdfmonkey.io/docs/account-and-security/security-measures.md) -- how your data is protected while your account is active
- [Document Retention and Automatic Deletion](https://pdfmonkey.io/docs/generating-documents/retention-and-deletion.md) -- TTL-based document cleanup
- [Our Plans](https://pdfmonkey.io/docs/pricing-and-billing/our-plans.md) -- subscription details and plan comparison


---

# How to Reset or Change Your PDFMonkey Password

Source: https://pdfmonkey.io/docs/account-and-security/changing-password.md
PDFMonkey does not have a password change option inside the Dashboard. To change or reset your password, use the password reset flow from the [Sign in page](https://dashboard.pdfmonkey.io/login).

## How to reset your password

1. Go to the [Sign in page](https://dashboard.pdfmonkey.io/login).
2. Click **Forgot your password?** below the sign-in button.
3. Enter the email address associated with your account and submit the form.
4. Check your inbox for an email from PDFMonkey containing a password reset link.
5. Click the link in the email. It opens a page where you can set a new password.
6. Enter your new password and submit. You are redirected to the Sign in page.
7. Sign in with your new password.

> [!WARNING]
> **Reset link expiration**
>
> The password reset link expires after **6 hours**. If it has expired, go back to step 1 and request a new one.


## Password requirements

Your new password must be between **6 and 128 characters**. There are no additional complexity requirements (uppercase, symbols, etc.).

## Social login accounts

If you signed up using **Google**, **GitHub**, or **Microsoft**, you do not have a PDFMonkey password. You sign in through your social provider instead. The password reset flow does not apply to social login accounts.

If you want to add a password to a social login account, [contact support](https://pdfmonkey.io/docs/getting-started/support.md) for assistance.

## Troubleshooting

### I did not receive the reset email

- Check your spam or junk folder.
- Make sure you entered the exact email address you used to register.
- If you signed up via Google, GitHub, or Microsoft, you do not have a password-based account (see [Social login accounts](#social-login-accounts) above).
- If you still cannot find the email, [contact support](https://pdfmonkey.io/docs/getting-started/support.md).

### The reset link is not working

- The link may have expired. Reset links are valid for 6 hours. Request a new one from the [Sign in page](https://dashboard.pdfmonkey.io/login).
- Make sure you are clicking the most recent reset link. If you requested multiple resets, only the last link is valid.

## Related pages

- [Account Deletion](https://pdfmonkey.io/docs/account-and-security/account-deletion.md) -- how to permanently delete your PDFMonkey account
- [Security Measures](https://pdfmonkey.io/docs/account-and-security/security-measures.md) -- how your data is protected
- [Support](https://pdfmonkey.io/docs/getting-started/support.md) -- how to reach the PDFMonkey team


---

# PDFMonkey Security: How Your Data Is Protected

Source: https://pdfmonkey.io/docs/account-and-security/security-measures.md
PDFMonkey is designed to keep your data safe at every stage: when you send it, while it is stored, and when it is no longer needed. This page covers the specific measures in place to protect your Templates, Documents, and dynamic data.

## Encryption in transit

All communication with PDFMonkey is encrypted over HTTPS (TLS). The API enforces SSL on every request; plain HTTP connections are automatically redirected to HTTPS.

This applies to:

- API requests and responses
- Dashboard and Builder sessions
- Webhook deliveries to your server
- Download URLs for generated files

## Encryption at rest

The dynamic data you send to generate a Document (the `payload` and `meta` fields) is stored in an encrypted database column. It is decrypted on-the-fly only when needed for Document generation, and is never stored in plaintext.

Generated files (PDFs and images) are stored in private S3 buckets. Access is controlled through short-lived presigned URLs that expire after one hour.

## Data isolation and access

PDFMonkey processes your data with strict boundaries:

| Principle | Details |
|:----------|:--------|
| **Purpose limitation** | Your data is used exclusively to generate the requested Document. It is never shared with partners, sold, or used for analytics. |
| **No third-party analysis** | Your data is not analyzed by PDFMonkey or any external service. |
| **Account isolation** | Each account's Templates, Documents, and generated files are isolated. You can only access resources that belong to your own Workspaces. |
| **API authentication** | Every API request requires a secret API key sent as a [Bearer token](https://pdfmonkey.io/docs/api/authentication.md). Keys are scoped to your account. |

> [!WARNING]
> **Keep your API key secret**
>
> Your API secret key carries the same privileges as your account. Never share it publicly or commit it to version control. If your key is compromised, regenerate it from the API Key page in the Dashboard.


## European hosting

PDFMonkey infrastructure is hosted on Amazon Web Services (AWS) in the **EU (Paris)** region. This includes:

- The application servers
- The database (with encrypted columns)
- The S3 buckets storing generated files and large payloads

## Data deletion

Your data is removed when you no longer need it:

- **Manual deletion**: deleting a Document through the Dashboard or API permanently removes its payload, metadata, and generated file.
- **Automatic deletion (TTL)**: each Template has a configurable retention period. When a Document's TTL expires, it is automatically deleted. See [Retention and Automatic Deletion](https://pdfmonkey.io/docs/generating-documents/retention-and-deletion.md) for details.
- **Account deletion**: deleting your account permanently removes all Workspaces, Templates, Documents, and generated files. See [Account Deletion](https://pdfmonkey.io/docs/account-and-security/account-deletion.md).

Temporary HTML pages generated during the rendering process are discarded immediately after generation.

## Webhook security

When PDFMonkey sends webhook notifications to your server, the payload is delivered over HTTPS. You can verify the authenticity of webhook deliveries using signature verification. See [Webhooks](https://pdfmonkey.io/docs/generating-documents/webhooks.md) for the full setup guide.

## Related pages

- [API Authentication](https://pdfmonkey.io/docs/api/authentication.md) -- how API requests are authenticated
- [Data Storage and Retention](https://pdfmonkey.io/docs/account-and-security/data-storage-and-retention.md) -- what data PDFMonkey stores and for how long
- [Retention and Automatic Deletion](https://pdfmonkey.io/docs/generating-documents/retention-and-deletion.md) -- TTL-based document cleanup
- [Compliance and DPA](https://pdfmonkey.io/docs/account-and-security/compliance-and-dpa.md) -- GDPR alignment, data processing agreements, and sub-processor list
- [Webhooks](https://pdfmonkey.io/docs/generating-documents/webhooks.md) -- webhook setup and signature verification


## FAQ

**Is PDFMonkey secure?**

Yes. PDFMonkey encrypts all data in transit over HTTPS (TLS) and at rest using encrypted database columns. Generated files are stored in private S3 buckets with presigned URLs that expire after one hour. All infrastructure is hosted on AWS in the EU (Paris) region.

**Where is PDFMonkey data hosted?**

All PDFMonkey infrastructure is hosted on Amazon Web Services (AWS) in the EU (Paris) region, including application servers, the database, and the S3 buckets that store generated files.

**Does PDFMonkey share or analyze my data?**

No. Your data is used exclusively to generate the requested document. It is never shared with partners, sold, or analyzed by PDFMonkey or any third-party service.


---

# PDFMonkey Data Storage and Retention Policy

Source: https://pdfmonkey.io/docs/account-and-security/data-storage-and-retention.md
PDFMonkey stores only the data needed to generate your documents and serve the resulting files. This page explains what is stored, where it lives, and when it is removed.

## What data PDFMonkey stores

There are three categories of data involved in document generation:

| Data | Description | Storage location | Lifetime |
|:-----|:------------|:-----------------|:---------|
| **Dynamic data** | The `payload` and `meta` fields you send when creating a Document | Database | Until the Document is deleted |
| **Temporary HTML page** | The rendered HTML used to produce the final file | S3 (temporary) | Discarded after generation |
| **Generated file** | The output file (PDF, PNG, WebP, or JPG) | S3 (private bucket) | Until the Document is deleted |

### Dynamic data (payload and meta)

When you create a Document, you send a JSON `payload` containing the data for your Template, along with optional `meta` fields. PDFMonkey stores this data so you can review it later in the Dashboard or retrieve it through the API.

This data is removed when the Document is deleted, whether manually or by automatic TTL expiration.

> [!NOTE]
> **Large payloads**
>
> If a payload exceeds the database column size limit, PDFMonkey stores it in a private S3 bucket instead. It is still accessible through the API in the same way and follows the same deletion rules.


### Temporary HTML page

During generation, PDFMonkey renders your Template with the provided payload into a complete HTML page. This page is uploaded to a temporary S3 location and passed to the rendering engine. Once generation finishes (whether the Document succeeds or fails), the reference to this HTML page is discarded. The HTML file itself is cleaned up by an S3 lifecycle policy.

The temporary HTML is never accessible through the API or Dashboard.

### Generated file

The output file (PDF or image) is stored in a private S3 bucket. It is only accessible through short-lived presigned URLs that expire after one hour. Each time you request a download URL, PDFMonkey generates a fresh presigned URL.

See [The Download URL](https://pdfmonkey.io/docs/generating-documents/download-url.md) for details on accessing your generated files.

## Where data is hosted

All PDFMonkey infrastructure runs on Amazon Web Services (AWS) in the **EU (Paris)** region. This includes:

- Application servers
- The database
- S3 buckets storing generated files, large payloads, and temporary HTML pages

For more details on encryption and access controls, see [Security Measures](https://pdfmonkey.io/docs/account-and-security/security-measures.md).

## When data is deleted

Your data is removed in three ways:

### Manual deletion

You can delete a Document at any time through the [Dashboard](https://dashboard.pdfmonkey.io) or via the [API](https://pdfmonkey.io/docs/api/documents.md#delete-a-document). Deleting a Document permanently removes its dynamic data (`payload` and `meta`) and its generated file.

### Automatic deletion (TTL)

Each Template has a configurable **TTL (Time To Live)** that determines how long its Documents are kept after successful generation. When a Document's TTL expires, PDFMonkey automatically deletes it.

Available TTL values range from 5 minutes to unlimited, depending on your plan. See [Document Retention and Automatic Deletion](https://pdfmonkey.io/docs/generating-documents/retention-and-deletion.md) for the full TTL reference, including values by plan and how plan changes affect retention.

### Account deletion

Deleting your PDFMonkey account permanently removes all Workspaces, Templates, Documents, and generated files associated with your account. See [Account Deletion](https://pdfmonkey.io/docs/account-and-security/account-deletion.md) for the full process.

> [!CAUTION]
> **Deletion is permanent**
>
> There is no way to recover deleted Documents, generated files, or dynamic data. If you need to keep files long-term, download them to your own storage before deletion occurs.


## Frequently asked questions

**Is my data shared with third parties?**

No. Your data is used exclusively to generate the Documents you request. It is never shared with partners, sold, or used for analytics. See [Security Measures](https://pdfmonkey.io/docs/account-and-security/security-measures.md) for the full data isolation policy.

**Where can I find PDFMonkey's Data Processing Agreement?**

PDFMonkey provides a DPA and a Data SubProcessing Agreement for organizations that require them. See [Compliance and DPA](https://pdfmonkey.io/docs/account-and-security/compliance-and-dpa.md) for download links and contact information.

**How do I know when a Document will be automatically deleted?**

The Document object does not expose an `expires_at` field directly. You can calculate it from the Template's `ttl` value and the Document's `updated_at` timestamp. See [Document Retention and Automatic Deletion](https://pdfmonkey.io/docs/generating-documents/retention-and-deletion.md#how-ttl-works) for details.

## Related pages

- [Security Measures](https://pdfmonkey.io/docs/account-and-security/security-measures.md) -- encryption, access controls, and data isolation
- [Document Retention and Automatic Deletion](https://pdfmonkey.io/docs/generating-documents/retention-and-deletion.md) -- TTL configuration and plan-based limits
- [The Download URL](https://pdfmonkey.io/docs/generating-documents/download-url.md) -- accessing generated files before they expire
- [Account Deletion](https://pdfmonkey.io/docs/account-and-security/account-deletion.md) -- what happens when you delete your account
- [Compliance and DPA](https://pdfmonkey.io/docs/account-and-security/compliance-and-dpa.md) -- data processing agreements
- [Our Plans](https://pdfmonkey.io/docs/pricing-and-billing/our-plans.md) -- plan comparison including retention limits


## FAQ

**What data does PDFMonkey store?**

PDFMonkey stores three types of data: the dynamic data you send (payload and meta), a temporary HTML page used during rendering, and the generated file (PDF or image). The dynamic data and generated file persist until the document is deleted; the HTML page is discarded after generation.

**Where is PDFMonkey data hosted?**

All PDFMonkey infrastructure is hosted on Amazon Web Services (AWS) in the EU (Paris) region, including application servers, the database, and S3 storage buckets.

**How long does PDFMonkey keep my documents?**

Each template has a configurable TTL (Time To Live). When a document's TTL expires, PDFMonkey automatically deletes it along with its generated file and dynamic data. You can also delete documents manually at any time. TTL options range from 5 minutes to unlimited depending on your plan.

**Can I delete my data from PDFMonkey?**

Yes. You can delete individual documents through the Dashboard or API, configure automatic deletion via TTL, or delete your entire account to remove all data permanently.


---

# PDFMonkey GDPR Compliance and Data Processing Agreement (DPA)

Source: https://pdfmonkey.io/docs/account-and-security/compliance-and-dpa.md
PDFMonkey aligns its data handling practices with GDPR requirements. This page covers the company's compliance posture, the available legal agreements, and the key privacy commitments built into the platform.

## Compliance posture

PDFMonkey does not hold a formal compliance certification (such as SOC 2 or ISO 27001). As a small, focused company, pursuing these certifications is not currently feasible. Instead, PDFMonkey implements concrete [security measures](https://pdfmonkey.io/docs/account-and-security/security-measures.md) that protect your data at every stage: encryption in transit and at rest, EU-only hosting, strict access controls, and configurable data retention.

> [!NOTE]
> **No certification does not mean no security**
>
> The absence of a certification badge does not reflect the absence of security practices. PDFMonkey&#39;s technical and organizational measures are documented in the [Security Measures](https://pdfmonkey.io/docs/account-and-security/security-measures.md) page and formalized in the DPA below.


## GDPR data roles

When you use PDFMonkey, the GDPR roles are defined as follows:

| Role | Party | Responsibility |
|:-----|:------|:---------------|
| **Data Controller** | You (the User) | You determine what personal data is sent to PDFMonkey and for what purpose. |
| **Data Processor** | PDFMonkey | PDFMonkey processes your data exclusively to generate the Documents you request, following your instructions. |

PDFMonkey processes your data only for the purpose of providing the service. It is never analyzed, shared with partners, sold, or used for any other purpose.

If you are yourself a Processor acting on behalf of a Controller (for example, generating documents for your own clients), PDFMonkey provides a separate **Data SubProcessing Agreement** (DsPA) that formalizes the Controller-Processor-SubProcessor chain.

## Data Processing Agreement (DPA)

PDFMonkey provides two standard agreements covering data processing obligations under GDPR:

| Document | Use case | Link |
|:---------|:---------|:-----|
| **Data Processing Agreement (DPA)** | You are the Controller; PDFMonkey is your Processor | [Download DPA (PDF)](https://pdfmonkey-resources.s3-eu-west-3.amazonaws.com/documents/2023-03-01%20PDFMonkey%20DPA.pdf) |
| **Data SubProcessing Agreement (DsPA)** | You are a Processor; PDFMonkey is a SubProcessor acting on your Controller's behalf | [Download DsPA (PDF)](https://pdfmonkey-resources.s3-eu-west-3.amazonaws.com/documents/2023-03-01%20PDFMonkey%20DsPA.pdf) |

Both agreements are dated March 1, 2023 and cover:

- Definitions aligned with GDPR terminology
- Data processing obligations and instructions
- Security measures and confidentiality
- Audit rights (once per year, 30 days' notice)
- Breach notification procedures
- International data transfer safeguards
- Approved sub-processor list
- Data deletion on termination

> [!TIP]
> **Need a custom agreement?**
>
> If your organization requires PDFMonkey to review and sign a custom data privacy agreement, [contact us](https://pdfmonkey.io/contact). DPA-related inquiries can also be sent directly to tinymonkey@pdfmonkey.io.


## Key GDPR commitments

The following commitments are formalized in the DPA and reflected in PDFMonkey's technical implementation:

### EU-only data hosting

All infrastructure runs on AWS in the **EU (Paris)** region. Your data does not leave the EEA unless a sub-processor requires it, in which case the transfer is protected by GDPR-compliant safeguards (adequacy decisions or standard contractual clauses). See [Security Measures: European hosting](https://pdfmonkey.io/docs/account-and-security/security-measures.md#european-hosting) for details.

### Purpose limitation

PDFMonkey processes your data exclusively to generate the Documents you request. It is never analyzed by PDFMonkey or any external service, never shared with third parties, and never used for profiling or analytics.

### Data minimization and retention

You control how long your data is stored. Each Template has a configurable [TTL (Time To Live)](https://pdfmonkey.io/docs/generating-documents/retention-and-deletion.md) that automatically deletes Documents after the retention period expires. You can also [delete Documents manually](https://pdfmonkey.io/docs/generating-documents/retention-and-deletion.md#manual-deletion) at any time. See [Data Storage and Retention](https://pdfmonkey.io/docs/account-and-security/data-storage-and-retention.md) for the full picture of what is stored and when it is removed.

### Breach notification

If PDFMonkey becomes aware of a personal data breach affecting your data, it notifies you without undue delay. The notification includes the nature and scope of the breach, a point of contact, likely consequences, and remediation measures taken or proposed.

### Data deletion on termination

When you [delete your account](https://pdfmonkey.io/docs/account-and-security/account-deletion.md), PDFMonkey ceases all processing and permanently destroys all your data, including Templates, Documents, generated files, and dynamic data.

## Approved sub-processors

PDFMonkey uses a limited set of sub-processors. The DPA requires PDFMonkey to notify you in writing before adding or replacing a sub-processor, giving you time to object.

| Sub-processor | Purpose |
|:--------------|:--------|
| **Amazon Web Services** | Hosting and storage |
| **Heroku** | Hosting |
| **SendGrid** | Email delivery |
| **Dropbox** | Invoice storage |
| **Svix** | Webhook delivery |
| **Zapier** | Integration platform |
| **Rollbar** | Error logging |
| **Sentry** | Error logging |
| **Cloudflare** | DNS and network services |

For full contact details and compliance links for each sub-processor, see Section 5 of the [DPA](https://pdfmonkey-resources.s3-eu-west-3.amazonaws.com/documents/2023-03-01%20PDFMonkey%20DPA.pdf) or [DsPA](https://pdfmonkey-resources.s3-eu-west-3.amazonaws.com/documents/2023-03-01%20PDFMonkey%20DsPA.pdf).

## Frequently asked questions

**Does PDFMonkey have SOC 2 or ISO 27001 certification?**

No. PDFMonkey is a small company and does not currently hold formal compliance certifications. The [Security Measures](https://pdfmonkey.io/docs/account-and-security/security-measures.md) page describes the technical and organizational measures in place.

**Can I audit PDFMonkey?**

Yes. The DPA grants you the right to audit PDFMonkey's data processing practices once per year, during business hours, with at least 30 days' written notice. Audit costs are borne by you unless the audit reveals non-compliance on PDFMonkey's part.

**What happens to my data if I cancel my subscription?**

When you [delete your account](https://pdfmonkey.io/docs/account-and-security/account-deletion.md), PDFMonkey permanently deletes all your Workspaces, Templates, Documents, and generated files. See [Account Deletion](https://pdfmonkey.io/docs/account-and-security/account-deletion.md) for the full process.

**Is my data transferred outside the EU?**

PDFMonkey commits to processing data within the EEA. If a sub-processor requires a transfer outside the EEA, GDPR-compliant safeguards (adequacy decisions or standard contractual clauses) are in place.

## Related pages

- [Security Measures](https://pdfmonkey.io/docs/account-and-security/security-measures.md) -- encryption, access controls, and data isolation
- [Data Storage and Retention](https://pdfmonkey.io/docs/account-and-security/data-storage-and-retention.md) -- what data PDFMonkey stores and for how long
- [Document Retention and Automatic Deletion](https://pdfmonkey.io/docs/generating-documents/retention-and-deletion.md) -- TTL configuration and plan-based limits
- [Account Deletion](https://pdfmonkey.io/docs/account-and-security/account-deletion.md) -- what happens when you delete your account
- [Support](https://pdfmonkey.io/docs/getting-started/support.md) -- how to reach the PDFMonkey team


## FAQ

**Is PDFMonkey GDPR compliant?**

PDFMonkey follows GDPR principles: data is processed exclusively within the EU (AWS Paris region), encrypted in transit and at rest, never shared with third parties, and deleted when no longer needed. PDFMonkey acts as a data Processor on your behalf.

**Does PDFMonkey provide a Data Processing Agreement (DPA)?**

Yes. PDFMonkey provides a standard DPA and a Data SubProcessing Agreement (DsPA), both available for download. If your organization requires a custom data privacy agreement, you can contact PDFMonkey to arrange review and signing.

**Where is PDFMonkey data hosted?**

All PDFMonkey infrastructure is hosted on Amazon Web Services (AWS) in the EU (Paris) region. This includes application servers, the database, and S3 storage. Data is processed exclusively within the EEA.

**What sub-processors does PDFMonkey use?**

PDFMonkey uses a limited set of sub-processors: AWS (hosting and storage), Heroku (hosting), SendGrid (email), Dropbox (invoice storage), Svix and Zapier (integrations), Rollbar and Sentry (error logging), and Cloudflare (DNS). The full list is detailed in the DPA.



---

# PDFMonkey Plans and Pricing: Free, Starter, Pro, Pro+, Premium

Source: https://pdfmonkey.io/docs/pricing-and-billing/our-plans.md
PDFMonkey offers five plans to match different document generation volumes. Every new account starts with a [30-day Pro trial](https://pdfmonkey.io/docs/getting-started/the-30-day-trial.md) so you can test premium features before choosing a plan. Visit [pdfmonkey.io/pricing](https://pdfmonkey.io/pricing) for current prices.

## Feature comparison {#feature-comparison}

| Feature | Free | Starter | Pro | Pro+ | Premium |
|:--------|:----:|:-------:|:---:|:----:|:-------:|
| Documents per month | 20 | 300 | 3,000 | 5,000 | 60,000 |
| [Document retention](https://pdfmonkey.io/docs/generating-documents/retention-and-deletion.md) | 1 day | 1 day | 7 days | Unlimited | Unlimited |
| [External resources](https://pdfmonkey.io/docs/getting-started/external-resources.md) | No | Yes | Yes | Yes | Yes |
| Team members | 1 | 1 | 2 | Unlimited | Unlimited |
| [Share links](https://pdfmonkey.io/docs/generating-documents/share-links.md) | No | No | No | Yes | Yes |
| Max generation time | 30 sec | 30 sec | 2 min | 3 min | 5 min |
| [Pay-as-you-go](https://pdfmonkey.io/docs/pricing-and-billing/pay-as-you-go.md) | No | Yes | Yes | Yes | Yes |

> [!TIP]
> **Not sure which plan you need?**
>
> Start with the Free plan and upgrade any time. Plan changes take effect immediately and billing is prorated. See [Changing My Plan](https://pdfmonkey.io/docs/pricing-and-billing/changing-my-plan.md).


## Plan details {#plan-details}

### Free

The Free plan gives you 20 documents per month with a 30-second generation time limit. It is a good fit for testing PDFMonkey before committing to a paid plan. [External resources](https://pdfmonkey.io/docs/getting-started/external-resources.md) (web fonts, remote images) are not available on this tier.

### Starter

The Starter plan raises your quota to 300 documents per month and unlocks [external resources](https://pdfmonkey.io/docs/getting-started/external-resources.md). If you generate a small volume of documents and do not need team collaboration, Starter covers the basics.

### Pro

The Pro plan supports up to 3,000 documents per month with [7-day document retention](https://pdfmonkey.io/docs/generating-documents/retention-and-deletion.md) and a 2-minute generation time limit. You can invite one additional team member, bringing the total to two seats.

### Pro+

The Pro+ plan provides 5,000 documents per month with unlimited document retention, unlimited team members, [share links](https://pdfmonkey.io/docs/generating-documents/share-links.md), and a 3-minute generation time limit.

### Premium

The Premium plan handles up to 60,000 documents per month with all the features of Pro+, plus a 5-minute generation time limit.

## Annual billing {#annual-billing}

All paid plans offer a 10% discount when you choose yearly billing. You can switch between monthly and annual billing at any time from the Dashboard. Check [pdfmonkey.io/pricing](https://pdfmonkey.io/pricing) for exact annual prices.

## Reaching your quota {#reaching-your-quota}

When you reach 80% of your monthly quota, PDFMonkey sends you a warning email. At 100%, new generation requests are blocked and documents are set to **draft** [status](https://pdfmonkey.io/docs/generating-documents/document-statuses.md). You are not charged for blocked generations.

Your quota resets automatically at the start of each billing cycle. If you need more documents before the reset, you have three options:

- **Upgrade your plan:** move to a higher tier for a larger monthly quota. See [Changing My Plan](https://pdfmonkey.io/docs/pricing-and-billing/changing-my-plan.md).
- **Buy a Boost Pack:** purchase a one-time block of extra document credits. See [Boost Packs](https://pdfmonkey.io/docs/pricing-and-billing/boost-packs.md).
- **Enable pay-as-you-go:** get billed automatically for each document beyond your quota (all paid plans). See [Pay-As-You-Go](https://pdfmonkey.io/docs/pricing-and-billing/pay-as-you-go.md).

## Custom plans {#custom-plans}

If you need more than 60,000 documents per month, [contact us](https://pdfmonkey.io/contact) to discuss a custom plan tailored to your volume.

## Frequently asked questions {#faq}

**What happens to my documents when I downgrade?**

Documents within the new plan's [retention window](https://pdfmonkey.io/docs/generating-documents/retention-and-deletion.md) are kept. Documents outside it are permanently deleted. Features exclusive to higher tiers (such as [share links](https://pdfmonkey.io/docs/generating-documents/share-links.md)) stop working until you upgrade again.

**Can I generate images as well as PDFs?**

Yes. All plans support PDF, PNG, WebP, and JPG output. See [Output Format](https://pdfmonkey.io/docs/generating-documents/output-format.md) for details.

**Do unused documents roll over to the next month?**

No. Your monthly quota resets to zero at the start of each billing cycle. Unused documents do not accumulate.

**Is there a free trial?**

Yes. Every new account gets a [30-day Pro trial](https://pdfmonkey.io/docs/getting-started/the-30-day-trial.md) with 300 documents, external resources, and a 2-minute generation time limit. When the trial ends, your account moves to the Free plan automatically.

## Related pages {#related-pages}

- [Boost Packs](https://pdfmonkey.io/docs/pricing-and-billing/boost-packs.md) -- one-time extra document credits
- [Pay-As-You-Go](https://pdfmonkey.io/docs/pricing-and-billing/pay-as-you-go.md) -- automatic per-document billing beyond your quota
- [Changing My Plan](https://pdfmonkey.io/docs/pricing-and-billing/changing-my-plan.md) -- how upgrades, downgrades, and proration work
- [30-Day Pro Trial](https://pdfmonkey.io/docs/getting-started/the-30-day-trial.md) -- what the trial includes and what happens when it ends
- [Document Retention and Deletion](https://pdfmonkey.io/docs/generating-documents/retention-and-deletion.md) -- TTL settings and plan-based retention limits
- [Share Links](https://pdfmonkey.io/docs/generating-documents/share-links.md) -- permanent public URLs for generated documents
- [External Resources](https://pdfmonkey.io/docs/getting-started/external-resources.md) -- web fonts, remote images, and external CSS/JS


## FAQ

**How much does PDFMonkey cost?**

PDFMonkey offers five plans: Free (20 documents/month), Starter (300/month), Pro (3,000/month), Pro+ (5,000/month), and Premium (60,000/month). All paid plans offer a 10% discount on annual billing. Every new account starts with a 30-day Pro trial. Visit pdfmonkey.io/pricing for current prices.

**What happens when I reach my PDFMonkey document quota?**

At 80% of your monthly quota, PDFMonkey sends a warning email. At 100%, new generation requests are blocked. You can upgrade your plan, buy a one-time Boost Pack, or enable pay-as-you-go billing to continue generating.

**Do unused PDFMonkey documents roll over to the next month?**

No. Your monthly quota resets to zero at the start of each billing cycle. Unused documents do not accumulate.

**Does PDFMonkey have a free plan?**

Yes. The Free plan gives you 20 documents per month with a 30-second generation time limit. External resources (web fonts, remote images) are not available on the free tier.


---

# Boost Packs: Buy Extra Document Generation Credits

Source: https://pdfmonkey.io/docs/pricing-and-billing/boost-packs.md
Boost Packs are one-time purchases of additional document generation credits. Each Boost Pack adds 1,000 documents to your quota for **5 EUR** (excl. taxes). Credits are available immediately and last until the end of your current billing cycle.

> [!TIP]
> **Quick summary**
>
> Plan quota is consumed first, then Boost Pack credits. Unused Boost Pack credits expire when your subscription renews.


## Pricing and availability {#pricing}

| Detail | |
|:-------|:--|
| **Price** | 5 EUR per Boost Pack (excl. taxes) |
| **Credits per pack** | 1,000 documents |
| **Minimum purchase** | 1 pack (1,000 documents) |
| **Maximum purchase** | 1,000 packs (1,000,000 documents) per transaction |
| **Available on** | All paid plans (Starter, Pro, Pro+, Premium) |
| **Refunds** | Non-refundable |

> [!WARNING]
> Boost Packs are only available to paying customers. If you are on the [Free plan](https://pdfmonkey.io/docs/pricing-and-billing/our-plans.md#plan-details), you need to upgrade to a paid plan first.


Visit [pdfmonkey.io/pricing](https://pdfmonkey.io/pricing) for the latest pricing details.

## Boost Packs vs. pay-as-you-go {#boost-packs-vs-payg}

PDFMonkey offers two ways to handle overage. They are mutually exclusive: you must choose one or the other.

| | Boost Packs | [Pay-as-you-go](https://pdfmonkey.io/docs/pricing-and-billing/pay-as-you-go.md) |
|---|---|---|
| **Billing** | One-time, upfront charge | Automatic, per-document charge |
| **Pricing** | 5 EUR per 1,000 documents (0.005 EUR/doc) | 0.005--0.008 EUR per document (varies by plan) |
| **Minimum purchase** | 1,000 documents (1 pack) | None (billed per document used) |
| **Availability** | All paid plans | All paid plans |
| **Action needed** | Manual purchase in Dashboard | None (automatic once enabled) |
| **Best for** | Predictable overage with a fixed budget | Unpredictable volume with no upfront commitment |

> [!NOTE]
> If you are on an annual plan, pay-as-you-go overage is still billed monthly for the extra usage.


## Credit consumption order {#consumption-order}

When you generate a document, PDFMonkey draws from your credits in this order:

1. **Monthly plan quota** is consumed first.
2. **Boost Pack credits** are consumed next, once your plan quota is fully depleted.

As long as your plan quota has remaining credits, your Boost Pack balance stays untouched.

## How to buy Boost Packs {#how-to-buy}

1. Open your Dashboard and go to the **Billing** section.
2. Scroll down to the **Boost Packs** area.
3. Use the **+** and **-** buttons to select the number of packs you need (each pack is 1,000 documents).
4. Check the agreement box to confirm the charge amount and terms.
5. Click **Give me a Boost Pack** (or **Give me X Boost Packs** for multiple).

The purchase is charged immediately to your default payment method on file. Credits are added to your account as soon as the payment succeeds.

> [!NOTE]
> If you see an error during purchase, make sure your payment method is up to date in the Billing section. Contact support through the in-app chat if the issue persists.


## Expiry {#expiry}

Boost Pack credits **expire at the end of your current billing cycle**. When your subscription renews, any unused Boost Pack credits are reset to zero and your quota reverts to your plan's base allowance.

If you need credits that persist across billing cycles, consider upgrading to a higher [plan tier](https://pdfmonkey.io/docs/pricing-and-billing/our-plans.md) instead.

## Frequently asked questions {#faq}

**Can I buy Boost Packs on the Free plan?**

No. Boost Packs require an active paid subscription (Starter, Pro, Pro+, or Premium). [Upgrade your plan](https://pdfmonkey.io/docs/pricing-and-billing/changing-my-plan.md) first.

**Do unused Boost Pack credits roll over to the next billing cycle?**

No. Unused credits are reset to zero when your subscription renews. Buy Boost Packs only when you need them within the current cycle.

**Can I get a refund for unused Boost Pack credits?**

No. Boost Packs are non-refundable.

**Are Boost Pack credits shared across Workspaces?**

Boost Pack credits are tied to the Workspaces you own and increase the document quota for those Workspaces. They do not apply to Workspaces owned by other accounts that you have been invited to.

**What happens if my payment method fails?**

The purchase is not completed and no credits are added. Update your payment method in the Billing section of the Dashboard and try again.

## Related pages {#related-pages}

- [Our Plans](https://pdfmonkey.io/docs/pricing-and-billing/our-plans.md) -- compare plan tiers and monthly quotas
- [Pay-As-You-Go](https://pdfmonkey.io/docs/pricing-and-billing/pay-as-you-go.md) -- automatic per-document billing beyond your quota
- [Changing My Plan](https://pdfmonkey.io/docs/pricing-and-billing/changing-my-plan.md) -- how upgrades, downgrades, and proration work
- [Document Statuses](https://pdfmonkey.io/docs/generating-documents/document-statuses.md) -- understand what happens when your quota is exhausted


## FAQ

**What are PDFMonkey Boost Packs?**

Boost Packs are one-time purchases of additional document generation credits. Each Boost Pack adds 1,000 documents to your quota for 5 EUR (excl. taxes). Credits are available immediately and last until the end of your current billing cycle.

**Can I buy Boost Packs on the Free plan?**

No. Boost Packs require an active paid subscription (Starter, Pro, Pro+, or Premium). You need to upgrade your plan first.

**Do unused Boost Pack credits roll over?**

No. Unused credits are reset to zero when your subscription renews. Buy Boost Packs only when you need them within the current billing cycle.

**How much do Boost Packs cost?**

Each Boost Pack costs 5 EUR (excl. taxes) and includes 1,000 document generation credits. You can purchase between 1 and 1,000 packs per transaction.


---

# Pay-As-You-Go: Automatic Per-Document Billing on PDFMonkey

Source: https://pdfmonkey.io/docs/pricing-and-billing/pay-as-you-go.md
Pay-as-you-go (PAYG) is an automatic billing mode that charges you for each document generated after your monthly quota is depleted. Instead of being blocked when your quota runs out, you keep generating documents and pay a small per-document fee.

> [!TIP]
> **Quick summary**
>
> PAYG has no minimum purchase and no upfront commitment. You only pay for documents generated beyond your monthly quota, billed automatically at your plan&#39;s per-document rate.

## Per-document rates {#per-document-rates}

| Plan | Rate per document |
|:-----|:------------------|
| Starter | 0.008 EUR |
| Pro | 0.007 EUR |
| Pro+ | 0.006 EUR |
| Premium | 0.005 EUR |

These rates apply to every document generated beyond your monthly plan quota, whether it produces a PDF or an [image](https://pdfmonkey.io/docs/generating-documents/output-format.md).

Visit [pdfmonkey.io/pricing](https://pdfmonkey.io/pricing) for the latest pricing details.

## Availability {#availability}

Pay-as-you-go is available on all paid plans: **Starter**, **Pro**, **Pro+**, and **Premium**. It is not available on the Free plan. See [Our Plans](https://pdfmonkey.io/docs/pricing-and-billing/our-plans.md#feature-comparison) for a full feature comparison.

## How it works {#how-it-works}

1. Your **monthly plan quota** is consumed first.
2. Once your quota is depleted, each additional document is billed at the per-document rate for your plan.
3. Overage charges are calculated at the end of the billing period and added to your next invoice.

PAYG applies to all Workspaces **you own**. It does not apply to Workspaces owned by other accounts that you have been invited to.

> [!NOTE]
> **If you are on an annual plan, PAYG overage is still billed monthly for the extra usage.**
>
> 

## Enabling pay-as-you-go {#enabling}

To enable or disable PAYG on your account, open the **Billing** section of your Dashboard and look for the pay-as-you-go toggle. If you do not see it, contact support through the in-app chat for assistance.

Once enabled, PAYG activates automatically whenever your monthly quota runs out. You do not need to take any manual action each time your quota is depleted.

## Pay-as-you-go vs. Boost Packs {#payg-vs-boost-packs}

PDFMonkey offers two ways to handle overage beyond your monthly quota. They are **mutually exclusive**: you must choose one or the other, not both.

| | Pay-as-you-go | [Boost Packs](https://pdfmonkey.io/docs/pricing-and-billing/boost-packs.md) |
|---|---|---|
| **Billing** | Automatic, per-document charge | One-time, upfront charge |
| **Pricing** | 0.005--0.008 EUR per document (varies by plan) | 5 EUR per 1,000 documents (0.005 EUR/doc) |
| **Minimum purchase** | None (billed per document used) | 1,000 documents (1 pack) |
| **Availability** | All paid plans | All paid plans |
| **Action needed** | None (automatic once enabled) | Manual purchase in Dashboard |
| **Expiry** | N/A (billed per use) | End of current billing cycle |
| **Best for** | Unpredictable volume with no upfront commitment | Predictable overage with a fixed budget |

> [!WARNING]
> **You cannot have both PAYG and Boost Packs active at the same time. If you want to switch from one overage method to the other, disable the current one first.**
>
> 

## Frequently asked questions {#faq}

**Is there a minimum number of documents for PAYG?**

No. PAYG has no minimum purchase. You are billed only for the documents you actually generate beyond your quota, even if that is a single document.

**Does PAYG apply to all my Workspaces?**

PAYG applies to Workspaces you own. If you have been invited to Workspaces owned by other accounts, your PAYG setting does not cover those Workspaces.

**What happens if I downgrade to the Free plan?**

PAYG is automatically disabled because it is not available on the Free plan. Any overage accrued before the downgrade is still billed. See [Changing My Plan](https://pdfmonkey.io/docs/pricing-and-billing/changing-my-plan.md) for details on how plan changes work.

**Can I set a spending cap?**

There is currently no built-in spending cap for PAYG. If you want to limit overage costs, consider using [Boost Packs](https://pdfmonkey.io/docs/pricing-and-billing/boost-packs.md) instead, which give you a fixed, known cost.

**Does PAYG count image generation as well as PDFs?**

Yes. Every document generated counts against your quota and toward PAYG billing, regardless of whether the output is a PDF or an [image](https://pdfmonkey.io/docs/generating-documents/output-format.md).

## Related pages {#related-pages}

- [Our Plans](https://pdfmonkey.io/docs/pricing-and-billing/our-plans.md) -- compare plan tiers and monthly quotas
- [Boost Packs](https://pdfmonkey.io/docs/pricing-and-billing/boost-packs.md) -- one-time extra document credits (mutually exclusive with PAYG)
- [Changing My Plan](https://pdfmonkey.io/docs/pricing-and-billing/changing-my-plan.md) -- how upgrades, downgrades, and proration work
- [Document Statuses](https://pdfmonkey.io/docs/generating-documents/document-statuses.md) -- understand what happens when your quota is exhausted
- [Generate Images Instead of PDFs](https://pdfmonkey.io/docs/generating-documents/output-format.md) -- image output counts toward your quota


## FAQ

**What is PDFMonkey pay-as-you-go?**

Pay-as-you-go (PAYG) is an automatic billing mode that charges you for each document generated after your monthly quota is depleted. Instead of being blocked when your quota runs out, you keep generating documents and pay a small per-document fee.

**Is there a minimum number of documents for pay-as-you-go?**

No. PAYG has no minimum purchase. You are billed only for the documents you actually generate beyond your quota, even if that is a single document.

**Can I set a spending cap on pay-as-you-go?**

There is currently no built-in spending cap for PAYG. If you want to limit overage costs, consider using Boost Packs instead, which give you a fixed, known cost.

**What is the per-document rate for pay-as-you-go?**

The per-document rate depends on your plan: Starter at 0.008 EUR, Pro at 0.007 EUR, Pro+ at 0.006 EUR, and Premium at 0.005 EUR. These rates apply to every document generated beyond your monthly plan quota.


---

# Changing Your PDFMonkey Plan: Upgrades, Downgrades, and Billing

Source: https://pdfmonkey.io/docs/pricing-and-billing/changing-my-plan.md
You can change your PDFMonkey plan at any time from the Billing section of your Dashboard. Upgrades take effect immediately; downgrades apply at the start of your next billing cycle.

## How to change your plan {#how-to-change-your-plan}

1. Open your Dashboard and go to the **Billing** section.
2. Click on **Manage My Subscription** to open the billing portal.
3. Choose a new plan tier and confirm the change.

For upgrades, PDFMonkey uses a dedicated upgrade flow that applies the change immediately after confirmation. For downgrades or cancellations, the Stripe billing portal lets you schedule the change for the end of your current billing cycle.

## Upgrading {#upgrading}

When you upgrade to a higher plan, the change takes effect **immediately**. You get instant access to the new plan's features, higher document quota, and longer generation time limit.

> [!NOTE]
> **Prorated billing**
>
> You are only charged for the remainder of your current billing cycle at the new plan&#39;s rate. The unused portion of your old plan is credited toward the new charge. If you have specific questions about how proration is calculated, contact support through the in-app chat.

### What changes on upgrade

- **Document quota** increases immediately to the new plan's allowance.
- **Generation time limit** increases to the new plan's maximum (for example, 30 seconds on Free to 2 minutes on Pro).
- **Document retention** is extended. Templates that were at the old plan's maximum TTL are automatically updated to the new plan's maximum. See [Retention and Deletion](https://pdfmonkey.io/docs/generating-documents/retention-and-deletion.md).
- **Features** unlock instantly. For example, upgrading to Pro+ or Premium activates [share links](https://pdfmonkey.io/docs/generating-documents/share-links.md) for all existing successful documents — you do not need to regenerate them.

## Downgrading {#downgrading}

When you downgrade to a lower plan, the change is **scheduled for the start of your next billing cycle**. You keep your current plan's features and quota until the cycle ends.

> [!WARNING]
> **Feature and data impact**
>
> Downgrading can permanently affect your documents. Review the sections below before confirming a downgrade.

### What changes on downgrade

- **Document quota** decreases to the new plan's allowance when the next billing cycle starts.
- **Generation time limit** decreases. Documents that need more time than the new plan allows may fail at generation time.
- **Document retention** is reduced. Templates with a TTL above the new plan's maximum are automatically lowered to that maximum, and existing documents' expiration dates are recalculated accordingly. Documents that fall outside the new retention window are permanently deleted and cannot be recovered. See [Retention and Deletion](https://pdfmonkey.io/docs/generating-documents/retention-and-deletion.md).
- **Share links** stop working if you move from Pro+ or Premium to a plan that does not include them (Pro, Starter, or Free). If you later upgrade back to Pro+ or Premium, share links reactivate for documents that still exist. See [Share Links](https://pdfmonkey.io/docs/generating-documents/share-links.md).
- **External resources** (web fonts, remote images, external CSS/JS) stop working if you downgrade to the Free plan. Documents that reference them will fail at generation time. See [External Resources](https://pdfmonkey.io/docs/getting-started/external-resources.md).
- **Pay-as-you-go** is disabled automatically if you downgrade to the Free plan. Any overage accrued before the downgrade is still billed. See [Pay-As-You-Go](https://pdfmonkey.io/docs/pricing-and-billing/pay-as-you-go.md).

## Switching billing frequency {#switching-billing-frequency}

You can switch between monthly and yearly billing. Yearly billing saves you **10%** compared to the monthly rate. You can make this change at any time from the billing portal.

When you switch from monthly to yearly, you are charged the annual price immediately (prorated for any remaining time on your current monthly cycle). Switching from yearly to monthly takes effect at the end of your current annual period.

See [Our Plans](https://pdfmonkey.io/docs/pricing-and-billing/our-plans.md) for details on available plan tiers, or visit [pdfmonkey.io/pricing](https://pdfmonkey.io/pricing) for current prices.

## Effect on overage methods {#effect-on-overage-methods}

If you have [Boost Packs](https://pdfmonkey.io/docs/pricing-and-billing/boost-packs.md) or [Pay-As-You-Go](https://pdfmonkey.io/docs/pricing-and-billing/pay-as-you-go.md) enabled, keep the following in mind:

- **Boost Pack credits** are preserved when you change plans within the same billing cycle. They still expire at the end of the cycle, regardless of the plan change.
- **Pay-as-you-go** remains active across paid plan changes. It is disabled automatically only if you move to the Free plan.
- Both overage methods are unavailable on the Free plan.

## Frequently asked questions {#faq}

**Is there a contract or minimum commitment?**

No. All PDFMonkey plans are billed on a recurring basis with no long-term contract. You can upgrade, downgrade, or cancel at any time.

**What happens to my documents when I downgrade?**

Documents within the new plan's [retention window](https://pdfmonkey.io/docs/generating-documents/retention-and-deletion.md) are kept. Documents outside it are permanently deleted when the downgrade takes effect. Features exclusive to higher tiers (such as [share links](https://pdfmonkey.io/docs/generating-documents/share-links.md)) stop working until you upgrade again.

**Can I switch plans during my 30-day trial?**

Yes. You can [upgrade to any paid plan](https://pdfmonkey.io/docs/pricing-and-billing/our-plans.md) at any point during the trial. The change takes effect immediately. See [30-Day Pro Trial](https://pdfmonkey.io/docs/getting-started/the-30-day-trial.md) for details on what the trial includes.

**Will I lose my templates if I downgrade?**

No. Your templates are never deleted when you change plans. Only generated documents are affected by retention changes.

**How is proration calculated?**

Proration is handled by Stripe. When you upgrade mid-cycle, you are credited for the unused time on your old plan and charged the proportional cost of the new plan for the remaining days in the cycle. The exact amounts appear as line items on your next invoice.

## Related pages {#related-pages}

- [Our Plans](https://pdfmonkey.io/docs/pricing-and-billing/our-plans.md) -- compare plan tiers, quotas, and features
- [Boost Packs](https://pdfmonkey.io/docs/pricing-and-billing/boost-packs.md) -- one-time extra document credits
- [Pay-As-You-Go](https://pdfmonkey.io/docs/pricing-and-billing/pay-as-you-go.md) -- automatic per-document billing beyond your quota
- [30-Day Pro Trial](https://pdfmonkey.io/docs/getting-started/the-30-day-trial.md) -- what the trial includes and what happens when it ends
- [Share Links](https://pdfmonkey.io/docs/generating-documents/share-links.md) -- permanent public URLs, and how plan changes affect them
- [Document Retention and Deletion](https://pdfmonkey.io/docs/generating-documents/retention-and-deletion.md) -- TTL settings and plan-based retention limits
- [External Resources](https://pdfmonkey.io/docs/getting-started/external-resources.md) -- what counts as an external resource and free-plan restrictions


## FAQ

**Is there a contract or minimum commitment on PDFMonkey?**

No. All PDFMonkey plans are billed on a recurring basis with no long-term contract. You can upgrade, downgrade, or cancel at any time.

**What happens to my documents when I downgrade my PDFMonkey plan?**

Documents within the new plan's retention window are kept. Documents outside it are permanently deleted when the downgrade takes effect. Features exclusive to higher tiers, such as share links, stop working until you upgrade again.

**Will I lose my templates if I downgrade?**

No. Your templates are never deleted when you change plans. Only generated documents are affected by retention changes.

**How is proration calculated when upgrading a PDFMonkey plan?**

Proration is handled by Stripe. When you upgrade mid-cycle, you are credited for the unused time on your old plan and charged the proportional cost of the new plan for the remaining days in the cycle. The exact amounts appear as line items on your next invoice.



---

# Why Is My PDFMonkey Document Blank?

Source: https://pdfmonkey.io/docs/troubleshooting/document-is-blank.md
A blank document usually means PDFMonkey generated the document successfully, but the output contains no visible content. The most common cause is an unpublished template.

## The template is not published {#template-not-published}

This is by far the most frequent cause. PDFMonkey templates have two versions of their content: a **draft** (what you edit) and a **published** version (what PDFMonkey uses to generate documents). If you have never clicked **Publish**, the published content is empty and every document generated from that template comes out blank.

### How to fix it {#fix-unpublished-template}

1. Open your template in the editor (Dashboard or Builder).
2. Click the **Publish** button.
3. Generate the document again.

> [!WARNING]
> **Publish after every change**
>
> Clicking **Publish** copies the current draft to the published version. If you edit your template and forget to publish again, documents continue to use the old published content. Always publish after making changes you want to appear in generated documents.

For a walkthrough of the full template-to-document workflow, see [From Zero to Your First Document](https://pdfmonkey.io/docs/getting-started/from-zero-to-first-document.md).

## Conditional logic hides all content {#conditional-logic}

If your template wraps content in conditional blocks, the output can be blank when the conditions are not met.

**Code templates** use Liquid syntax:

```liquid
{% if items.size > 0 %}
  <!-- content here -->
{% endif %}
```

If `items` is missing from the payload or is an empty array, nothing renders.

**Builder templates** use visibility rules on components. If a visibility condition evaluates to false for every component, the page appears empty.

### How to fix it {#fix-conditional-logic}

- Compare the variable names in your conditions against the keys in your [payload](https://pdfmonkey.io/docs/code-templates/defining-dynamic-data.md). A typo or casing mismatch (`Items` vs `items`) causes the condition to fail silently.
- Test with the payload you are actually sending, not just the template's sample data.
- Temporarily remove conditions to confirm the content renders without them, then add them back one at a time.

## A JavaScript or expression error in a Builder template {#builder-js-error}

Builder templates can break silently when they contain a runtime error. Two common scenarios:

- **External JavaScript libraries or custom code in HTML blocks.** If a script throws an uncaught error, rendering can stop and produce a blank document.
- **Syntax errors in conditions or repetitions.** A typo in a visibility condition or a repetition expression (for example a missing closing parenthesis or a misspelled variable) prevents the component from evaluating, which can result in an empty output.

### How to fix it {#fix-builder-js-error}

1. Open the template in the Builder and check the **preview**. If the preview itself is blank or broken, the error is in the template logic.
2. Look at any **HTML blocks** that include `<script>` tags. Try removing them temporarily to isolate the problem.
3. Review **condition** and **repetition** expressions on your components for typos or syntax mistakes.
4. If you use external libraries loaded via a CDN URL, make sure the URL is correct and the library is accessible at generation time.

> [!TIP]
> **When debugging, strip the template down to its simplest form (static text, no scripts, no conditions) and confirm it generates correctly. Then add complexity back one piece at a time to find what breaks.**
>
> 

## The payload is empty or missing {#empty-payload}

If you create a document without providing a `payload` (or with `"payload": {}`), any template variable evaluates to blank. When the template has no static content, the result is a blank document.

### How to fix it {#fix-empty-payload}

Make sure your API request includes a `payload` with the data your template expects:

```json
{
  "document": {
    "document_template_id": "YOUR_TEMPLATE_ID",
    "status": "pending",
    "payload": {
      "name": "Jane Doe",
      "items": [{ "description": "Widget", "price": 9.99 }]
    }
  }
}
```

See [My Data Is Not Showing Up](https://pdfmonkey.io/docs/troubleshooting/data-not-showing.md) for more on payload/template variable mismatches.

## CSS hides the content {#css-hides-content}

CSS rules can make content invisible without removing it from the HTML. Common culprits:

- `display: none` or `visibility: hidden` on a wrapper element
- White (or transparent) text on a white background
- `opacity: 0` on a container
- An element positioned off-page with `position: absolute` and large negative offsets

### How to fix it {#fix-css}

1. Open the template editor and check the **CSS** tab for rules that might hide content.
2. Use the live preview to verify that content appears as expected.
3. If you use conditional CSS classes, confirm the payload data triggers the correct class.

## Frequently asked questions {#faq}

**I can see content in the preview but the generated document is blank.**

The preview uses the **draft** version of your template, while generation uses the **published** version. Click **Publish** in the template editor and generate again.

**I published my template, but only the old content appears.**

You likely edited the template after publishing. Each time you change the draft, you need to click **Publish** again to push those changes to the published version.

**My Builder template generates a blank document even though the preview looks fine.**

Check that you have published the template from the **Dashboard** (not just saved in the Builder). Also verify that any visibility rules on your components evaluate correctly with the payload you are sending via the API.

## Related pages {#related-pages}

- [From Zero to Your First Document](https://pdfmonkey.io/docs/getting-started/from-zero-to-first-document.md) — end-to-end template and document creation walkthrough
- [Dashboard UI Tour](https://pdfmonkey.io/docs/getting-started/dashboard-ui-tour.md) — where to find the Publish button and editor tabs
- [My Data Is Not Showing Up](https://pdfmonkey.io/docs/troubleshooting/data-not-showing.md) — fix payload/variable mismatches
- [Document Statuses and Lifecycle](https://pdfmonkey.io/docs/generating-documents/document-statuses.md) — understand draft, pending, and other statuses
- [Templates API: Draft vs. Published Properties](https://pdfmonkey.io/docs/api/templates.md#draft-vs-published-properties) — how draft and published fields relate in the API


## FAQ

**Why is my PDFMonkey document blank?**

The most common cause is an unpublished template. PDFMonkey uses the published version of a template to generate documents. If you have never clicked Publish, the published content is empty and the document comes out blank.

**How do I publish a template in PDFMonkey?**

Open your template in the editor and click the Publish button. This copies the draft content (HTML, CSS, settings) to the published version that PDFMonkey uses for document generation. You need to publish again after every change you want to appear in generated documents.

**My template is published but the document is still blank. What else could be wrong?**

Other causes include: conditional logic (Liquid if/unless blocks or Builder visibility rules) that hides all content when the payload data does not match; JavaScript errors or syntax mistakes in Builder conditions and repetitions; an empty or missing payload; CSS rules like display:none or visibility:hidden that hide content; or white text on a white background.


---

# Why Is My PDFMonkey Download URL Empty or Null?

Source: https://pdfmonkey.io/docs/troubleshooting/download-url-is-empty.md
The `download_url` field is `null` whenever a document has not reached the `success` [status](https://pdfmonkey.io/docs/generating-documents/document-statuses.md). This page walks through each cause and how to fix it.

## The document status is "draft" {#status-draft}

This is the most common cause. If you do not set a `status` attribute when creating your document, it defaults to `draft` and **no generation takes place**. Since the document is never generated, there is no file to download and `download_url` stays `null`.

### How to fix it {#fix-status-draft}

Set `"status": "pending"` when you create the document to queue generation immediately:

```json
{
  "document": {
    "document_template_id": "YOUR_TEMPLATE_ID",
    "status": "pending",
    "payload": {
      "name": "Jane Doe"
    }
  }
}
```

You can also update an existing draft document by sending a PATCH request with `"status": "pending"`. See the [Documents API reference](https://pdfmonkey.io/docs/api/documents.md) for details.

> [!TIP]
> Setting `&#34;status&#34;: &#34;pending&#34;` at creation time is the most common pattern for API integrations. It skips the draft step entirely and queues generation in a single request.

## The document status is "pending" or "generating" {#status-pending-generating}

If you set `"status": "pending"` when creating the document, generation is queued but may not be finished yet. The API response to your creation request returns the document in `pending` or `generating` status; the `download_url` is `null` at this point because the file does not exist yet.

### How to fix it {#fix-status-pending}

Wait for generation to complete before reading the URL. You have three options:

| Approach | How it works | Best for |
|:---------|:-------------|:---------|
| **Webhook** | PDFMonkey sends a POST to your endpoint when the document reaches `success` or `failure`. | Production integrations |
| **Polling** | Fetch the document in a loop until `status` is `success` or `failure`. | Simple scripts, prototyping |
| **Sync endpoint** | `POST /api/v1/documents/sync` creates the document and waits for the result in a single request (6-minute timeout). | Low-volume, latency-tolerant workflows |

See [Webhooks](https://pdfmonkey.io/docs/generating-documents/webhooks.md) and [Synchronous Generation](https://pdfmonkey.io/docs/api/documents.md#synchronous-generation) for setup instructions.

## The document status is "failure" {#status-failure}

If generation failed, the document status is `failure` and `download_url` is `null`. The `failure_cause` field contains a human-readable error message, and `generation_logs` provides additional detail.

### How to fix it {#fix-status-failure}

1. Inspect the `failure_cause` and `generation_logs` fields in the API response.
2. Fix the underlying issue in your template or payload.
3. Retry generation by setting the document status back to `"pending"` via a PATCH request.

See [Document Statuses and Lifecycle](https://pdfmonkey.io/docs/generating-documents/document-statuses.md#failure) for common failure causes.

## Don't confuse download_url with preview_url {#preview-url-is-not-download}

> [!WARNING]
> **preview_url is not a download link**
>
> The `preview_url` field renders a visual preview of the document in the browser. It works even for drafts and does **not** trigger a file download. If you need the generated file, use `download_url` instead.
&gt; 
&gt; A good example of `preview_url` in action is the PDFMonkey Dashboard itself: when you create a document, the preview panel on the right uses `preview_url` to show what the output looks like before you generate it.
&gt; 
&gt; See [Embedding a Document Preview](https://pdfmonkey.io/docs/generating-documents/embedding-a-preview.md) to learn how to use `preview_url` in your own application.

## Frequently asked questions {#faq}

**I set status to "pending" but the download URL is still null.**

The creation response returns the document before generation is complete. You need to wait for the status to reach `success` by polling the API, using a webhook, or using the [sync endpoint](https://pdfmonkey.io/docs/api/documents.md#synchronous-generation).

**How long does generation take?**

Most documents are generated within a few seconds. Complex templates with many pages, heavy images, or external assets can take longer. The sync endpoint has a 6-minute timeout.

**Can I get the download URL without polling?**

Yes. Set up a [webhook endpoint](https://pdfmonkey.io/docs/generating-documents/webhooks.md) to receive a notification when generation succeeds. The webhook payload includes the `download_url`. Alternatively, use the [sync endpoint](https://pdfmonkey.io/docs/api/documents.md#synchronous-generation) to wait for the result in a single request.

## Related pages {#related-pages}

- [Document Statuses and Lifecycle](https://pdfmonkey.io/docs/generating-documents/document-statuses.md) — understand the draft, pending, generating, success, and failure statuses
- [Download URL](https://pdfmonkey.io/docs/generating-documents/download-url.md) — how temporary signed URLs work and when they expire
- [Generate Documents with the API](https://pdfmonkey.io/docs/generating-documents/api-pdf-generation.md) — end-to-end guide to creating documents via the API
- [Webhooks](https://pdfmonkey.io/docs/generating-documents/webhooks.md) — receive notifications when generation completes
- [Synchronous Generation](https://pdfmonkey.io/docs/api/documents.md#synchronous-generation) — create and wait for the result in one request
- [The Download URL Gives a 403 Error](https://pdfmonkey.io/docs/troubleshooting/download-url-gives-403.md) — how to handle expired URLs


## FAQ

**Why is the PDFMonkey download URL empty or null?**

The download_url field is null whenever the document has not reached the "success" status. The most common cause is forgetting to set status to "pending" when creating the document, which leaves it in "draft" and skips generation entirely. Set status to "pending", then poll for completion or use a webhook.

**How do I get a download URL from PDFMonkey?**

Create a document with status set to "pending" to queue generation. Once the status reaches "success", the download_url field contains a temporary signed URL valid for 1 hour. You can poll the API, use a webhook, or use the synchronous /api/v1/documents/sync endpoint.


---

# Why Does My PDFMonkey Download URL Return a 403 Error?

Source: https://pdfmonkey.io/docs/troubleshooting/download-url-gives-403.md
If you try to access a document's download URL and receive a **403 Forbidden** error, the URL has expired.

## Why this happens {#why-this-happens}

Download URLs are temporary [signed links](https://pdfmonkey.io/docs/generating-documents/download-url.md) valid for **1 hour** after they are generated. Once that time passes, the URL stops working and returns a 403 error. This is expected behavior: the URL is designed to be short-lived for security.

Every time you fetch a document's details (via the API, an integration, or the Dashboard), you receive a **fresh download URL** with a new 1-hour window. The generated file itself remains available on PDFMonkey's servers until it is [deleted](https://pdfmonkey.io/docs/generating-documents/retention-and-deletion.md); only the signed URL expires.

## How to fix it {#how-to-fix-it}

Fetch the document again to get a fresh download URL. You do **not** need to regenerate the document.

### Via the API {#fix-api}

Send a GET request to retrieve the document. The response includes a new `download_url`:

```bash
curl https://api.pdfmonkey.io/api/v1/documents/YOUR_DOCUMENT_ID \
  -H "Authorization: Bearer YOUR_SECRET_API_KEY"
```

See the [Documents API reference](https://pdfmonkey.io/docs/api/documents.md) for the full response format.

### Via an integration {#fix-integration}

Use a "Get Document" or "Find Document" action in [Zapier](https://pdfmonkey.io/docs/integrations/zapier.md), [Make](https://pdfmonkey.io/docs/integrations/make.md), [n8n](https://pdfmonkey.io/docs/integrations/n8n.md), or another platform to refresh the URL.

### Via the Dashboard {#fix-dashboard}

Open the document in the [Dashboard](https://pdfmonkey.io/docs/generating-documents/using-the-dashboard.md). The download link shown on the document detail page is always current.

### Via the Ruby SDK {#fix-ruby-sdk}

Call `document.reload!` to fetch the latest attributes, including a fresh `download_url`:

```ruby
document = PdfMonkey::Document.find("YOUR_DOCUMENT_ID")
document.reload!
document.download_url  # => fresh URL valid for 1 hour
```

See the [Ruby SDK documentation](https://pdfmonkey.io/docs/integrations/ruby-sdk.md) for setup instructions.

## How to avoid this {#how-to-avoid-it}

- **Download immediately after generation.** When you receive a [webhook](https://pdfmonkey.io/docs/generating-documents/webhooks.md) notification or poll for completion, download the file right away rather than storing the URL for later.
- **Store the file, not the URL.** If you need the generated file later, save it to your own storage (S3, Google Drive, etc.) instead of relying on the temporary PDFMonkey download URL.
- **Use share links for permanent access.** If you need a stable URL to share in emails or embed in web pages, enable [Share Links](https://pdfmonkey.io/docs/generating-documents/share-links.md) (available on Pro+ and Premium plans). Unlike download URLs, share links never expire.
- **Re-fetch when needed.** If none of the above apply and you need the file later, fetch the document details again to get a fresh URL. It takes a single GET request.

## Frequently asked questions {#faq}

**Does the 403 error mean my document was deleted?**

Not necessarily. A 403 means the signed URL expired, not that the file is gone. Fetch the document again via the API; if you get a new `download_url`, the file is still available. If the document has been deleted (via [TTL](https://pdfmonkey.io/docs/generating-documents/retention-and-deletion.md) or manually), the API returns a 404 instead.

**How long exactly is a download URL valid?**

Exactly 1 hour from the moment the URL is generated (when you fetch the document details). The clock does not start from when the document was created or when generation completed.

**Does this apply to image output too?**

Yes. Download URLs work the same way regardless of [output format](https://pdfmonkey.io/docs/generating-documents/output-format.md) (PDF, PNG, JPG, or WebP). They all expire after 1 hour.

**Can I extend the expiration time?**

No. The 1-hour duration is fixed and cannot be configured. If you need longer-lived links, use [Share Links](https://pdfmonkey.io/docs/generating-documents/share-links.md) or save the file to your own storage.

## Related pages {#related-pages}

- [The Download URL](https://pdfmonkey.io/docs/generating-documents/download-url.md) — how temporary signed URLs work and when they expire
- [The Download URL Is Empty](https://pdfmonkey.io/docs/troubleshooting/download-url-is-empty.md) — fix a `null` download URL (different issue from 403)
- [Share Links](https://pdfmonkey.io/docs/generating-documents/share-links.md) — permanent public URLs that never expire
- [Webhooks](https://pdfmonkey.io/docs/generating-documents/webhooks.md) — get notified the moment a document is ready to download
- [Retention and Automatic Deletion](https://pdfmonkey.io/docs/generating-documents/retention-and-deletion.md) — how long files are stored before cleanup
- [Document Statuses and Lifecycle](https://pdfmonkey.io/docs/generating-documents/document-statuses.md) — understand when `download_url` becomes available
- [API Documents reference](https://pdfmonkey.io/docs/api/documents.md) — full endpoint and field documentation


## FAQ

**Why does the PDFMonkey download URL give a 403 error?**

Download URLs expire after 1 hour. Fetch the document again via the API, an integration, or the Ruby SDK to get a fresh URL with a new 1-hour window.

**How do I get a new download URL after it expires?**

Fetch the document again via the API (GET /api/v1/documents/:id), through an integration like Zapier or Make, or in the Dashboard. Each fetch returns a fresh URL valid for 1 hour. You do not need to regenerate the document.

**Can I get a permanent download link that never expires?**

Yes. Enable Share Links on Pro+ or Premium plans to get a permanent public URL for each document. Unlike download URLs, share links do not expire.


---

# Why Is My Data Not Showing in a PDFMonkey Document?

Source: https://pdfmonkey.io/docs/troubleshooting/data-not-showing.md
When dynamic data does not appear in a generated document, the cause is almost always a mismatch between the variable names in your template and the keys in the JSON payload you send. This page covers every common cause and how to fix each one.

## Variable names do not match payload keys {#variable-name-mismatch}

This is the most common cause. The variable name in your template must match the corresponding key in your JSON payload **exactly**.

If your template contains:

```liquid
{{ someVariable }}
```

Your Document payload must include a matching key:

```json
{
  "someVariable": "Some value"
}
```

If the key is missing, misspelled, or uses different casing, the variable renders as blank.

### How to fix it {#fix-variable-name-mismatch}

1. Open your template and note the exact variable names used.
2. Compare them against the keys in the JSON payload you send when creating the document.
3. Fix any differences in spelling or structure.

> [!TIP]
> **Use the test data tab to verify**
>
> Paste the exact JSON payload you intend to send into the **Test data** tab of your template editor. If the preview renders correctly with that data, the variable names match. If data is still missing in the generated document, the issue is with the payload sent via the API, not with the template itself.

## Variable names are case-sensitive {#case-sensitivity}

Variable names are case-sensitive in both Code (Liquid) and Builder (Vue) templates. `firstName`, `firstname`, and `FirstName` are three different variables.

**Template:**

```liquid
{{ firstName }}
```

**Payload (wrong):**

```json
{
  "firstname": "Jane"
}
```

**Payload (correct):**

```json
{
  "firstName": "Jane"
}
```

### How to fix it {#fix-case-sensitivity}

Pick a consistent naming convention (camelCase is common) and use it in both your template and your API integration. Double-check for subtle differences such as `orderId` vs `orderID` or `fullName` vs `fullname`.

## Nested data requires dot notation {#nested-data}

If your payload contains nested objects, you need to traverse the structure with dot notation in your template.

**Payload:**

```json
{
  "client": {
    "name": "Jane Doe",
    "address": {
      "city": "Paris"
    }
  }
}
```

**Template (Code/Liquid):**

```liquid
{{ client.name }}
{{ client.address.city }}
```

Writing `{{ name }}` or `{{ city }}` alone does not work because those keys exist inside nested objects, not at the top level.

### How to fix it {#fix-nested-data}

Make sure the path you use in the template follows the full nesting structure of your payload. See [Using Dynamic Data](https://pdfmonkey.io/docs/code-templates/defining-dynamic-data.md) for more on accessing nested values and arrays.

## The payload is empty or malformed {#empty-payload}

If you create a document without a `payload` (or with `"payload": {}`), every variable evaluates to blank. Similarly, if the JSON is malformed, the entire payload may be ignored.

### How to fix it {#fix-empty-payload}

Verify that your API request includes a valid `payload` object with the data your template expects:

```json
{
  "document": {
    "document_template_id": "YOUR_TEMPLATE_ID",
    "status": "pending",
    "payload": {
      "name": "Jane Doe",
      "items": [{ "description": "Widget", "price": 9.99 }]
    }
  }
}
```

> [!WARNING]
> **Check your JSON syntax**
>
> A stray comma, unquoted key, or missing bracket can make the payload unparseable. Validate your JSON with a linter or tool like [jsonlint.com](https://jsonlint.com) before sending the request.

## Builder templates use Vue, not Liquid {#builder-templates}

Builder templates use Vue expressions, not Liquid. The same principle applies (variable names must match payload keys), but the syntax is different.

In a Builder template, dynamic data is accessed through the `$docPayload` object. Simple variables look identical to Liquid:

```
{{ name }}
```

But if a variable name **starts with a number** or contains special characters, it is not a valid JavaScript identifier and cannot be used directly. Use bracket notation instead:

```
{{ $docPayload['123varname'] }}
```

### How to fix it {#fix-builder-templates}

1. Confirm that the variable names in your Builder expressions match the keys in your test data or API payload.
2. For keys that are not valid JavaScript identifiers, use `$docPayload['key']` bracket notation.
3. Check that any **conditions** or **repetitions** on your components reference existing payload keys.

See [Builder vs. Code Templates](https://pdfmonkey.io/docs/getting-started/builder-vs-code-templates.md#the-builder-does-not-use-liquid) for more details on the syntax differences.

## The template is not published {#template-not-published}

If you recently changed variable names in your template but did not publish, the generated document still uses the old published version. This can make it look like data is missing when the real issue is that the published template expects different variable names.

### How to fix it {#fix-template-not-published}

Click **Publish** in the template editor after making changes, then generate the document again. See [Why Is My Document Blank?](https://pdfmonkey.io/docs/troubleshooting/document-is-blank.md#template-not-published) for a detailed explanation of the draft vs. published distinction.

## Frequently asked questions {#faq}

**I can see data in the preview but it is missing in the generated document.**

The preview uses the **draft** version of your template and the **test data** you defined. The generated document uses the **published** version and the **payload** you sent via the API. Make sure you have published the template and that the API payload matches the test data structure.

**My variable renders as the literal text `{{ someVariable }}` instead of its value.**

In Code templates, this means the Liquid engine did not process the variable. Check that the double curly braces have no extra characters (such as a leading backslash or mismatched braces). In Builder templates, this should not happen unless the text is inside a raw HTML block that bypasses Vue rendering.

**How do I debug which data PDFMonkey received?**

Create a document with `"status": "pending"` and then fetch it via the API. The response includes the `payload` field, which shows the exact data PDFMonkey received. Compare it against what your template expects.

**Are arrays and objects supported in the payload?**

Yes. You can pass arrays and nested objects in your payload and access them in your template. See [Using Dynamic Data](https://pdfmonkey.io/docs/code-templates/defining-dynamic-data.md) for Liquid syntax examples with arrays and objects.

## Related pages {#related-pages}

- [Using Dynamic Data](https://pdfmonkey.io/docs/code-templates/defining-dynamic-data.md) — define test data, access nested values, and name variables correctly
- [Naming Variables](https://pdfmonkey.io/docs/code-templates/defining-dynamic-data.md#naming-your-variables) — naming conventions and rules
- [Builder vs. Code Templates](https://pdfmonkey.io/docs/getting-started/builder-vs-code-templates.md) — understand the syntax differences between Liquid and Vue
- [Why Is My Document Blank?](https://pdfmonkey.io/docs/troubleshooting/document-is-blank.md) — when the entire document is empty, not just specific data
- [Generate Documents with the API](https://pdfmonkey.io/docs/generating-documents/api-pdf-generation.md) — full API payload examples
- [Document Statuses and Lifecycle](https://pdfmonkey.io/docs/generating-documents/document-statuses.md) — understand when generation happens


## FAQ

**Why is my data not showing up in the PDFMonkey document?**

The variable names in your template must match the keys in your JSON payload exactly, including case. For example, if your template uses {{firstName}}, your payload must include a "firstName" key — not "firstname" or "FirstName".

**How do I access nested data in a PDFMonkey template?**

In Code templates (Liquid), use dot notation: {{client.name}}. In Builder templates (Vue), use the same dot notation: {{client.name}}. Your JSON payload must include the nested structure: {"client": {"name": "Jane Doe"}}.

**Are PDFMonkey template variable names case-sensitive?**

Yes. Variable names are case-sensitive in both Code (Liquid) and Builder (Vue) templates. The key in your JSON payload must match the variable name exactly, including capitalization.