This add-on is operated by Sivije

Build templates with HTML and use a simple REST API to generate PDF documents

Last updated 11 August 2020

PDFMonkey is an add-on for providing easy, API-based generation of PDF documents. You can generate any document your business needs, including invoices, contracts, reports, and flyers.

PDFMonkey is accessible through a REST API and provides integration options for a variety of languages. Examples are included for Ruby and cURL.

Provisioning the add-on

PDFMonkey can be attached to a Heroku application via the CLI:

$ heroku addons:create pdfmonkey
-----> Adding pdfmonkey to immense-journey-80008... done, v42 (free)

Once PDFMonkey is provisioned, a PDFMONKEY_PRIVATE_KEY config var is added to your app. It contains the private key you use to call the PDFMonkey REST API. You can confirm this value using the heroku config:get command:

$ heroku config:get PDFMONKEY_PRIVATE_KEY
6e51345c7cdee7ad0f1566ce

Local environment setup

After provisioning the add-on, you need to replicate its config vars locally so your development environment can operate against the service.

Use the heroku local command to run your app locally. This command reads config vars from your app’s .env file. To view all of your app’s config vars, type heroku config. Use the following command to add the PDFMONKEY_PRIVATE_KEY value retrieved from heroku config to add to your .env file:

$ heroku config -s | grep PDFMONKEY_PRIVATE_KEY >> .env
$ more .env

For more information, see the Heroku Local article.

Using with Ruby

Ruby applications can add the following entry to their Gemfile to include the pdfmonkey gem:

gem 'pdfmonkey'

Then update application dependencies with bundler:

$ bundle install

Before generating a document, you need to get a Template ID from the PDFMonkey Dashboard. Once you have it you can use the gem.

Synchronous generation

If you want your application’s logic to wait for document generation to complete before continuing, use the generate! method. This method initiates a document generation and waits for it to succeed or fail before returning.

tempalte_id = 'YOUR_TEMPLATE_ID'
data = { name: 'John Doe' }

document = Pdfmonkey::Document.generate!(template_id, data)

document.status       # => 'success'
document.download_url # => 'https://…'

Asynchronous generation

If you want to generate documents asynchronously, PDFMonkey provides webhooks that notify you when document generation succeeds or fails.

To initiate an asynchronous document generation, use the generate method:

tempalte_id = 'b13ebd75-d290-409b-9cac-8f597ae3e785'
data = { name: 'John Doe' }

document = Pdfmonkey::Document.generate(template_id, data)

document.status # => 'pending'
document.download_url # => nil

If you’ve specified a webhook URL, PDFMonkey sends it a POST request with a Content-Type: application/json header when generation completes or fails. The body of this request has the following structure:

{
  "document": {
    "id": "4204eff8-3126-4ec7-a5f9-aa8ed5b8517b",
    "status": "success",
    "app_id": "d9ec8249-65ae-4d50-8aee-7c12c1f9683a",
    "document_template_id": "b13ebd75-d290-409b-9cac-8f597ae3e785",
    "payload": "{\"name\":\"John Doe\"}",
    "checksum": "6dc8942e10f93b1e22d4b18bdf04e2f3",
    "download_url": "https://….pdf",
    "preview_url": null,
    "meta": null,
    "created_at": "2018-12-04T20:28:35.072+01:00",
    "updated_at": "2018-12-04T20:28:38.899+01:00"
  }
}

You can then create a Document object from this JSON payload with the following command:

document = Pdfmonkey::Document.new(params[:document])

Using with cURL

If you want to use the PDFMonkey API in a language for which no integration exist yet, you can use requests like the ones that follow.

Creating a document with a POST request

$ curl https://api.pdfmonkey.io/api/v1/documents \
    -X POST \
    -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer YOUR_PDFMONKEY_PRIVATE_KEY' \
    -d '{
      "document": {
        "document_template_id": "YOUR_TEMPLATE_ID",
        "payload": "{\"name\":\"John Doe\"}",
        "status": "pending"
      }
    }'

Expected JSON result:

{
  "document": {
    "id": "4204eff8-3126-4ec7-a5f9-aa8ed5b8517b",
    "status": "pending",
    "app_id": "d9ec8249-65ae-4d50-8aee-7c12c1f9683a",
    "document_template_id": "b13ebd75-d290-409b-9cac-8f597ae3e785",
    "payload": "{\"name\":\"John Doe\"}",
    "checksum": "6dc8942e10f93b1e22d4b18bdf04e2f3",
    "download_url": null,
    "preview_url": null,
    "meta": null,
    "created_at": "2018-12-04T20:28:35.072+01:00",
    "updated_at": "2018-12-04T20:28:38.899+01:00"
  }
}

Fetching a document with a GET request

$ curl https://api.pdfmonkey.io/api/v1/documents/4204eff8-3126-4ec7-a5f9-aa8ed5b8517b \
    -H 'Authorization: Bearer YOUR_PDFMONKEY_PRIVATE_KEY'

Expected JSON result:

{
  "document": {
    "id": "4204eff8-3126-4ec7-a5f9-aa8ed5b8517b",
    "status": "success",
    "app_id": "d9ec8249-65ae-4d50-8aee-7c12c1f9683a",
    "document_template_id": "b13ebd75-d290-409b-9cac-8f597ae3e785",
    "payload": "{\"name\":\"John Doe\"}",
    "checksum": "6dc8942e10f93b1e22d4b18bdf04e2f3",
    "download_url": "https://….pdf",
    "preview_url": null,
    "meta": null,
    "created_at": "2018-12-04T20:28:35.072+01:00",
    "updated_at": "2018-12-04T20:28:38.899+01:00"
  }
}

Dashboard

The PDFMonkey dashboard allows you to create, edit, and delete your templates. You can also use it to generate documents manually if necessary.

The dashboard can be accessed via the CLI:

$ heroku addons:open pdfmonkey
Opening pdfmonkey for immense-journey-80008...

or by visiting the Heroku Dashboard and selecting the application in question. Select PDFMonkey from the Add-ons menu.

Migrating between plans

Use the heroku addons:upgrade command to migrate to a new plan.

$ heroku addons:upgrade pdfmonkey:nano-monkey
-----> Upgrading pdfmonkey:nano-monkey to immense-journey-80008... done, v42 ($6/mo)
       Your plan has been updated to: pdfmonkey:nano-monkey

Removing the add-on

PDFMonkey can be removed via the CLI.

$ heroku addons:destroy pdfmonkey
-----> Removing pdfmonkey from immense-journey-80008... done, v43 (free)

Support

All PDFMonkey support and runtime issues should be submitted via one of the Heroku Support channels. Any non-support related issues or product feedback is welcome at support@pdfmonkey.io.