# HTML to PDF in Bubble with the API Connector

Set up html-pdf.com in Bubble's API Connector, generate a PDF from your page's data, save it to a file field and email it. Includes fixes for common errors.

**Quick answer.** Add an API in the **API Connector** with **Private key in header** (`Authorization` = `Bearer hp_live_...`). Add a call with these settings, initialize it, and use it as a workflow action.

- **Use as:** `Action`
- **Data type:** `File`
- **Method / URL:** `POST` `https://html-pdf.com/v1/pdf`
- **Body (JSON):** `{"html": <html>, "format": "A4"}`

Why File and when to use a link instead is explained on the [HTML to PDF in Bubble](https://html-pdf.com/bubble-html-to-pdf) overview.

## Get an API key

This step gives you a key. Get one by email at https://html-pdf.com/login, or with one call:

```bash
curl -X POST https://html-pdf.com/v1/signup \
  -H "Content-Type: application/json" \
  -d '{"email": "you@example.com"}'
```

Then open the link we email you to confirm your address. That adds the 100 free credits. 1 credit = 1 PDF page, and no card is needed.

## Add the API

Install the **API Connector** plugin (made by Bubble) from the Plugins tab, then click **Add another API**.

- **API Name:** `html-pdf`
- **Authentication:** `Private key in header`
- **Key name:** `Authorization`
- **Private key:** `Bearer hp_live_...` (the word `Bearer`, a space, then your key)

API Connector calls run through Bubble's server, so the key never reaches your users' browsers.

## Add the call

Click **Add another call** and name it `Render PDF`.

- **Use as:** `Action`
- **Data type:** `File`
- **Method / URL:** `POST` `https://html-pdf.com/v1/pdf`
- **Headers:** `Content-Type` = `application/json`
- **Body type:** `JSON`

Paste this body.

```json
{
  "html": <html>,
  "format": "A4",
  "margin": "15mm",
  "filename": "voucher.pdf",
  "max_pages": 5
}
```

`<html>` becomes a parameter below the body. Uncheck **Private** next to it so workflows can set it. Don't put quotes around `<html>`, because the value you pass later brings its own.

## Initialize the call

Bubble sends one real request to learn what comes back. It uses 1 credit.

Give the `html` parameter a test value, with the quotes, since it is raw JSON at this point.

```json
"<h1>Hello from Bubble</h1>"
```

Click **Initialize call**. With the File data type, Bubble saves the returned PDF to your app's storage. Use only sample data here, because Bubble keeps the test value in your app.

Want a 24-hour link instead? Add `"response": "url"` to the body, set **Data type** to `JSON`, and initialize again. Bubble then detects `url`, `pages`, `credits_remaining` and `expires_at`.

## Build the workflow

This example makes a gift voucher. It assumes a `Voucher` data type with `recipient`, `amount`, `code` and a file field `pdf`.

1. **Plugins → html-pdf - Render PDF.** For `html`, choose **Arbitrary text** and write the HTML, inserting dynamic data where needed, for example `<h1>Gift voucher</h1><p>For Current Page Voucher's recipient</p><p>Code: Current Page Voucher's code</p>`. Then add `:formatted as JSON-safe` after the Arbitrary text.
2. **Make changes to a thing** on the voucher. Set `pdf` to `Result of step 1`, the file Bubble saved.
3. **Send email** to the customer, with `Result of step 1` in **Attachments**.

With the link response, step 2 isn't needed. Use **Open an external website** with `Result of step 1's url`, or put that link in the email body.

## Keep PDFs small

Bubble refuses responses over 50 MB, and one email can carry 19 MB of attachments. Most PDFs are well under 1 MB. Large ones come from images.

- **Resize images before inserting them.** A phone photo can be 5 MB or more and keeps its full resolution in the PDF. Bubble's `:processed with Imgix` operator can serve images from your Bubble storage at a smaller size.
- **Prefer JPEG for photos.** PNG photos are much heavier. Use SVG for logos.
- **Set `max_pages`.** A runaway list stops the render, and you aren't charged.
- **Use `scale`** (0.1 to 2) to fit wide content on fewer pages, which also costs fewer credits.

## Troubleshooting

Most problems come from the key, the JSON or the response type.

- **401 `missing_api_key` or `invalid_api_key`:** check the **Private key** value. It must be `Bearer ` followed by the full key.
- **403 `email_not_confirmed`:** open the confirmation email we sent, then try again.
- **402 `insufficient_credits`:** top up at https://html-pdf.com/dashboard. Check **Include errors in response and allow workflow actions to continue** on the call to handle it in your workflow. Failed renders are free.
- **400 `invalid_json`:** a quote or line break broke the body. Apply `:formatted as JSON-safe` to the whole HTML, and leave the quotes off `<html>`. A misspelled option name also gives this error.
- **Images missing:** Bubble file links often start with `//`. Write `https:` in front of the dynamic image URL.
- **"response too large":** the PDF is over Bubble's 50 MB limit. Shrink the images, or switch to `"response": "url"`.
- **Initialization fails or shows garbled text:** the data type is JSON or Text, but the body has no `response`, so the API sends a PDF. Set the data type to File, or add `"response": "url"`.

## FAQ

### Can I add page numbers?

Yes. Add `"footer_html": "<div style='font-size:9px;width:100%;text-align:center'><span class='pageNumber'></span> / <span class='totalPages'></span></div>"` to the body and keep a bottom margin so the footer has room.

### How do I email the PDF from Bubble?

Use the file response, then add `Result of step 1` to the **Attachments** of the **Send email** action. Bubble only attaches files stored in your app's storage, up to 19 MB in total.

### Can I generate PDFs in a backend workflow?

Yes. API Connector actions work in backend workflows, so you can create PDFs on a schedule or when data changes.

### How many credits does a PDF cost?

One credit per page. A 3-page invoice uses 3 credits. New accounts get 100 free credits, and purchased credits never expire.

Full reference: [API docs](https://html-pdf.com/docs) · [HTML templates](https://html-pdf.com/templates)
