Generating a document using our API

Libraries

As of today, we provide the following libraries:

Authentication

In order to generate a PDF through the API, you’ll need to grab your API KEY first.

Head to the My account page using the top-right menu.

Toggle your API KEY by clicking on the Display value link below the API SECRET KEY field and copy your key.

You can then use this key to authenticate every call to the API:

# Method 1: Use the PDFMONKEY_PRIVATE_KEY environment variable.
# No code needed.

# Method 2: Set the private key manually (this will generally go in an initializer).
Pdfmonkey.configure do |config|
  config.private_key = '[API KEY]'
end
curl 'https://api.pdfmonkey.io/api/v1/documents' \
  -H 'Authorization: Bearer [API KEY]'

Get your template ID

Every template has a unique ID that you can copy from the Templates page:

You’re now ready to generate a document!

Generate a document

Here is a code snippet you can use to generate a document:

template_id = '[TEMPLATE ID]'
data = { name: 'Jane Doe' }


# Wait for document generation automatically with `generate!`

document = Pdfmonkey::Document.generate!(template_id, data)
document.status
#=> "success"


# Wait for document generation manually with `generate`

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

until document.done?
  puts 'Waiting 1s…'
  sleep 1
  document.reload!
end

document.status
#=> "success"
# IMPORTANT!
# A "pending" status will tell PDFMonkey to generate your document upon creation.
# Don’t forget it!

curl 'https://api.pdfmonkey.io/api/v1/documents' \
  -H 'Authorization: Bearer [API KEY]' \
  -H 'Content-Type: application/json' \
  -d '{
        "document": {
          "document_template_id": "[TEMPLATE ID]",
          "payload": "{ \"name\": \"Jane Doe\" }",
          "status": "pending"
        }
      }'

Be careful to replace [API KEY] and [TEMPLATE ID] with the corresponding information.

The document object

The document you’ll get in return will look like this:

#<Pdfmonkey::Document
  id="d2f2de44-9de7-4dd8-90f4-bee5e99c9984"
  status="generating"
  app_id="e87c71ac-06c2-473c-a49b-98794a340255"
  checksum="7ddb1dc96435ec5f58b31db23b43cfcf"
  created_at="2042-01-02T01:23:45.678+02:00"
  document_template_id="[TEMPLATE ID]"
  download_url="https://..."
  errors=nil
  meta=nil
  payload="{\"name\":\"Jane Doe\"}"
  preview_url="https://..."
  updated_at="2042-01-02T01:23:46.012+02:00">
{
  "document" : {
    "id": "d2f2de44-9de7-4dd8-90f4-bee5e99c9984",
    "status": "generating",
    "app_id": "e87c71ac-06c2-473c-a49b-98794a340255",
    "checksum": "7ddb1dc96435ec5f58b31db23b43cfcf",
    "created_at": "2042-01-02T01:23:45.678+02:00",
    "document_template_id": "[TEMPLATE ID]",
    "download_url": "https://...",
    "errors": null,
    "meta": null,
    "payload": "{\"name\":\"Jane Doe\"}",
    "preview_url": "https://...",
    "updated_at": "2042-01-02T01:23:46.012+02:00"
  }
}

Statuses

Here is the complete list of statuses a document can have:

draft
The document can be previewed and edited
pending
The document has been queued for generation
generating
The document is currently being generated
success
The document is now generated and can be downloaded
failure
The generation failed for some reason

Waiting for generation

To check if your document is done generating, call the API again to get your document payload:

# This will refresh document’s data.
document.reload!

document.status
# => "generating"

# You can reload until you get a "success" or "failure" status indicating
# that the generation is complete.

until document.done?
  document.reload!
end

document.status
# => "success"
curl 'https://api.pdfmonkey.io/api/v1/documents/d2f2de44-9de7-4dd8-90f4-bee5e99c9984' \
  -H 'Authorization: Bearer [API KEY]'

# You will get the same payload again.
# Retry until its status changes to "success" or "failure".

When your document is generated, its attributes will include a download_url.

This URL will be valid for 30 seconds, afterward you’ll need to call the API again to get a new one.

Visit the download_url to get your document. That’s it!

Customizing the file name

When generating a Document using the API, you can customize the generated file name. This can be very useful when you want to send the Document by email or save it in Dropbox for instance.

To do so, provide the special _filename property the the meta of the Document:

template_id = '[TEMPLATE ID]'
data = { name: 'Jane Doe' }
meta = { _filename: 'pdf-for-jane-doe.pdf' }

# The meta argument was added in v0.4.0 of the pdfmonkey gem
document = Pdfmonkey::Document.generate!(template_id, data, meta)
curl 'https://api.pdfmonkey.io/api/v1/documents' \
  -H 'Authorization: Bearer [API KEY]' \
  -H 'Content-Type: application/json' \
  -d '{
        "document": {
          "document_template_id": "[TEMPLATE ID]",
          "meta": "{ \"_filename\": \"pdf-for-jane-doe.pdf\" }",
          "payload": "{ \"name\": \"Jane Doe\" }",
          "status": "pending"
        }
      }'