# Bubble Integration: Generate Documents in Bubble


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](../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](../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-1634904776187x632941607749681200) 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](../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 Pro+ and Premium plans and during the 30-day trial) |
| **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'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'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](../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 `"status": "pending"` for PDFMonkey to start generating the document immediately. If you omit it or set it to `"draft"`, the document is created but not generated. See [Document Statuses](../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](../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](../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](../generating-documents/download-url.md) expires after 1 hour. If you need a permanent link, use a [share link](../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](./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](../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](../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](../generating-documents/share-links.md) for permanent access.

For more details, see [Download URL Returns 403](../troubleshooting/download-url-gives-403.md).

## Next Steps {#next-steps}

- [From Zero to First Document](../getting-started/from-zero-to-first-document.md): Set up your PDFMonkey account and create your first template
- [Defining Dynamic Data](../code-templates/defining-dynamic-data.md): Learn how to structure the JSON payload for your templates
- [Document Statuses](../generating-documents/document-statuses.md): Understand the lifecycle of a generated document
- [Webhooks](../generating-documents/webhooks.md): Receive real-time notifications when documents finish generating
- [Download URL](../generating-documents/download-url.md): How download URLs work and when they expire
- Explore other integrations: [Zapier](./zapier.md), [Make](./make.md), [n8n](./n8n.md)
