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"
}
}'
PDFMonkey