Ruby SDK
We provide a Ruby SDK to connect to PDFMonkey. This gem is the quickest way to use our API with Ruby.

Installation

Add this line to your application’s Gemfile:
Gemfile
1
gem 'pdfmonkey'
Copied!
And then execute:
1
$ bundle
Copied!
Or install it yourself as:
1
$ gem install pdfmonkey
Copied!

Usage

Setting up authentication

Using the default environment variables

PDFMonkey will look for the PDFMONKEY_PRIVATE_KEY environment variable. This variable should contain your private key obtained at https://dashboard.pdfmonkey.io/account.
1
PDFMONKEY_PRIVATE_KEY=j39ckj4…
Copied!

Setting credentials manually

You can choose to set up your credentials explicitely in your application:
1
Pdfmonkey.configure do |config|
2
config.private_key = 'j39ckj4…'
3
end
Copied!

Generating a document

Once your App is created in the PDFMonkey Dashboard, create a Document Template and add the content you want to use. Every Document Template has a unique identifier (UUID), get your template’s identifier. Your ready to generate a Document.

Synchronous generation

If your want to wait for a Document’s generation before continuing with your workflow, use the generate! method, it will request a document generation and wait for it to succeed or fail before giving you any answer.
1
template_id = 'b13ebd75-d290-409b-9cac-8f597ae3e785'
2
data = { name: 'John Doe' }
3
4
document = Pdfmonkey::Document.generate!(template_id, data)
5
6
document.status # => 'success'
7
document.download_url # => 'https://…'
Copied!
The Download URL is temporary
The download URL of a document is only valid for 1 hour. Passed this delay, reload the document to obtain a new one by calling document.reload!

Asynchronous generation

PDFMonkey was created with an asynchronous workflow in mind. It provides webhooks to inform you of a Document’s generation success.
To leverage this behavior and continue working while your Document is generated, use the generate method:
1
template_id = 'b13ebd75-d290-409b-9cac-8f597ae3e785'
2
data = { name: 'John Doe' }
3
4
document = Pdfmonkey::Document.generate(template_id, data)
5
6
document.status # => 'pending'
7
document.download_url # => nil
Copied!
If you have a webhook URL set up it will be called with you document once the generation is complete. You can simulate it for testing with the following cURL command:
1
curl <url of your app> \
2
-X POST \
3
-H 'Content-Type: application/json' \
4
-d '{
5
"document": {
6
"app_id": "d9ec8249-65ae-4d50-8aee-7c12c1f9683a",
7
"checksum": "ac0c2b6bcc77e2b01dc6ca6a9f656b2d",
8
"created_at": "2020-01-02T03:04:05.000+01:00",
9
"document_template_id": "f7fbe2b4-a57c-46ee-8422-5ae8cc37daac",
10
"download_url": "https://example.com/76bebeb9-9eb1-481a-bc3c-faf43dc3ac81.pdf",
11
"filename": "76bebeb9-9eb1-481a-bc3c-faf43dc3ac81.pdf",
12
"id": "76bebeb9-9eb1-481a-bc3c-faf43dc3ac81",
13
"meta": null,
14
"payload": "{\"name\": \"John Doe\"}",
15
"preview_url": null,
16
"status": "success",
17
"updated_at": "2020-01-02T03:04:15.000+01:00"
18
}
19
}'
Copied!

Attaching meta data to the document

In addition to the Document’s payload you can add meta data when generating a Document.
This can be done by passing a third argument to the generate! and generate methods:
1
meta = {
2
_filename: 'john-doe-contract.pdf',
3
client_id: '123xxx123'
4
}
5
6
document = Pdfmonkey::Document.generate!(template_id, payload, meta)
7
document.meta
8
# => '{"_filename":"john-doe-contract.pdf","client_id":"123xxx123"}'
9
10
document = Pdfmonkey::Document.generate(template_id, payload, meta)
11
document.meta
12
# => '{"_filename":"john-doe-contract.pdf","client_id":"123xxx123"}'
Copied!

Error handling

In case of error, be it an HTTP layer error or an API error, document.status will be set to 'error' and document.error will contain the error message.
1
# Using an unknown template
2
3
template_id = 'unknown'
4
data = { name: 'John Doe' }
5
6
document = Pdfmonkey::Document.generate(template_id, data)
7
8
document.status # => 'error'
9
document.errors # => ["Document template must exist"]
10
11
# If the network is down
12
document = Pdfmonkey::Document.generate(template_id, data)
13
14
document.status # => 'error'
15
document.errors # => ["Failed to open TCP connection to api.pdfmonkey.io:443 (getaddrinfo: nodename nor servname provided, or not known)"]
Copied!

Fetching a document

You can fetch an existing document using the .fetch method:
1
document = Pdfmonkey::Document.fetch('76bebeb9-9eb1-481a-bc3c-faf43dc3ac81')
Copied!

Error handling

In case of error, be it an HTTP layer error or an API error, document.status will be set to 'error' and document.error will contain the error message.
1
document = Pdfmonkey::Document.fetch('unknown')
2
3
document.status # => 'error'
4
document.errors # => ["We couldn't find any Document with ID \"unknown\"..."]
5
6
# If the network is down
7
document = Pdfmonkey::Document.fetch('95eb0b6e-090b-4195-9b7c-cc3d50099867')
8
9
document.status # => 'error'
10
document.errors # => ["Failed to open TCP connection to api.pdfmonkey.io:443 (getaddrinfo: nodename nor servname provided, or not known)"]
Copied!

Deleting a document

You can delete an existing document using the .delete method:
1
Pdfmonkey::Document.delete('76bebeb9-9eb1-481a-bc3c-faf43dc3ac81')
2
#=> true
Copied!
Alternatively you can call the #delete! method:
1
document.delete!
2
#=> true
Copied!

Error handling

In case of error, be it an HTTP layer error or an API error, an error Hash will be returned.
1
document.delete!
2
#=> true
3
4
document.delete!
5
# {
6
# errors: ["We couldn't find any Document with ID \"11111111-2222-3333-4444-555555555555\". If ..."],
7
# status: "error"
8
# }
9
10
# If the network is down
11
document.delete!
12
# {
13
# errors: ["Failed to open TCP connection to api.pdfmonkey.io:443 (getaddrinfo: nodename nor servname provided, or not known)"],
14
# status: "error"
15
# }
Copied!